uv

Praktický učební text o nástroji uv: od instalace přes inicializaci projektu a práci se závislostmi až po spouštění, sestavení a publikaci balíčků. Předpokládá se základní znalost Pythonu a příkazové řádky.

1. Co je uv

uv je rychlý správce Pythonu, projektů a balíčků od firmy Astral (tvůrci nástroje Ruff). Je napsaný v Rustu a v jednom programu nahrazuje celou sadu dřívějších nástrojů: pip, pip-tools, virtualenv, pyenv, pipx a velkou část funkcí Poetry či PDM.

Hlavní myšlenky:

  • Rychlost: instalace a řešení závislostí je řádově rychlejší než u pipu díky paralelizaci a globální cache.
  • Jeden nástroj: verze Pythonu, virtuální prostředí, závislosti, skripty, nástroje i publikace.
  • Reprodukovatelnost: soubor uv.lock zamyká přesné verze všech závislostí napříč platformami.
  • Standardy: projekt se konfiguruje v pyproject.toml podle PEP 621, takže zůstává přenositelný.
  • Automatika: prostředí .venv se vytváří a synchronizuje samo při uv run, uv sync a uv add.

Pozor: Nástroj se vyvíjí rychle. Přesné možnosti vždy ověřte pomocí uv --help nebo uv <příkaz> --help.

2. Instalace

Linux a macOS:

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

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternativy:

brew install uv          # Homebrew
pipx install uv          # přes pipx
pip install uv           # přes pip

Kontrola a aktualizace:

uv --version
uv self update           # jen u instalace oficiálním skriptem

Doplňování příkazů v shellu bash zapnete takto:

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

3. Správa verzí Pythonu

uv umí stáhnout a spravovat samotné interpretery Pythonu, takže nepotřebujete pyenv.

uv python list               # dostupné a nainstalované verze
uv python install 3.13       # nainstaluje Python 3.13
uv python install 3.12 3.13  # více verzí najednou
uv python find               # který interpreter uv použije
uv python pin 3.12           # zapíše verzi do .python-version
uv python uninstall 3.12

Pokud projekt vyžaduje verzi, kterou nemáte, uv ji při uv run nebo uv sync automaticky stáhne. Soubor .python-version určuje výchozí verzi pro daný adresář.

4. Inicializace projektu

Nový projekt

uv init muj-projekt
cd muj-projekt

Vznikne tato struktura:

muj-projekt/
├── .git/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

Soubor pyproject.toml vypadá zhruba takto:

[project]
name = "muj-projekt"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

Prostředí .venv a soubor uv.lock vzniknou při prvním uv add, uv sync nebo uv run.

Varianty uv init

Příkaz Účel
uv init inicializace v aktuálním adresáři
uv init --app aplikace (výchozí chování)
uv init --package balíček se strukturou src/ a build backendem
uv init --lib knihovna (balíček se strukturou src/ a typovým markerem py.typed)
uv init --python 3.12 určení verze Pythonu
uv init --no-readme --vcs none minimální výstup bez README a gitu

Pro balíček se vytvoří struktura src/muj_projekt/__init__.py a v pyproject.toml sekce [build-system]. Díky tomu se projekt nainstaluje do prostředí v editovatelném režimu.

5. Závislosti

Přidání a odebrání

uv add requests                  # přidá nejnovější kompatibilní verzi
uv add "fastapi>=0.110"          # s omezením verze
uv add "httpx[http2]"            # s extras
uv add -r requirements.txt       # import ze souboru
uv remove requests               # odebrání

uv add udělá tři věci najednou: upraví pyproject.toml, aktualizuje uv.lock a nainstaluje balíček do .venv.

Vývojové skupiny

uv add --dev pytest ruff         # skupina "dev"
uv add --group docs mkdocs       # vlastní skupina

Výsledek v pyproject.toml:

[dependency-groups]
dev = ["pytest>=8", "ruff>=0.6"]
docs = ["mkdocs>=1.6"]

Skupina dev se instaluje ve výchozím stavu. Ostatní zapnete přes --group, vypnete přes --no-group (u dev také --no-dev).

Volitelné závislosti (extras)

uv add --optional plotting matplotlib

Vytvoří sekci [project.optional-dependencies], kterou uživatelé knihovny zapnou jako muj-projekt[plotting].

Jiné zdroje než PyPI

uv add git+https://github.com/psf/requests
uv add ./lokalni-balicek
uv add --editable ../sdilena-knihovna
uv add torch --index pytorch=https://download.pytorch.org/whl/cpu

Alternativní zdroje se zapisují do [tool.uv.sources] a vlastní indexy do [[tool.uv.index]].

Prohlížení závislostí

