Hub documentation

Access Patterns

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Access Patterns

Beyond the CLI and Python SDK, there are several ways to access bucket data from your existing tools and workflows.

Choosing an Access Method

Method Best for Details
hf-mount Mount as local filesystem — any tool works See below
Volume mounts HF Jobs & Spaces (same idea, managed for you) See below
hf:// paths (fsspec) Python data tools (pandas, DuckDB) See below
CLI sync Batch transfers, backups Sync docs

Mount as a Local Filesystem

hf-mount lets you mount buckets (and repos) as local filesystems via NFS (recommended) or FUSE. Files are fetched lazily — only the bytes your code reads hit the network.

Install:

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

Mount a bucket:

hf-mount start bucket username/my-bucket /mnt/data

Once mounted, any tool that reads or writes files works with your bucket — pandas, DuckDB, vLLM, training scripts, shell commands, etc.

Buckets are mounted read-write; repos are read-only. See the hf-mount repository for full documentation including backend options, caching, and write modes.

Volume Mounts in Jobs and Spaces

Volume mounts in Jobs and Spaces are the same idea as hf-mount, managed for you by the platform — no extra setup needed. Buckets are mounted read-write by default.

hf jobs run -v hf://buckets/username/my-bucket:/data python:3.12 python script.py

For the full volume mount syntax and Python API, see the Jobs configuration docs and the Spaces volume mount guide.

Python Data Tools

The HfFileSystem provides fsspec-compatible access to buckets using hf://buckets/ paths. Any Python library that supports fsspec can read and write bucket data directly.

pandas:

import pandas as pd

df = pd.read_parquet("hf://buckets/username/my-bucket/data.parquet")
df.to_parquet("hf://buckets/username/my-bucket/output.parquet")

DuckDB (Python client):

import duckdb
from huggingface_hub import HfFileSystem

duckdb.register_filesystem(HfFileSystem())
duckdb.sql("SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10")

For more on hf:// paths and supported operations, see the HfFileSystem guide and the Buckets Python guide.

Update on GitHub