DOCSEARCHbyAlgolia
Submit Docs

hf-mount

repository·main·Indexed 21 days ago

https://github.com/huggingface/hf-mount

hf-mount (v0.9.0) allows users to mount Hugging Face Buckets and Hub repositories as local filesystems using FUSE or NFS. It enables lazy-loading of files, fetching only the specific bytes accessed by an application, which is ideal for ML workloads with limited disk space. It supports read-only mounts for repositories and read-write access for buckets, with an optional overlay mode for writable local layers.

Tokens
12K
Snippets
39
Records
55
Agent score
69%

What's inside hf-mount

  1. Use Overlay mode for writable local layers

    main

    The --overlay flag creates a writable local layer on top of a remote source.

    How it works:

    • Reads: Returns files from the remote source OR files already present in the local layer. If a name exists in both, the local copy wins.
    • Writes: All new files, directories, or modifications land only on the local disk. The remote source is never touched.
    • Persistence: Local files survive an unmount/remount.

    Use Case: A shared compilation cache where multiple machines mount the same bucket with --overlay. They read existing artifacts from the bucket but write new ones locally, effectively creating a per-machine cache layer.

    Limitations:

    • You cannot modify, rename, or delete files that exist only on the remote. These operations will fail with a permission error.
    • You cannot shadow an existing remote name with a new local file after the mount is active. To do this, place the file in the mount-point directory before starting the mount.
    • Symlinks in the local layer are hidden from the merged view to prevent escaping the mount point.
    # Producer (writes compiled artifacts to the bucket)
hf-mount start bucket myorg/torch-compile-cache "$TORCHINDUCTOR_CACHE_DIR"

# Consumer (reads from the bucket, compiles locally on miss)
hf-mount start --overlay bucket myorg/torch-compile-cache "$TORCHINDUCTOR_CACHE_DIR"

  2. Bound in-memory inode usage

    main

    When enumerating large trees (e.g., find, du), the in-memory inode table can grow significantly. Use --inode-soft-limit N to cap the table size. Two mechanisms manage this:

    1. Insert-time evictor (Synchronous): When the table reaches N + 256, it drops the oldest-touched entries.
      • Polite mode: Only drops entries the kernel has already released (forget-ed).
      • Force mode: If above 2 * N, it drops entries even if the kernel still caches the dentry. Note: Dirty files, locally-created dirs/symlinks, and inodes with live file handles are never dropped.
    2. Background LRU sweep: Every --lru-sweep-interval-ms, it sends FUSE_NOTIFY_INVAL_ENTRY to the kernel to drop cached dentries.

    Tuning Example: For a directory structure with ~20k files, setting --inode-soft-limit 10000 can keep the process memory usage around 250 MiB.

  3. Understand the hf-mount consistency model

    main

    hf-mount provides eventual consistency with the Hugging Face Hub. It does not receive push notifications for remote changes; instead, it relies on client-side polling to detect updates.

    Reads

    Files may be stale for up to the duration of --metadata-ttl-ms (default 10s). Freshness is maintained via:

    1. Metadata revalidation (FUSE only): When a per-file TTL expires, the next access checks the Hub. If the file has changed, the cached data is invalidated.
    2. Background polling: By default, every 30s, hf-mount lists the full tree to detect additions, modifications, and deletions.

    Writes

    There are two write modes available:

    • Streaming (Default): Uses an in-memory buffer and uploads only when close() is called. This is append-only/sequential. Note: This mode does not support text editors like vim, nano, or emacs because they use unlink+create patterns which are blocked with EPERM to prevent data loss.
    • Advanced (--advanced-writes): Downloads the full file to a local staging file on disk. This supports random writes, seeking, and overwriting existing files. Flushes are performed asynchronously (debounced between 2s and 30s).

  4. Compare FUSE and NFS backends

    main

    Choose between FUSE and NFS based on your environment and requirements:

    FeatureFUSENFS
    Metadata revalidationPer-file, within TTLNo (uses file handles)
    Page cache invalidationSupportedNot supported by NFS protocol
    Staleness window~10 sUp to poll interval (30 s)
    Write modeStreaming by defaultAdvanced always
    • FUSE is intended for standard Linux/macOS environments (requires macFUSE on macOS or fuse3 on Linux).
    • NFS is intended for environments without /dev/fuse and works everywhere, but lacks per-file metadata revalidation.

  5. When to use hf-mount (Best practices and limitations)

    main

    Best for:

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

    Not for:

    • General-purpose networked filesystems: No multi-writer support or cross-node file locking.
    • Latency-sensitive random I/O: The first read of any file requires a network round-trip.
    • Strong consistency requirements: Files can be stale for up to 10 seconds.
    • Heavy concurrent writes: Uses a "last writer wins" strategy with no conflict detection.
    • Default text editor usage: Editing files in streaming mode may be problematic; use the --advanced-writes flag if needed.

    File Locking:

    Advisory file locks (flock, fcntl POSIX record locks) are supported locally on a single mount on both backends. This supports libraries like filelock, huggingface_hub, and datasets for cache coordination on a single machine, but locks are not coordinated across multiple clients.

  6. Install hf-mount via manual download

    main

    You can download pre-built binaries for your platform from the GitHub Releases page. The available binaries include the main daemon, the NFS backend, and the FUSE backend for various architectures.

    | Platform | Daemon | NFS | FUSE |
