{"id":9811,"library":"hf","title":"Hugging Face CLI","description":"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.","status":"active","version":"1.11.0","language":"en","source_language":"en","source_url":"https://github.com/huggingface/huggingface_hub","tags":["CLI","HuggingFace","AI/ML","Machine Learning"],"install":[{"cmd":"pip install hf","lang":"bash","label":"Install `hf` CLI"}],"dependencies":[{"reason":"The `hf` CLI is built on top of the `huggingface_hub` Python library and requires it for core functionality.","package":"huggingface-hub","optional":false}],"imports":[],"quickstart":{"code":"# Log in to the Hugging Face Hub\nhf login\n\n# Check your current logged-in user\nhf whoami\n\n# Create a new private model repository\nhf repo create my-awesome-model --type model --private\n\n# Upload a file to an existing repository\necho \"Hello from CLI\" > README.md\nhf upload README.md --repo-id username/my-awesome-model --commit-message \"Add README via CLI\"\n","lang":"bash","description":"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."},"warnings":[{"fix":"For Python API interactions, use `from huggingface_hub import HfApi, login` etc., rather than trying to `import hf`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If using Homebrew, ensure you have updated Homebrew. For new installations, use `brew install hf`.","message":"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.","severity":"breaking","affected_versions":">=1.7.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.9.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the `hf` package using pip: `pip install hf`. If already installed, ensure your Python installation's script directory is in your PATH.","cause":"The `hf` CLI is not installed or its installation directory is not included in your system's PATH environment variable.","error":"hf: command not found"},{"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.","cause":"The command you are trying to execute requires authentication, but you are not logged in or your token has expired.","error":"You must be logged in to the Hugging Face Hub to use this command. Run `huggingface-cli login` to authenticate."},{"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`.","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.","error":"ModuleNotFoundError: No module named 'hf'"}]}