Virtuální prostředí v Pythonu: venv vs. uv v praxi

Každý Python projekt má vlastní závislosti a jejich verze. Když je instalujete globálně, dřív nebo později si dva projekty začnou přetahovat o stejnou knihovnu. Virtuální prostředí tento problém řeší: každý projekt dostane vlastní izolovanou složku s interpretem a balíčky.

Co virtuální prostředí vlastně je

Virtuální prostředí je obyčejný adresář (typicky .venv), který obsahuje odkaz na interpret Pythonu, vlastní site-packages a aktivační skripty. Po aktivaci se příkazy python a pip odkazují právě do této složky. Nic magického, žádný kontejner – jen jiná cesta v PATH.

Klasika: venv + pip

Modul venv je součástí standardní knihovny od Pythonu 3.3, takže ho nemusíte instalovat. Na Debianu a Ubuntu je ale potřeba systémový balíček:

sudo apt install python3-venv

Vytvoření a aktivace prostředí:

python3 -m venv .venv
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\activate         # Windows (cmd)
# .venv\Scripts\Activate.ps1     # Windows (PowerShell)

Po aktivaci uvidíte v promptu (.venv). Instalace balíčků:

pip install requests rich
pip freeze > requirements.txt

Na jiném stroji pak prostředí obnovíte:

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

Deaktivace je prostě deactivate.

Časté chyby

Commitování .venv do gitu. Přidejte .venv/ do .gitignore. Prostředí se vždy vytváří znovu.
Přesunutí složky. Virtuální prostředí obsahuje absolutní cesty. Po přesunu projektu ho smažte a vytvořte znovu.
pip freeze bez rozmyslu. Vypíše úplně všechno včetně tranzitivních závislostí. U menších projektů to nevadí, u větších je lepší udržovat seznam přímých závislostí v pyproject.toml.
Na Debianu 12+ a Ubuntu 23.04+ vám pip install mimo venv zahlásí externally-managed-environment. To je správně – systémový Python nechte systému.

Moderní cesta: uv

uv je správce balíčků a projektů od firmy Astral napsaný v Rustu. Nahrazuje pip, venv, pip-tools, částečně i pyenv a pipx, a je řádově rychlejší díky paralelnímu stahování a globální cache.

Instalace:

curl -LsSf https://astral.sh/uv/install.sh | sh
# nebo
pipx install uv

uv jako rychlejší pip

Pokud chcete jen zrychlit stávající workflow, uv má rozhraní kompatibilní s pipem:

uv venv                       # vytvoří .venv
source .venv/bin/activate
uv pip install -r requirements.txt

uv jako správce projektu

Plnohodnotné použití vypadá jinak – uv spravuje pyproject.toml a zamykací soubor uv.lock:

uv init muj-projekt
cd muj-projekt
uv add httpx pydantic
uv add --dev pytest
uv run python main.py
uv run pytest

Co se stane:

uv add zapíše závislost do pyproject.toml, aktualizuje uv.lock a nainstaluje ji do .venv.
uv run před spuštěním ověří, že prostředí odpovídá zámku, a případně ho synchronizuje. Nemusíte nic aktivovat.
uv sync na jiném stroji nainstaluje přesně verze ze zámku.

Správa verzí Pythonu

uv umí stáhnout i samotný interpret:

uv python install 3.12
uv venv --python 3.12
uv python pin 3.12   # zapíše .python-version

Srovnání

	venv + pip	uv
Součást Pythonu	ano	ne, samostatný binární soubor
Rychlost instalace	standardní	výrazně rychlejší
Zamykací soubor	ne (jen `requirements.txt`)	`uv.lock`
Instalace verzí Pythonu	ne	ano
Spouštění bez aktivace	ne	`uv run`

Co zvolit

Malý skript, výuka, server bez možnosti instalovat další nástroje: venv + pip stačí a funguje všude.
Nový projekt, tým, CI: uv. Reprodukovatelný zámek a rychlost se vyplatí hned při první instalaci v CI.
Existující projekt s requirements.txt: začněte s uv pip install -r requirements.txt a na plný režim přejděte, až budete chtít.

Jak ověřit, že jste ve správném prostředí

which python          # Linux / macOS
python -c "import sys; print(sys.prefix)"

Výstup by měl ukazovat do složky .venv vašeho projektu. Pokud ukazuje na /usr, prostředí aktivní není a balíčky se instalují jinam, než čekáte.

Pokud vám prostředí zlobí (např. ModuleNotFoundError, i když balíček „určitě“ máte), vložte výstup těchto příkazů do ColdHost AI v režimu Řešení problémů – rozdíl mezi interpretem a místem instalace bývá vidět hned.