Installation

Install HammerIO from PyPI with pip. Requires Python 3.9 or later.

pip install hammerio

For GPU acceleration, ensure you have a CUDA-capable NVIDIA GPU with drivers installed:

# Verify CUDA is available
python -c "import hammerio; print(hammerio.gpu_available())"

Optional Dependencies

  • NVIDIA GPU — Required for nvCOMP LZ4 acceleration. Falls back to CPU zstd automatically.
  • CUDA Toolkit 11.0+ — Bundled with most NVIDIA driver installations.
  • Desktop notifications — pip install hammerio[desktop] for system tray integration.
# Full install with all optional features
pip install hammerio[desktop,dashboard]

CLI Reference

HammerIO provides a command-line interface for compression, decompression, and management tasks.

Compress

# Compress a single file (auto-routes to GPU or CPU)
hammerio compress myfile.dat

# Force GPU engine
hammerio compress --engine gpu myfile.dat

# Force CPU zstd at compression level 9
hammerio compress --engine cpu --level 9 myfile.dat

# Compress a directory recursively
hammerio compress -r /path/to/data/

Decompress

# Decompress a file
hammerio decompress myfile.dat.hio

# Decompress to a specific directory
hammerio decompress -o /output/dir/ myfile.dat.hio

Info and Status

# Show file metadata
hammerio info myfile.dat.hio

# Show system status (GPU availability, engine versions)
hammerio status

# Run built-in benchmark
hammerio benchmark --size 1GB

Watch Daemon

The watch daemon monitors directories and automatically compresses new files as they appear.

# Start watching a directory
hammerio watch /path/to/incoming/

# Watch with specific engine preference
hammerio watch --engine gpu /data/ml-models/

# Run as a background service
hammerio watch --daemon /path/to/incoming/

# Stop the daemon
hammerio watch --stop

Daemon Configuration

The watch daemon can be configured via the config file or environment variables:

# ~/.config/hammerio/config.toml
[watch]
directories = ["/data/incoming", "/data/exports"]
engine = "auto"
notify = true
poll_interval = 2  # seconds
exclude_patterns = ["*.tmp", "*.lock"]

Python API

Full programmatic access to all HammerIO features.

import hammerio

# Simple compression (auto-routed)
hammerio.compress("large_dataset.bin")
hammerio.decompress("large_dataset.bin.hio")

# Explicit engine selection
hammerio.compress("data.bin", engine="gpu")
hammerio.compress("logs.txt", engine="cpu", level=9)

# Check GPU availability
if hammerio.gpu_available():
    print("GPU acceleration is active")

# Batch processing
results = hammerio.compress_batch([
    "file1.dat",
    "file2.dat",
    "file3.dat",
], engine="auto", parallel=True)

for r in results:
    print(f"{r.path}: {r.throughput_mb_s} MB/s")

# Benchmark
report = hammerio.benchmark(size_mb=1024)
print(report.summary())

Context Manager

import hammerio

# Automatic cleanup of temporary compressed files
with hammerio.session() as session:
    session.compress("input.dat", "output.dat.hio")
    # Process compressed data...
    data = session.decompress("output.dat.hio")

Configuration Reference

HammerIO reads configuration from ~/.config/hammerio/config.toml.

# ~/.config/hammerio/config.toml

[general]
default_engine = "auto"        # auto | gpu | cpu
log_level = "info"             # debug | info | warning | error
temp_dir = "/tmp/hammerio"

[gpu]
enabled = true
device_id = 0                  # CUDA device index
memory_limit = "4GB"           # Max GPU memory allocation

[cpu]
default_codec = "zstd"         # zstd | gzip | lz4
default_level = 3              # Compression level
threads = 0                    # 0 = auto-detect

[routing]
large_file_threshold = "500MB"
gpu_file_types = ["*.bin", "*.dat", "*.npy", "*.safetensors"]
cpu_file_types = ["*.txt", "*.log", "*.csv", "*.json"]
passthrough_types = ["*.zip", "*.gz", "*.bz2", "*.xz", "*.zst"]

[notifications]
enabled = true
sound = false

[dashboard]
enabled = false
port = 8420
host = "127.0.0.1"

Right-Click Integration

Install the file manager context menu integration for desktop compression.

Linux (Nautilus / Nemo / Thunar)

# Install for the current user
hammerio install --desktop

# This adds context menu entries for:
# - "Compress with HammerIO"
# - "Decompress with HammerIO"

Windows

# Run as Administrator
hammerio install --desktop --windows

# Adds right-click entries in Windows Explorer

Uninstall

hammerio install --desktop --uninstall

Hardware Compatibility

HammerIO automatically detects available hardware and falls back gracefully.

GPU Requirements

  • NVIDIA GPU with Compute Capability 7.0+ (Volta or newer)
  • NVIDIA driver 470+ installed
  • Minimum 2 GB GPU memory (4 GB+ recommended for large files)
  • CUDA 11.0+ (bundled with driver)

Supported GPUs

  • NVIDIA Jetson (Orin, Xavier)
  • NVIDIA GeForce RTX 20xx, 30xx, 40xx, 50xx
  • NVIDIA Quadro / RTX A-series
  • NVIDIA Tesla / A100 / H100
  • NVIDIA L4, L40, L40S

CPU Fallback

When no GPU is detected, HammerIO automatically uses CPU-based zstd compression. No configuration change is needed. The smart routing engine adjusts all thresholds for CPU-only operation.

# Verify your system configuration
hammerio status

# Example output:
# HammerIO v1.0.0
# GPU: NVIDIA Orin (8 GB) — nvCOMP 3.x ready
# CPU: 12 cores — zstd 1.5.5
# Routing: auto (GPU for files > 500 MB)

Questions? Reach out at Joseph@ResilientMindAI.com.