Hugging Face CLI

1.11.0 · active · verified Fri Apr 17

The `hf` library provides a command-line interface (CLI) for interacting with the Hugging Face Hub. It allows users to manage models, datasets, and Spaces, perform authentication, and execute various repository operations directly from the terminal. As of version 1.11.0, it includes features like semantic search for Spaces and server-side file copy operations. This library is updated frequently, often in sync with releases of the underlying `huggingface_hub` Python library.

Common errors

```
hf: command not found
```
cause The `hf` CLI is not installed or its installation directory is not included in your system's PATH environment variable.

fix Install the `hf` package using pip: `pip install hf`. If already installed, ensure your Python installation's script directory is in your PATH.
```
You must be logged in to the Hugging Face Hub to use this command. Run `huggingface-cli login` to authenticate.
```
cause The command you are trying to execute requires authentication, but you are not logged in or your token has expired.

fix Log in using the CLI: `hf login`. Provide your Hugging Face Hub token when prompted. For automation, consider using `hf login --token <YOUR_TOKEN>` or setting the `HF_TOKEN` environment variable.
```
ModuleNotFoundError: No module named 'hf'
```
cause This error occurs when attempting `import hf` in a Python script. The `hf` package is primarily a command-line interface and does not expose Python modules for direct functional import.

fix If you need Python APIs to interact with the Hugging Face Hub, use the `huggingface_hub` library. For example: `from huggingface_hub import HfApi`.

Warnings

gotcha The `hf` package provides a CLI tool and is not intended for direct Python `import` statements for most user-facing functionality. If you need to interact with the Hugging Face Hub programmatically within Python code, use the `huggingface_hub` library instead.
Fix: For Python API interactions, use `from huggingface_hub import HfApi, login` etc., rather than trying to `import hf`.
breaking The Homebrew formula for the Hugging Face CLI was renamed from `huggingface-cli` to `hf`. Existing users running `brew update` will have the rename handled automatically.
Fix: If using Homebrew, ensure you have updated Homebrew. For new installations, use `brew install hf`.
deprecated Hugging Face Spaces' 'persistent storage' feature has been deprecated in favor of 'Volumes'. CLI commands or API calls related to persistent storage should be updated to use the new Volume mechanisms.
Fix: Migrate your Spaces configurations to use the 'Volumes' feature, which offers more flexible mounting of models, datasets, and storage buckets. Refer to the `huggingface_hub` documentation for `set_space_volumes` and related API/CLI.
gotcha Commands involving sensitive operations (e.g., creating repos, uploading files, managing spaces) require authentication. If you encounter permissions errors or prompts to log in, ensure you are authenticated.
Fix: Run `hf login` in your terminal and provide your Hugging Face token (preferably a write token if performing write operations). You can generate tokens on the Hugging Face website under your profile settings.

Install

pip install hf Install `hf` CLI

Quickstart

This quickstart demonstrates how to log in, verify authentication, create a new repository, and upload a file using the `hf` CLI. Replace `username` with your Hugging Face username.

# Log in to the Hugging Face Hub
hf login

# Check your current logged-in user
hf whoami

# Create a new private model repository
hf repo create my-awesome-model --type model --private

# Upload a file to an existing repository
echo "Hello from CLI" > README.md
hf upload README.md --repo-id username/my-awesome-model --commit-message "Add README via CLI"

view raw JSON →