#Installation

#Requirements

• Python 3.10+ (3.11 / 3.12 recommended)
• pip (or uv / conda)
• Disk: the Hub cache grows—leave several GB
• GPU optional: classification and tiny generation run on CPU; full fine-tunes prefer CUDA / MPS

Tensors and torch.device are covered in this site’s PyTorch tutorial.

#Virtual environment

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

#Install PyTorch

Install a PyTorch build that matches your machine before Transformers, so pip does not pull the wrong CUDA wheel:

# CPU example; copy a GPU command from https://pytorch.org
pip install torch

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

#Install the Transformers stack

The official starter set:

pip install -U transformers datasets evaluate accelerate

Add as needed:

pip install huggingface_hub   # hf CLI, login, push
pip install peft              # LoRA, used in the fine-tune chapter
pip install sentencepiece     # some tokenizers
pip install soundfile         # Whisper and other audio

Verify:

python -c "import transformers, datasets; print(transformers.__version__)"

#Log in: hf auth login

huggingface_hub ships the hf CLI. Public ungated models download without login. Uploads, private repos, and some datasets need a token.

hf auth login

Authorize in the browser or paste an Access Token (write scope only if you push_to_hub). Check identity:

hf auth whoami

Or use an env var (CI / scripts; never commit it):

export HF_TOKEN="hf_..."

$env:HF_TOKEN = "hf_..."

huggingface-cli login may still work; current docs use hf auth login.

#GPU and load tips

On a consumer GPU, large models typically load like this:

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-0.5B-Instruct",
    device_map="auto",
    dtype="auto",
)

You can finish this course without a GPU: use DistilBERT / DistilGPT2 / Whisper-tiny and omit device_map or set it to cpu. Full-parameter 7B fine-tuning is not a beginner exercise.

#Cache and networks

The default cache is ~/.cache/huggingface (override with HF_HOME). Repeated from_pretrained calls hit disk.

If Hub downloads stall, use a proxy or a documented mirror endpoint. Never paste a token into a notebook you will publish.

#Suggested layout

my-hf-lab/
├── .venv/
├── .gitignore          # ignore .venv, .env, *.pt
├── requirements.txt
├── classify.py
└── outputs/            # Trainer output_dir

Minimum requirements.txt: torch, transformers, datasets, evaluate, accelerate.

#Troubleshooting

hf is not recognized?
pip install huggingface_hub, then reactivate the venv.

Downloads hang?
Check the network; switch to this course’s ungated tiny models; HF_HUB_ENABLE_HF_TRANSFER=1 sometimes helps.

CUDA out of memory?
Lower per_device_train_batch_size, use LoRA, or switch to 0.5B / DistilBERT. For casual local chat, try Ollama.

Windows login wants Git?
Pass --no-add-to-git-credential, or install Git for Windows.

#Next steps

• Quick Start
• Pipeline