Środowiska wirtualne w Pythonie: venv, aktywacja i requirements.txt

Problem, który rozwiązują środowiska wirtualne

Instalujesz Pythona, uruchamiasz pip install requests i pakiet trafia do jednego, globalnego miejsca. Przy jednym projekcie to działa. Przy trzecim zaczyna boleć:

• Projekt A potrzebuje django==3.2. Projekt B potrzebuje django==5.0. Globalnie może być zainstalowana tylko jedna z tych wersji.
• Chcesz wypróbować nową bibliotekę, ale nie chcesz, żeby zaśmiecała każdy inny projekt na twoim komputerze.
• Osoba z zespołu klonuje twoje repozytorium i nie ma pojęcia, od których wersji których pakietów faktycznie zależy projekt.

Rozwiązaniem jest środowisko wirtualne. To samodzielny folder z interpreterem Pythona i własnym katalogiem na biblioteki. Gdy środowisko jest aktywne, python i pip w terminalu wskazują ten folder zamiast systemowego Pythona. Zainstalowane tam pakiety tam zostają.

Tworzenie środowiska przez venv

venv jest dołączony do Pythona 3, więc nie trzeba niczego instalować. W katalogu projektu uruchom:

python3 -m venv .venv

Obok twojego kodu powstanie folder .venv/. Nazwa .venv to niemal powszechna konwencja; kropka na początku ukrywa go w większości listingów katalogów, a edytory takie jak VS Code automatycznie go wykrywają.

Po zakończeniu polecenia folder zawiera pełną instalację Pythona (kilkadziesiąt megabajtów, to normalne) i własny pip.

Aktywowanie środowiska

Aktywacja zmienia PATH twojej powłoki tak, żeby python i pip wskazywały te z .venv/. Polecenie zależy od platformy:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Gdy środowisko jest aktywne, znak zachęty dostaje przedrostek (.venv), który służy jako wizualne przypomnienie. Każde pip install uruchomione teraz dotyczy tylko tego projektu.

Po skończonej pracy deactivate przywraca poprzedni stan:

deactivate

Nie musisz dezaktywować środowiska przed zamknięciem terminala: wyjście z powłoki daje ten sam efekt.

Instalowanie pakietów

Przy aktywnym środowisku zainstaluj to, czego potrzebujesz:

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

Listę zainstalowanych pakietów sprawdzisz przez pip list. Usuniesz coś przez pip uninstall requests.

Zainstalowane pakiety leżą w .venv/lib/pythonX.Y/site-packages/. Nigdy nie edytujesz ich ręcznie: tym katalogiem zarządza pip.

Przypinanie zależności w requirements.txt

Projekt da się odtworzyć tylko wtedy, gdy inni mogą zainstalować te same wersje, których używasz. Najprościej zapisać je w requirements.txt:

pip freeze > requirements.txt

pip freeze wypisuje każdy zainstalowany pakiet z dokładną wersją. Dodaj ten plik do gita.

Gdy współpracownik (albo ty w przyszłości na nowym komputerze) sklonuje repozytorium:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Trzy polecenia i środowisko jest takie samo jak twoje.

Typowa konfiguracja projektu

Cały proces od początku do końca:

# Utwórz folder projektu
mkdir my_tool && cd my_tool

# Utwórz i aktywuj venv
python3 -m venv .venv
source .venv/bin/activate

# Zainstaluj zależności
pip install requests rich

# Zapisz je
pip freeze > requirements.txt

# Pracuj nad kodem...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# Gdy skończysz
deactivate

Dodaj .venv do .gitignore

Nigdy nie dodawaj folderu .venv/ do repozytorium. Jest zależny od platformy i da się go odtworzyć z requirements.txt:

# .gitignore
.venv/
__pycache__/
*.pyc

Dodanie go rozdęłoby repozytorium, psułoby się na innych komputerach i ujawniałoby binaria specyficzne dla systemu, których używa twój interpreter.

Która wersja Pythona?

Domyślnie python3 -m venv .venv używa tego python3, który znajdzie twoja powłoka. Jeśli masz zainstalowanych kilka wersji Pythona (na przykład 3.12 i 3.13), podaj wprost, której chcesz:

python3.13 -m venv .venv

Gdy venv już istnieje, jego interpreter jest przypięty: python uruchomiony w aktywnym venv zawsze używa tej konkretnej wersji, nawet jeśli systemowy Python się zmieni.

Gdy coś idzie nie tak

Kilka typowych objawów i sposobów naprawy:

• pip install działa, ale importy się nie udają. Pakiet trafił do złego Pythona. Aktywuj venv przed pip install i sprawdź ponownie przez which python (macOS/Linux) albo where python (Windows).
• "ModuleNotFoundError" po aktywacji. Venv powstał bez pewnych bibliotek albo pakiet zainstalował się w innym venv. pip list pokazuje, co faktycznie jest w bieżącym.
• Skrypt aktywacji nie działa w Windows. PowerShell może blokować niepodpisane skrypty. Uruchom raz Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, żeby zezwolić na lokalne skrypty.
• "No module named venv". W niektórych dystrybucjach Linuksa venv to osobny pakiet. Na Debianie/Ubuntu: sudo apt install python3-venv.

Poza venv: Poetry, uv, pipenv

Gdy poczujesz się pewnie z venv + pip + requirements.txt, trafisz na narzędzia, które opakowują te same pomysły w wygodniejszą formę:

• Poetry: zarządza środowiskami venv, zależnościami i budowaniem pakietów za pomocą jednego pliku pyproject.toml.
• uv: bardzo szybki zamiennik pip, który obsługuje też venv.
• pipenv: starsze narzędzie, które spopularyzowało wzorzec "Pipfile + Pipfile.lock".

Wszystkie są dobre. Żadne nie jest wymagane do nauki. Najpierw oswój się ze zwykłym przepływem venv; reszta to optymalizacje.

Co warto zapamiętać

• Każdy prawdziwy projekt w Pythonie dostaje własne środowisko wirtualne.
• Utwórz je przez python3 -m venv .venv, aktywuj, a potem swobodnie używaj pip install.
• Przypinaj zależności przez pip freeze > requirements.txt i dodaj ten plik do repozytorium.
• Nigdy nie dodawaj do repozytorium samego folderu .venv/.
• Gdy importy działają dziwnie, najpierw sprawdź, który Python jest aktywny.

Dalej: wzorzec __main__

Gdy projekt jest skonfigurowany, a pakiety zainstalowane, ten rozdział zamyka jeszcze jeden idiom: strażnik if __name__ == "__main__". Jest w prawie każdym pliku Pythona przeznaczonym do uruchamiania jako skrypt i to temat następnej strony.