Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 38 ยท Getting Started

Installation and Environment Setup

Install transformers, PyTorch and friends in a clean virtual environment, pick the right device, understand the cache folder and log in to the Hub safely.

Setting up Transformers is mostly about three decisions: which Python environment to use, which deep-learning backend to install, and where models should live on disk. Getting them right once saves hours of confusing errors later.

The library supports PyTorch as its main backend. Older TensorFlow and JAX/Flax support exists for some models, but new work, new models and the Trainer all target PyTorch, so this course uses it.

A clean environment

Always work inside a virtual environment so library versions do not clash with other projects. These are shell commands, shown read-only.

Terminal
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install torch                  # pick the build that matches your GPU on pytorch.org
pip install transformers datasets evaluate accelerate

A short explanation of each package:

  • torch: tensors and automatic differentiation. Choose a CPU-only build or a CUDA build on the PyTorch install page.
  • transformers: models, tokenizers, pipelines and Trainer.
  • datasets: data loading and preprocessing.
  • evaluate: metrics such as accuracy, F1 and ROUGE.
  • accelerate: runs the same training code on one GPU, many GPUs or a CPU.

Check what you have installed:

Python
import torch, transformers
print(transformers.__version__)
print(torch.__version__, torch.cuda.is_available())

If the second value prints False on a machine with an NVIDIA GPU, you probably installed the CPU build of PyTorch. Reinstall with the CUDA command from the PyTorch website.

Choosing a device

Computation happens on a device: cpu, cuda (NVIDIA GPUs), mps (Apple silicon) or others. Models and input tensors must be on the same device. The usual pattern is to pick the best available one:

Python
import torch

if torch.cuda.is_available():
    device = "cuda"
elif torch.backends.mps.is_available():
    device = "mps"
else:
    device = "cpu"

In pipelines you can pass device=0 for the first GPU, or device_map="auto" to let accelerate place a large model across GPUs and CPU memory.

The following runnable program is a stand-in for that decision logic: it takes a description of a machine and picks a device, so you can practise the branching without any hardware.

Python Stand-in: pick a device

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Where files go: the cache

The first time you load a model, files are downloaded into a cache folder and reused afterwards. By default it is ~/.cache/huggingface. Models are big, so you may want to move it to a larger disk with an environment variable.

Terminal
export HF_HOME=/data/hf-cache          # models, datasets, tokens
export HF_HUB_OFFLINE=1                # never touch the network, use cached files only

The cache stores each repository by its git commit hash, so several versions of a model can live side by side and a changed model is downloaded again. Use huggingface-cli scan-cache to see what takes space.

Logging in

Many models (for example gated ones such as Llama) and all uploads need an access token. Create one in your Hub account settings with the smallest role you need (read for downloads, write for uploads), then log in:

Terminal
huggingface-cli login

Never paste a token into code you share, commit it to Git or print it. In CI, store it as a secret and pass it as the HF_TOKEN environment variable; the libraries pick it up automatically.

If a download is interrupted or a file looks corrupted, delete that model's folder in hub/ inside the cache and load it again. Nothing else breaks.

Checking an environment as data

Support questions often start with "what versions do you have?". The stand-in below builds a tiny environment report and flags mismatches. It uses a made-up requirements table, not real pip data.

Python Stand-in: compare versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that versions are compared as tuples of integers, never as strings: as text, "4.9" > "4.10", which is wrong.

Working in notebooks and Colab

Free notebook services give you a GPU without any setup. Install with !pip install transformers datasets in the first cell, enable a GPU runtime, and remember that files on the notebook disk vanish when the session ends. Push finished models to the Hub or save them to cloud storage.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why use a virtual environment?

    A virtual environment keeps each project's dependencies separate, avoiding version clashes.
  2. 2. Which environment variable moves the Hugging Face cache?

    HF_HOME controls where models, datasets and tokens are stored.
  3. 3. torch.cuda.is_available() returns False on a GPU machine. What is the likely cause?

    The default pip wheel on some systems is CPU-only. Install the CUDA build from the PyTorch site.
  4. 4. Where should an access token live in a CI job?

    Tokens are credentials. Keep them in a secret store and expose them as an environment variable.

Summary

  • Use a virtual environment, install torch first, then transformers, datasets, evaluate and accelerate.
  • Pick cuda, mps or cpu deliberately and keep model and tensors on the same device.
  • Models are cached under HF_HOME; move it to a big disk and use offline mode when needed.
  • Treat access tokens as secrets and give them the smallest role.

Next: The Transformer Architecture in One Lesson