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.lockzamyká přesné verze všech závislostí napříč platformami. - Standardy: projekt se konfiguruje v
pyproject.tomlpodle PEP 621, takže zůstává přenositelný. - Automatika: prostředí
.venvse vytváří a synchronizuje samo přiuv run,uv syncauv add.
Pozor: Nástroj se vyvíjí rychle. Přesné možnosti vždy ověřte pomocí
uv --helpnebouv <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
- Oficiální dokumentace: https://docs.astral.sh/uv/
- Repozitář a seznam změn: https://github.com/astral-sh/uv