Mount Hugging Face Buckets and repos as local filesystems. No download, no copy, no waiting.

hf-mount start bucket myuser/my-bucket /tmp/data

Also works with any model or dataset repo (read-only):

hf-mount start repo openai/gpt-oss-20b /tmp/gpt-oss

Commands will pick up your HF_TOKEN from the environment, or you can pass it explicitly with --hf-token.

Then use your local folders as usual:

from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("/tmp/gpt-oss")  # reads on demand, no download step

hf-mount exposes Hugging Face Buckets and Hub repos as a local filesystem via FUSE or NFS. Files are fetched lazily on first read, so only the bytes your code actually touches ever hit the network.

Two backends are available:

• NFS (recommended) -- works everywhere, no root, no kernel extension
• FUSE -- tighter kernel integration, requires root or macFUSE on macOS

Agentic storage: Agents don't require complex APIs or SDKs, they thrive on the filesystem: ls, cat, find, grep, and the power of composable UNIX pipelines.

curl -fsSL https://raw.githubusercontent.com/huggingface/hf-mount/main/install.sh | sh

Installs hf-mount to ~/.local/bin/. Set INSTALL_DIR to change the location. Supports Linux (x86_64, aarch64) and macOS (Apple Silicon).

Binaries are available on GitHub Releases:

The NFS backend has no system dependencies. For FUSE:

Linux: sudo apt-get install -y fuse3 (pre-built binaries only need the runtime; building from source also requires libfuse3-dev)

macOS: install macFUSE (brew install macfuse, requires reboot on first install)

Requires Rust 1.85+.

# NFS only (no system deps, works everywhere)
cargo build --release --features nfs

# FUSE (requires macFUSE on macOS, fuse3 on Linux)
cargo build --release --features fuse

# All backends
cargo build --release --features fuse,nfs

Binaries: target/release/hf-mount, target/release/hf-mount-nfs, target/release/hf-mount-fuse

Best for:

• Loading models and datasets without downloading the full repo
• Browsing repo contents (ls, cat, find) without cloning
• Read-heavy ML workloads (training, inference, evaluation)
• Environments where disk space is limited

Not for:

• General-purpose networked filesystem (no multi-writer support, no file locking)
• Latency-sensitive random I/O (first reads require network round-trips)
• Workloads that need strong consistency (files can be stale for up to 10 s)
• Heavy concurrent writes from multiple mounts (last writer wins, no conflict detection)

See Consistency model for details.

# Public model (no token needed)
hf-mount start repo openai/gpt-oss-20b /tmp/model

# Private model
hf-mount start --hf-token $HF_TOKEN repo myorg/my-private-model /tmp/model

# Dataset
hf-mount start repo datasets/open-index/hacker-news /tmp/hn

# Specific revision
hf-mount start repo openai-community/gpt2 /tmp/gpt2 --revision v1.0

# Subfolder only
hf-mount start repo openai-community/gpt2/onnx /tmp/onnx

Buckets are S3-like object storage on the Hub, designed for large-scale mutable data (training checkpoints, logs, artifacts) without git version control.

hf-mount start --hf-token $HF_TOKEN bucket myuser/my-bucket /tmp/data

# Read-only
hf-mount start --hf-token $HF_TOKEN --read-only bucket myuser/my-bucket /tmp/data

# Subfolder only
hf-mount start --hf-token $HF_TOKEN bucket myuser/my-bucket/checkpoints /tmp/ckpts

hf-mount status                  # list running mounts
hf-mount stop /tmp/data          # stop and unmount

Logs are written to ~/.hf-mount/logs/. PID files are stored in ~/.hf-mount/pids/.

By default, hf-mount uses NFS. Pass --fuse for tighter kernel integration (page cache invalidation, per-file metadata revalidation). Requires fuse3 on Linux or macFUSE on macOS.

hf-mount start --fuse --hf-token $HF_TOKEN bucket myuser/my-bucket /mnt/data

