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

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 with Homebrew:

brew install hf-mount

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

Jobs can also take a local directory as the volume source (-v ./training-data:/data): the directory is synced to your private jobs-artifacts bucket and mounted from there, so incremental re-syncs and output pull-back come for free.

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.