uv tree                          # strom závislostí
uv tree --outdated               # co má novější verzi
uv tree --invert                 # obrácený strom: kdo na balíčku závisí

6. Lock soubor a synchronizace

uv.lock je přesný, platformně nezávislý záznam všech verzí včetně kontrolních součtů. Generuje se automaticky, patří do verzovacího systému a ručně se needituje.

uv lock                          # vytvoří/aktualizuje uv.lock
uv lock --upgrade                # povýší vše v rámci omezení
uv lock --upgrade-package requests
uv sync                          # nainstaluje přesně to, co je v uv.lock
uv sync --locked                 # selže, pokud je lock zastaralý (CI)
uv sync --frozen                 # použije lock bez kontroly aktuálnosti
uv sync --no-dev                 # bez vývojových závislostí
uv sync --all-extras             # včetně volitelných závislostí
uv sync --group docs             # včetně skupiny docs

Rozdíl: uv lock řeší verze, uv sync je instaluje do prostředí. uv sync také odstraní balíčky, které v locku nejsou, takže prostředí přesně odpovídá projektu.

Pro nástroje, které uv neznají, lze lock převést na requirements.txt:

uv export --format requirements-txt -o requirements.txt

7. Spouštění projektu

uv run main.py                   # spustí skript v projektovém prostředí
uv run python                    # interaktivní interpreter
uv run -m pytest                 # spuštění modulu
uv run pytest -q                 # spuštění nainstalovaného nástroje
uv run --with rich main.py       # dočasně přidá balíček
uv run --python 3.11 main.py     # jiná verze Pythonu
uv run --no-sync main.py         # bez synchronizace prostředí

Před každým během uv run zkontroluje, že uv.lock a .venv odpovídají pyproject.toml, a případně je opraví. Prostředí proto nemusíte ručně aktivovat. Pokud ho přesto chcete aktivovat, klasicky:

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

Vlastní příkazy projektu

Pokud má balíček (projekt vytvořený s --package) definovaný vstupní bod, spustíte ho jménem:

[project.scripts]
muj-cli = "muj_projekt:main"
uv run muj-cli --help

uv nemá vestavěný spouštěč úloh jako npm scripts. Pro opakované úlohy se obvykle používá Makefile, just nebo poethepoet.

8. Samostatné skripty (PEP 723)

Jednosouborové skripty mohou mít závislosti uvedené přímo v hlavičce. uv pro ně vytvoří izolované dočasné prostředí.

uv init --script prehled.py --python 3.12
uv add --script prehled.py requests rich

Hlavička souboru pak obsahuje inline metadata:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests",
#   "rich",
# ]
# ///

import requests
from rich import print
print(requests.get("https://example.com").status_code)
uv run prehled.py

Skript lze také udělat spustitelným: na první řádek přidejte shebang #!/usr/bin/env -S uv run --script a nastavte chmod +x prehled.py.

9. Nástroje (uvx a uv tool)

Pro samostatné aplikace příkazové řádky (ruff, black, httpie, cookiecutter) slouží příkazy, které nahrazují pipx.

uvx ruff check .                 # jednorázové spuštění v dočasném prostředí
uv tool run ruff --version       # totéž, delší zápis
uvx --from httpie http GET example.com   # když se název balíčku liší od příkazu

uv tool install ruff             # trvalá instalace do izolovaného prostředí
uv tool list
uv tool upgrade ruff
uv tool upgrade --all
uv tool uninstall ruff
uv tool update-shell             # přidá adresář nástrojů do PATH

Každý nainstalovaný nástroj má vlastní virtuální prostředí, takže se jeho závislosti nemíchají s projektem.

10. Rozhraní uv pip

Pro starší postupy nebo postupnou migraci nabízí uv rozhraní kompatibilní s pipem, tedy bez práce s pyproject.toml a uv.lock.

uv venv                          # vytvoří .venv
uv venv --python 3.12 prostredi
uv pip install requests
uv pip install -r requirements.txt
uv pip install -e .
uv pip list
uv pip freeze > requirements.txt
uv pip uninstall requests
uv pip compile requirements.in -o requirements.txt   # náhrada pip-compile
uv pip sync requirements.txt                          # náhrada pip-sync

Pro nové projekty se doporučuje projektové rozhraní (uv add, uv sync, uv run), protože poskytuje lock soubor a automatickou správu prostředí.

11. Build a publikace

uv build                         # vytvoří sdist a wheel v adresáři dist/
uv build --wheel
uv version                       # zobrazí verzi projektu
uv version --bump minor          # zvýší minor verzi
uv publish                       # nahraje dist/* na PyPI
uv publish --token pypi-XXXX
uv publish --index testpypi      # index definovaný v pyproject.toml (s publish-url)

