hf-image

Fast, Xet-native push and pull for the Hugging Face container registry (cr.hf.co), packaged as an hf CLI extension.

Layers move directly between your machine and Hugging Face storage, deduplicated by content — so re-pushing an image only uploads the chunks that actually changed, and a pull only downloads what you don't already have. Pushed images stay fully compatible with plain docker: anything you push with hf image can be pulled with docker pull, and anything pulled with hf image matches what docker would fetch.

Install

$ hf extensions install huggingface/hf-image
$ hf image --help

Needs the hf CLI (ships with huggingface_hub). Pushing from / pulling into your local Docker daemon also needs Docker running.

Working from a local checkout instead of the published extension? See docs/development.md.

Authenticate

hf image uses your logged-in Hugging Face token:

$ hf auth login

Pulling public images works without logging in. Pushing always needs a token with write access to the target repository. You can also pass --token <token> or set HF_TOKEN.

Push an image

# push the local Docker image tagged cr.hf.co/... (just like `docker push`)
$ hf image push cr.hf.co/acme-ai/inference-server:latest

# push a differently-named local image
$ hf image push cr.hf.co/acme-ai/inference-server:latest --from inference-server:latest

# push an OCI layout or archive (no Docker daemon needed — e.g. `docker buildx build -o type=oci`)
$ hf image push cr.hf.co/acme-ai/inference-server:latest --from oci:./build
$ hf image push cr.hf.co/acme-ai/inference-server:latest --from oci-archive:./inference-server.tar

The positional is the cr.hf.co/<owner>/<image>:<tag> destination — same form as pull — and its bucket must already exist (see the note above). --from chooses what to push and defaults to the local Docker image tagged like the target. Multi-arch sources push every platform.

The default (and --from <name>) export from your local Docker daemon, which needs Docker ≥ 25. On older Docker, push an OCI artifact with --from oci: / --from oci-archive: instead.

Pull an image

# into your local Docker daemon (default)
$ hf image pull cr.hf.co/acme-ai/inference-server:latest

# into an OCI layout directory
$ hf image pull cr.hf.co/acme-ai/inference-server:latest -o ./oci

# pick a platform from a multi-arch image (default: linux/amd64)
$ hf image pull cr.hf.co/acme-ai/inference-server:latest --platform linux/arm64

If a pull fails with a "not registered in the bucket listing" error, the image contains a blob the fast path can't resolve yet — typically an attestation layer, or an image originally uploaded with plain docker push. Use docker pull for those images; this is a known gap.

Uninstall

$ hf extensions remove image

How it works & contributing

The design, the architecture, and how to build from source live in docs/.