For scripts, containers, or debugging, use the backend binaries directly (they run in the foreground):

hf-mount-nfs repo gpt2 /tmp/gpt2
hf-mount-fuse --hf-token $HF_TOKEN bucket myuser/my-bucket /mnt/data

To have hf-mount start automatically on login, create a LaunchAgent:

label=co.huggingface.hf-mount

mkdir -p ~/Library/LaunchAgents

cat > ~/Library/LaunchAgents/$label.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>$label</string>
    <key>ProgramArguments</key>
    <array>
        <string>$HOME/.local/bin/hf-mount-nfs</string>
        <string>repo</string>
        <string>openai/gpt-oss-20b</string>
        <string>/tmp/gpt-oss</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/hf-mount.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/hf-mount.log</string>
</dict>
</plist>
EOF

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/$label.plist

To stop: launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/$label.plist

umount /tmp/data                 # NFS or FUSE (macOS)
fusermount -u /tmp/data          # FUSE (Linux)
hf-mount stop /tmp/data          # daemon mounts

RUST_LOG=hf_mount=debug hf-mount-fuse repo gpt2 /mnt/gpt2

• FUSE & NFS backends -- FUSE for standard Linux/macOS, NFS for environments without /dev/fuse
• Lazy loading -- files are fetched on demand, not eagerly downloaded
• Subfolder mounting -- mount only a subdirectory (e.g. user/model/ckpt/v2)
• Simple writes (default) -- append-only, in-memory, synchronous upload on close
• Advanced writes (--advanced-writes) -- staging files on disk, random writes + seek, async debounced flush
• Remote sync -- background polling detects remote changes and updates the local view
• POSIX metadata -- chmod, chown, timestamps, symlinks (in-memory only, lost on unmount)

hf-mount provides eventual consistency with remote changes. There is no push notification from the Hub; all freshness relies on client-side polling.

Files can be stale for up to --metadata-ttl-ms (default 10 s) after a remote update. Two mechanisms detect changes:

1. Metadata revalidation (FUSE only) -- when the per-file TTL expires, the next access checks the Hub. If the file changed, cached data is invalidated.
2. Background polling (default every 30 s) -- lists the full tree and detects additions, modifications, and deletions.

Streaming mode buffers writes in memory and uploads on close(). A crash before close means data loss.

Advanced mode downloads the full file to local disk before allowing edits. After close(), dirty files are flushed asynchronously. A crash before flush completes means data loss.

hf-mount sits between your application and the Hugging Face Hub. It presents a standard filesystem interface (FUSE or NFS) and translates file operations into Hub API calls and storage fetches.

Reads go through an adaptive prefetch buffer that starts small and grows with sequential access. Writes are uploaded to HF storage and committed via the Hub API. A background poll loop keeps the local view in sync with remote changes.

Built on xet-core for content-addressed storage and efficient file transfers, and fuser for the FUSE implementation.

Use the hf-csi-driver to mount Buckets and repos as Kubernetes volumes. The CSI driver runs hf-mount inside a DaemonSet and exposes mounts to pods via the Container Storage Interface.

helm install hf-csi oci://ghcr.io/huggingface/charts/hf-csi-driver

See the hf-csi-driver README for setup and examples.

# Unit tests (no network, no token)
cargo test --lib --features fuse,nfs

# Integration tests (require HF_TOKEN and FUSE)
HF_TOKEN=... cargo test --release --features fuse,nfs --test fuse_ops -- --test-threads=1 --nocapture
HF_TOKEN=... cargo test --release --features fuse,nfs --test nfs_ops -- --test-threads=1 --nocapture

# Repo mount test (public repo, no token needed)
cargo test --release --features nfs --test repo_ops -- --test-threads=1 --nocapture

# Benchmarks
HF_TOKEN=... cargo test --release --features fuse,nfs --test bench -- --nocapture

Apache-2.0