Install Hugging Face Hub in Python

Hugging Face Hub is a platform for sharing machine learning models, datasets, and demos. It hosts thousands of open models for tasks like text, image, and audio.

The huggingface_hub library connects your Python code to this platform. It lets you download models, upload files, and manage repositories.

This guide shows you how to install it, log in, and run your first commands. It is written for beginners, so every step is simple and clear.

What Is Hugging Face Hub?

Hugging Face Hub is a central place for AI resources. You can find models such as BERT, GPT, and Stable Diffusion there.

The hub also stores datasets and spaces. Spaces are small web apps that show models in action.

The huggingface_hub package is the official Python client. It works with the website and with the Transformers library.

You can use it on its own. You can also use it as a base for other tools.

Requirements Before You Start

You need a few basic things before installing the library.

First, install Python 3.7 or newer. You can check your version in the terminal.

python --version

Second, make sure pip is available. Pip is the package installer for Python.

pip --version

Third, create a virtual environment. This keeps your project clean and avoids conflicts.

python -m venv hf-env
source hf-env/bin/activate

On Windows, use this command instead:

hf-env\Scripts\activate

How to Install Hugging Face Hub

Installing the library is quick. Use pip to get the latest version.

pip install huggingface_hub

This command downloads the package and its dependencies. It works on Windows, macOS, and Linux.

If you use conda, you can install it with conda-forge.

conda install -c conda-forge huggingface_hub

After the install, check that it worked. Import the library in Python.

import huggingface_hub

print(huggingface_hub.__version__)

You should see a version number like this:

0.23.4

If you see a number, the install was a success. If you see an error, check your pip and Python versions.

Install Optional Extras

The base package is small. You can add extras for more features.

For example, the cli extra adds command line tools. The torch extra helps with PyTorch models.

pip install "huggingface_hub[cli]"

The hf command becomes available after this step. You can use it to log in and manage files.

hf --help

This prints a list of commands. It is handy when you work in the terminal.

Log In to Your Hugging Face Account

Some models are public. Others need an account or a token.

Create a free account on the Hugging Face website. Then go to your settings and make an access token.

Use the login() function to sign in from Python.

from huggingface_hub import login

# Paste your token when asked
login()

The function asks for your token. Paste it and press Enter.

You can also log in from the terminal with the hf command.

hf auth login

Your token is saved on your machine. You only need to do this once.

Keep your token private. Do not share it or commit it to Git.

Download a Model or Dataset

Now you can download files from the hub. The hf_hub_download() function grabs a single file.

from huggingface_hub import hf_hub_download

# Download the model config file
path = hf_hub_download(
    repo_id="bert-base-uncased",
    filename="config.json"
)

print(path)

The output shows where the file is saved on your disk.

/home/user/.cache/huggingface/hub/models--bert-base-uncased/snapshots/.../config.json

For a whole repository, use the snapshot_download() function.

from huggingface_hub import snapshot_download

# Download all files in the repo
folder = snapshot_download(repo_id="bert-base-uncased")

print(folder)

This downloads every file in the model repo. It is useful when you want the full model.

Files are cached by default. The next download is much faster.

Upload Files to the Hub

You can also push your own files. The upload_file() function sends one file to a repo.

from huggingface_hub import upload_file

# Upload a local file to your repo
upload_file(
    path_or_fileobj="my_model.bin",
    path_in_repo="my_model.bin",
    repo_id="your-username/my-model"
)

Make sure you are logged in first. The repo must exist or be created.

Use create_repo() to make a new repository from Python.

from huggingface_hub import create_repo

# Create a new model repo
create_repo(repo_id="your-username/my-model", repo_type="model")

After that, you can upload files and share your work with others.

Common Installation Problems

Most issues come from old tools or missing permissions.

If pip fails, upgrade it first.

pip install --upgrade pip

If you get a permission error, avoid using sudo. Use a virtual environment instead.

If the import fails, check that you installed the package in the right environment.

Network problems can also block downloads. A stable internet connection helps a lot.

Behind a proxy, set the HTTPS_PROXY environment variable before you run your code.

Best Practices

Always use a virtual environment. It keeps your global Python clean.

Pin your package version in a requirements file. This makes your project reproducible.

pip freeze > requirements.txt

Store your token in an environment variable or a secret manager. Never hard-code it.

Clear your cache if you run out of disk space. The cache lives in the ~/.cache/huggingface folder.

These small habits save time and prevent bugs later.

Conclusion

Installing Hugging Face Hub in Python is easy. One pip command gets you started.

From there, you can log in, download models, and upload your own files. The library handles caching and authentication for you.

Follow the steps in this guide, and you will be ready to use thousands of AI models in minutes. Happy coding!