Pro publikaci projekt potřebuje sekci [build-system], která vzniká při uv init --package, například s backendem uv_build:

[build-system]
requires = ["uv_build>=X.Y,<X.Z"]
build-backend = "uv_build"

Konkrétní rozsah verzí doplní uv init --package podle nainstalované verze uv. Funguje i jakýkoli jiný standardní backend (hatchling, setuptools, flit). Doporučená je publikace přes Trusted Publishing z CI, bez ukládání tokenů.

12. Workspaces

Workspace sdružuje více vzájemně souvisejících balíčků (monorepo) pod jedním lock souborem.

# kořenový pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

# v balíčku, který závisí na jiném členu
[project]
dependencies = ["spolecne"]

[tool.uv.sources]
spolecne = { workspace = true }
uv sync --all-packages
uv run --package api pytest
uv init packages/novy-balicek    # přidá nového člena

13. Cache a konfigurace

Cache

uv ukládá stažené a sestavené balíčky do globální cache a do prostředí je zpřístupňuje pomocí hardlinků (nebo kopií), proto jsou opakované instalace tak rychlé.

uv cache dir                     # kde cache leží
uv cache clean                   # smaže celou cache
uv cache prune                   # odstraní nepoužívané položky

Konfigurace

Nastavení se čte (od nejvyšší priority) z příkazové řádky, proměnných prostředí, projektové konfigurace a uživatelského souboru ~/.config/uv/uv.toml. Projektovou konfiguraci tvoří sekce [tool.uv] v pyproject.toml, nebo soubor uv.toml v adresáři projektu. Pokud existují oba, má uv.toml přednost a [tool.uv] se ignoruje.

[tool.uv]
python-preference = "managed"    # preferovat interpretery spravované uv

Užitečné proměnné prostředí: UV_PYTHON, UV_CACHE_DIR, UV_DEFAULT_INDEX (náhrada PyPI jiným indexem), UV_PROJECT_ENVIRONMENT (jiné umístění prostředí než .venv).

14. Docker a CI

GitHub Actions

- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v6
  with:
    enable-cache: true
- run: uv sync --locked
- run: uv run pytest

Čísla verzí akcí (@v4, @v6) zkontrolujte v jejich repozitářích a používejte aktuální hlavní verzi.

Dockerfile

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
WORKDIR /app
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-dev --no-install-project
COPY . .
RUN uv sync --locked --no-dev
CMD ["uv", "run", "--no-sync", "python", "main.py"]

Rozdělení do dvou kroků uv sync využije vrstvovou cache Dockeru: závislosti se přeinstalují jen při změně pyproject.toml či uv.lock. Pro produkci připněte konkrétní verzi obrazu uv (např. uv:0.9.5) místo latest. Adresář .venv přidejte do .dockerignore.

Alternativní přístup s conda-forge balíčky popisuje návod Python v Dockeru s micromambou.

15. Migrace z pip a Poetry

Z requirements.txt

uv init
uv add -r requirements.txt
uv add --dev -r requirements-dev.txt

Z Poetry

Projekty se starším formátem [tool.poetry] je nutné převést do standardní sekce [project]. Pomůže nástroj migrate-to-uv (uvx migrate-to-uv). Poté:

uv lock
uv sync

Srovnání pojmů

Úkol pip / venv Poetry uv
Nový projekt ručně poetry new uv init
Přidat balíček pip install x poetry add x uv add x
Instalace z locku pip install -r poetry install uv sync
Spuštění aktivace + python poetry run uv run
Verze Pythonu pyenv pyenv uv python
Globální nástroje pipx – uvx, uv tool

16. Přehled příkazů

Příkaz Význam
uv init [název] vytvoří nový projekt
uv add / remove přidá / odebere závislost
uv lock vytvoří nebo aktualizuje uv.lock
uv sync synchronizuje .venv s lock souborem
uv run <příkaz> spustí příkaz v prostředí projektu
uv tree strom závislostí
uv export export locku do requirements.txt
uv python install / list / pin správa verzí Pythonu
uv venv vytvoří virtuální prostředí
uv pip … rozhraní kompatibilní s pipem
uvx <nástroj> jednorázové spuštění nástroje
uv tool install / list / upgrade trvale nainstalované nástroje
uv build / publish sestavení a publikace balíčku
uv cache clean / dir práce s cache
uv self update aktualizace uv

Doporučený denní postup

uv init analyza && cd analyza
uv add numpy pandas matplotlib
uv add --dev pytest ruff
uv run main.py
uv run pytest
uvx ruff check .
git add pyproject.toml uv.lock .python-version main.py
git commit -m "Založení projektu"

Další zdroje

results matching ""

    No results matching ""