hf-mount: Mount Hugging Face Repos as Local Filesystems — No Download Required

If you have ever waited 20 minutes for a 40 GB model to download before you could run a single inference test, you already understand the problem that hf-mount solves.

hf-mount is a new open-source tool from Hugging Face that exposes any Hub repository or Bucket as a mountable local filesystem. Your shell sees a normal directory. Your Python code reads normal files. But nothing is actually downloaded until the moment a byte is accessed — and even then, only the bytes you touch.

No staging directory. No waiting. No copy.

The Core Idea

Traditional Hugging Face workflows look like this:

huggingface-cli download openai/gpt-oss-20b
# wait... wait... wait...
python run_inference.py

With hf-mount, it looks like this:

hf-mount start repo openai/gpt-oss-20b /tmp/model
python run_inference.py   # reads /tmp/model/... on demand

The directory /tmp/model appears instantly. Files show their correct sizes. You can ls, cat, find, and open() them just like local files. Under the hood, chunks are fetched from the Hugging Face CDN only when your process actually reads them — and cached locally so repeat reads are instant.

This is lazy loading, done at the OS filesystem level.

Installation

The quickest path is the install script:

curl -sSL https://huggingface.co/install/hf-mount | sh

This drops the binary into ~/.local/bin/. You can also grab a release binary manually from the GitHub Releases page.

Supported platforms:

• Linux x86_64 and aarch64
• macOS Apple Silicon

Backend dependencies:

• NFS (recommended): No additional dependencies, works without root
• FUSE: Requires fuse3 on Linux (sudo apt install fuse3) or macFUSE on macOS

Authentication

hf-mount reads your Hugging Face token from the HF_TOKEN environment variable:

export HF_TOKEN=hf_your_token_here
hf-mount start repo meta-llama/Llama-3-8B /tmp/llama

Or pass it inline:

hf-mount start --hf-token $HF_TOKEN repo meta-llama/Llama-3-8B /tmp/llama

A --token-file option is also available for environments where credential rotation is managed externally.

Mounting Repositories vs Buckets

hf-mount supports two resource types:

Repositories (read-only)

Model and dataset repositories are mounted read-only. This covers the vast majority of use cases — loading weights, reading dataset shards, browsing configs.

# Mount a model repo
hf-mount start repo openai/gpt-oss-20b /tmp/model

# Mount a dataset repo
hf-mount start repo datasets/HuggingFaceFW/fineweb /tmp/fineweb

# Mount a specific subfolder only
hf-mount start repo --subfolder en /tmp/fineweb-en

Buckets (read-write)

Hugging Face Buckets support both reads and writes. Writes are append-only by default (streaming mode), which works well for logging and output collection. For workflows that need in-place edits, use --advanced-writes:

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

Managing Mounts

# Check what's currently mounted
hf-mount status

# Unmount a specific path
hf-mount stop /tmp/model

# Unmount all active mounts
hf-mount stop --all

How It Works Under the Hood

hf-mount sits between your application and the Hugging Face Hub, translating POSIX filesystem calls into Hub API requests.

Two backends are available:

NFS is the default and recommended option — it works on any system without elevated privileges and has excellent compatibility.

The storage layer is built on xet-core, Hugging Face’s content-addressed storage engine. Files are chunked, deduplicated, and cached locally (configurable up to ~10 GB by default). Sequential reads are accelerated by an adaptive prefetch buffer that adjusts its window size based on access patterns.

Consistency model: Metadata is eventually consistent, with a default staleness window of 10 seconds. Remote changes are detected by a background polling process (default interval: 30 seconds). This is appropriate for read-heavy ML workloads but not for scenarios requiring strong consistency.

POSIX Metadata Support

Unlike some lazy-loading solutions that present files as opaque blobs, hf-mount supports a meaningful subset of POSIX metadata:

• chmod, chown (buckets)
• Timestamps (mtime, atime, ctime)
• Symbolic links
• Standard directory traversal (ls -la, find, tree)

This means tools like rsync, cp, and most ML data loaders work without modification.

Kubernetes Integration

For teams running training jobs on Kubernetes, the companion hf-csi-driver exposes hf-mount as a CSI (Container Storage Interface) volume. You can declare a Hugging Face repo as a volume in your pod spec and have it appear at a mount path inside the container — no init containers, no PVCs, no manual download steps.

This is particularly useful for large-scale training infrastructure where dozens of nodes need access to the same model weights simultaneously.

When to Use hf-mount

hf-mount is a strong fit for:

• Exploratory inference: Test a model before committing to a full download
• Dataset sampling: Read 1,000 rows from a 500 GB dataset without downloading it
• Disk-constrained environments: CI runners, small VMs, edge devices
• Training pipelines: Load dataset shards on demand across many workers
• Repository browsing: Inspect file structure, configs, tokenizer files

Where it is not the right tool:

• Multi-writer workloads where multiple processes write to the same files simultaneously
• Latency-critical random I/O (the network round-trip cost applies)
• Text editors in default mode (use --advanced-writes for in-place editing)
• Scenarios requiring strict consistency guarantees

Performance Notes

The local chunk cache is the key to making this practical. Once a chunk is fetched, subsequent reads hit local disk — at full disk speed. For sequential access patterns (reading a model shard start-to-finish), the adaptive prefetch buffer keeps the pipeline full and network idle time minimal.

For random access patterns (jumping around a large dataset), performance depends on your connection speed and chunk size. It will always be slower than local disk but avoids the upfront cost entirely.

The cache size can be tuned:

hf-mount start --cache-size-gb 20 repo openai/gpt-oss-20b /tmp/model

Practical Example: Loading a Model in Python

import subprocess
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# Mount the model
subprocess.run(["hf-mount", "start", "repo", "meta-llama/Llama-3-8B", "/tmp/llama"], check=True)

# Load directly from the mount — no separate download step
tokenizer = AutoTokenizer.from_pretrained("/tmp/llama")
model = AutoModelForCausalLM.from_pretrained("/tmp/llama", torch_dtype=torch.bfloat16)

# Unmount when done
subprocess.run(["hf-mount", "stop", "/tmp/llama"])

The from_pretrained call reads only the files it needs (config, tokenizer, and the specific weight shards required). For a sharded model, that means only the shards actually loaded into memory are transferred over the network.

Summary

hf-mount is a well-engineered solution to a real friction point in the ML workflow. The idea — treat a remote repository as a filesystem — is not new, but the execution here is solid: NFS and FUSE backends, POSIX metadata support, a tunable local cache, Kubernetes integration via CSI, and read-write support for Buckets.

If you regularly work with large models or datasets on Hugging Face, the installation takes 30 seconds and the workflow improvement is immediate. Start with the NFS backend (no root required), mount a repo you normally download, and run your usual code against the mount path. Chances are it just works.

curl -sSL https://huggingface.co/install/hf-mount | sh
hf-mount start repo <owner>/<repo> /tmp/mnt

The project is open source and actively maintained. Source is at github.com/huggingface/hf-mount.