Installation

Purpose and Scope

This page explains how to get Hugging Face Transformers running in a clean Python environment, choose the right backend installation path, and verify that the library can download and execute a pretrained model. The installation docs position Transformers as a PyTorch-based library tested on Python 3.10+ and PyTorch 2.4+, so the first practical decision is whether you are installing for normal inference and training, CPU-only development, GPU acceleration, or local contribution work. The same installation surface is published across localized docs, with the English page using uv commands and older localized pages showing equivalent pip, venv, and conda flows.

Sources: docs/source/en/installation.md, docs/source/de/installation.md, docs/source/es/installation.md, docs/source/fr/installation.md, docs/source/it/installation.md, docs/source/ar/installation.md

Transformers itself is the Python package that exposes APIs such as pipeline, model classes, tokenizers, processors, and training utilities. PyTorch is the primary deep learning backend named by the current installation page, and CUDA drivers are only needed when you want NVIDIA GPU acceleration. A virtual environment is recommended because it isolates the Transformers package and its backend dependencies from the rest of your system Python packages. That isolation matters for this repository because users often switch between stable releases, source installs from main, and editable installs for development.

Relevant Source Files

• docs/source/en/installation.md — current English installation guide with uv, Python 3.10+, PyTorch 2.4+, GPU check, CPU-only PyTorch install, source install, editable install, and pipeline verification commands.
• docs/source/ar/installation.md — Arabic localized installation guide preserving the broader installation scope: backend setup, cache configuration, optional offline use, pip install, source install, editable install, conda, and verification.
• docs/source/de/installation.md — German localized installation guide showing virtual environment creation, platform-specific activation, pip install transformers, transformers[torch], source install, and editable-install intent.
• docs/source/es/installation.md — Spanish localized installation guide documenting virtual environments, pip install, CPU-oriented backend extra, source installation from GitHub, and local editable development use cases.
• docs/source/fr/installation.md — French localized installation guide confirming Python and PyTorch requirements, virtual environment workflow, CPU-only backend installation, source install, and editable install for contributors.
• docs/source/it/installation.md — Italian localized installation guide with the same user-facing sequence for project environments, PyTorch-oriented installation, source install, editable install, and verification.

Environment and Backend Requirements

The supported baseline in the current English installation guide is straightforward: use Python 3.10 or newer and PyTorch 2.4 or newer. The localized pages repeat this compatibility framing and direct readers to the PyTorch installation instructions for backend-specific setup. In practice, that means Transformers is not the component that selects your CUDA toolkit or CPU wheel; PyTorch does. Install the correct PyTorch build first, or use the CPU-only command shown in the docs when you deliberately want a non-GPU environment.

Sources: docs/source/en/installation.md, docs/source/fr/installation.md, docs/source/it/installation.md

For GPU acceleration, the installation guide tells you to install the appropriate CUDA drivers for PyTorch and then run nvidia-smi to verify that the system can see an NVIDIA GPU. Treat this as a hardware and driver check rather than a Transformers-specific command. If nvidia-smi fails, installing Transformers again will not usually solve the problem; fix the driver, container, or PyTorch CUDA installation first. Once PyTorch can access the GPU, Transformers model and pipeline APIs can use that backend through normal PyTorch execution paths.

nvidia-smi

Installing with a Virtual Environment

The recommended first step is to create an isolated project environment. The current English guide uses uv, a Rust-based Python package and project manager, because it creates and manages virtual environments by default and can act as a drop-in replacement for pip. If you prefer plain pip, the same conceptual flow applies: create a virtual environment, activate it, then install packages into that environment. The localized docs show the traditional python -m venv .env command, which is still useful for readers not using uv.

Sources: docs/source/en/installation.md, docs/source/de/installation.md, docs/source/es/installation.md

uv venv .env
source .env/bin/activate
uv pip install transformers

On Linux and macOS, activation uses source .env/bin/activate; the localized German, French, and Arabic pages also call out Windows activation with .env/Scripts/activate. Keeping activation explicit helps avoid a common setup mistake: installing Transformers into one Python interpreter and then running examples with another. When the shell prompt is inside the environment, commands such as python -c ... and uv pip install ... resolve against the same project-local interpreter.

python -m venv .env
source .env/bin/activate
pip install transformers

CPU, GPU, and Backend Install Options

For a standard stable release, install the published package with uv pip install transformers or, in the localized pip-oriented docs, pip install transformers. If you are intentionally using CPU-only PyTorch, the current English docs install the CPU PyTorch wheel from the PyTorch CPU index before installing Transformers. Older localized docs also show the convenience extra transformers[torch], which installs Transformers together with PyTorch-oriented dependencies. Choose the form that matches the package manager and backend policy for your environment.

Sources: docs/source/en/installation.md, docs/source/ar/installation.md, docs/source/de/installation.md, docs/source/fr/installation.md

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

pip install 'transformers[torch]'

A working install should be tested with a real import and inference call, not only by checking that the package appears in pip list. The installation docs use pipeline('sentiment-analysis') because it exercises the public transformers import, downloads a pretrained model, runs preprocessing and inference, and returns a label and score. This is a compact end-to-end signal that your Python environment, package install, model download path, and backend runtime are all functioning together.

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"

Expected output is a positive sentiment label with a high score, for example:

[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

Source and Editable Installs

A source install pulls the latest code from the Transformers GitHub repository instead of installing the latest stable package release. The docs recommend this when you need a change that has landed on main but has not yet been released, or when you want to experiment with the newest features. The tradeoff is stability: the current development branch is maintained actively, but it can include changes that have not gone through the same release cycle as the packaged version.

Sources: docs/source/en/installation.md, docs/source/es/installation.md, docs/source/it/installation.md

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

An editable install is different from a one-time source install. It links the local clone into Python’s import path so changes in your checkout are reflected when you import Transformers. This is the right mode for contributors and for developers testing local modifications against examples or downstream code. The docs warn that the local folder must remain in place, because Python is importing from that linked checkout rather than from a copied package directory inside site-packages.

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

Cache, Offline Readiness, and Verification Flow

The localized installation pages frame cache setup and optional offline operation as part of installation, because Transformers commonly downloads model files from the Hugging Face Hub during the first successful inference call. The verification command is therefore more than a smoke test: it confirms that the environment can reach the model source, write downloaded artifacts into the configured cache, and reuse the backend to produce an output. For fully offline systems, prepare the cache while online or configure the relevant cache and offline environment settings before running workloads.

Sources: docs/source/ar/installation.md, docs/source/de/installation.md, docs/source/fr/installation.md, docs/source/it/installation.md

When debugging installation, follow the same order as the docs’ workflow. First confirm that you are inside the intended virtual environment. Next confirm that the Python and PyTorch versions meet the documented baseline. Then check GPU visibility with nvidia-smi if you expect CUDA acceleration. Finally, run the sentiment-analysis pipeline command and inspect whether the failure happens during import, model download, or inference. Those phases point to different fixes: package resolution, network or cache configuration, or backend runtime setup.

System-to-Code Mapping

Next Steps

After installation succeeds, continue with the Quickstart to load models, tokenizers, processors, and pipelines in normal application code. If your environment is constrained by network access or shared storage, read the Environment Variables page next so cache and offline behavior are explicit rather than accidental. If you installed from source or editable mode because you plan to contribute, move to the Contributor Guide before changing model, tokenizer, processor, or documentation files.