| --- | --- | --- | --- |
| Linux x86_64 | `hf-mount-x86_64-linux` | `hf-mount-nfs-x86_64-linux` | `hf-mount-fuse-x86_64-linux` |
| Linux aarch64 | `hf-mount-aarch64-linux` | `hf-mount-nfs-aarch64-linux` | `hf-mount-fuse-aarch64-linux` |
| macOS Apple Silicon | `hf-mount-arm64-apple-darwin` | `hf-mount-nfs-arm64-apple-darwin` | `hf-mount-fuse-arm64-apple-darwin` |

  7. Manage and unmount hf-mount processes

    main

    Use the following commands to manage active daemon mounts:

    • hf-mount status: Lists all currently running mounts.
    • hf-mount stop <path>: Stops and unmounts the daemon at the specified path.

    Manual Unmounting: If you are not using the daemon (e.g., using FUSE directly), use standard system tools:

    • macOS (NFS/FUSE): umount <path>
    • Linux (FUSE): fusermount -u <path>

    Logs and PIDs:

    • Logs are stored in ~/.hf-mount/logs/.
    • PID files are stored in ~/.hf-mount/pids/.
    hf-mount status                  # list running mounts
hf-mount stop /tmp/data          # stop and unmount

# Manual unmounts
umount /tmp/data                 # NFS or FUSE (macOS)
fusermount -u /tmp/data          # FUSE (Linux)

  8. Run hf-mount in foreground mode

    main

    For debugging, scripts, or containers where you want the process to run in the foreground rather than as a daemon, call the backend binaries directly:

    • hf-mount-nfs <repo_or_bucket> <path>
    • hf-mount-fuse <path> (with appropriate flags)
    hf-mount-nfs repo gpt2 /tmp/gpt2
hf-mount-fuse --hf-token $HF_TOKEN bucket myuser/my-bucket /mnt/data

  9. Mount a Hugging Face repository (read-only)

    main

    Use hf-mount start repo to mount a Hugging Face repository as a local filesystem. Repositories are always mounted read-only. You can specify a specific revision or mount only a subfolder.

    Common patterns:

    • Public repos: No token required.
    • Private repos: Requires --hf-token.
    • Datasets: Use the datasets/ prefix.
    • Specific revisions: Use the --revision flag.
    • Subfolders: Append the path to the repo name.
    # 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

  10. Mount a Hugging Face Bucket (read-write)

    main

    Buckets are S3-like object storage on the Hub designed for large-scale mutable data (e.g., training checkpoints, logs). By default, bucket mounts are read-write, but you can force read-only mode using the --read-only flag.

    Common patterns:

    • Standard mount: Read-write access to the bucket.
    • Read-only mount: Use --read-only.
    • Subfolders: Append the path to the bucket name.
    # Standard bucket mount (read-write)
hf-mount start --hf-token $HF_TOKEN bucket myuser/my-bucket /tmp/data

# Read-only bucket mount
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

  11. Mount a Hugging Face Bucket or Repo

    main

    Use the hf-mount start command to mount Hugging Face Buckets or Hub repositories as local filesystems. Files are fetched lazily on first read, meaning only the bytes accessed by your code are downloaded.

    Authentication: Commands automatically detect your HF_TOKEN from the environment. Alternatively, you can provide it explicitly using the --hf-token flag.

    Examples:

    • Mount a Bucket: hf-mount start bucket <user>/<bucket-name> <mount-point>

    • Mount a Repo (Read-only): hf-mount start repo <org>/<repo-name> <mount-point>

    # Mount a bucket
hf-mount start bucket myuser/my-bucket /tmp/data

# Mount a repo (read-only)
hf-mount start repo openai/gpt-oss-20b /tmp/gpt-oss

  12. Use the FUSE backend for tighter integration

    main

    By default, hf-mount uses NFS. For tighter kernel integration (including page cache invalidation and per-file metadata revalidation), use the --fuse flag.

    Requirements:

    • Linux: Requires fuse3.
    • macOS: Requires macFUSE.
    hf-mount start --fuse --hf-token $HF_TOKEN bucket myuser/my-bucket /mnt/data