Skip to content
Transformers

Installation

Transformers works with PyTorch. It has been tested on Python 3.9+ and PyTorch 2.2+.

Virtual environment

Section titled “Virtual environment”

uv is an extremely fast Rust-based Python package and project manager and requires a virtual environment by default to manage different projects and avoids compatibility issues between dependencies.

It can be used as a drop-in replacement for pip, but if you prefer to use pip, remove uv from the commands below.

Create a virtual environment to install Transformers in.

Terminal window
uv venv .env
source .env/bin/activate

Python

Section titled “Python”

Install Transformers with the following command.

uv is a fast Rust-based Python package and project manager.

Terminal window
uv pip install transformers

For GPU acceleration, install the appropriate CUDA drivers for PyTorch.

Run the command below to check if your system detects an NVIDIA GPU.

Terminal window
nvidia-smi

To install a CPU-only version of Transformers, run the following command.

Terminal window
uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install transformers

Test whether the install was successful with the following command. It should return a label and score for the provided text.

Terminal window
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

Source install

Section titled “Source install”

Installing from source installs the latest version rather than the stable version of the library. It ensures you have the most up-to-date changes in Transformers and it’s useful for experimenting with the latest features or fixing a bug that hasn’t been officially released in the stable version yet.

The downside is that the latest version may not always be stable. If you encounter any problems, please open a GitHub Issue so we can fix it as soon as possible.

Install from source with the following command.

Terminal window
uv pip install git+https://github.com/huggingface/transformers

Check if the install was successful with the command below. It should return a label and score for the provided text.

Terminal window
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

Editable install

Section titled “Editable install”

An editable install is useful if you’re developing locally with Transformers. It links your local copy of Transformers to the Transformers repository instead of copying the files. The files are added to Python’s import path.

Terminal window
git clone https://github.com/huggingface/transformers.git
cd transformers
uv pip install -e .

Update your local version of Transformers with the latest changes in the main repository with the following command.

Terminal window
cd ~/transformers/
git pull

conda

Section titled “conda”

conda is a language-agnostic package manager. Install Transformers from the conda-forge channel in your newly created virtual environment.

Terminal window
conda install conda-forge::transformers

Set up

Section titled “Set up”

After installation, you can configure the Transformers cache location or set up the library for offline usage.

Cache directory

Section titled “Cache directory”

When you load a pretrained model with from_pretrained, the model is downloaded from the Hub and locally cached.

Every time you load a model, it checks whether the cached model is up-to-date. If it’s the same, then the local model is loaded. If it’s not the same, the newer model is downloaded and cached.

The default directory given by the shell environment variable HF_HUB_CACHE is ~/.cache/huggingface/hub. On Windows, the default directory is C:\Users\username\.cache\huggingface\hub.

Cache a model in a different directory by changing the path in the following shell environment variables (listed by priority).

  1. HF_HUB_CACHE (default)
  2. HF_HOME
  3. XDG_CACHE_HOME + /huggingface (only if HF_HOME is not set)

Offline mode

Section titled “Offline mode”

To use Transformers in an offline or firewalled environment requires the downloaded and cached files ahead of time. Download a model repository from the Hub with the snapshot_download method.

from huggingface_hub import snapshot_download


snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")

Set the environment variable HF_HUB_OFFLINE=1 to prevent HTTP calls to the Hub when loading a model.

Terminal window
HF_HUB_OFFLINE=1 \
python examples/pytorch/language-modeling/run_clm.py --model_name_or_path meta-llama/Llama-2-7b-hf --dataset_name wikitext ...

Another option for only loading cached files is to set local_files_only=True in from_pretrained.

from transformers import LlamaForCausalLM


model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True)