UV — szybki menedżer pakietów i środowisk Pythona (samouczek)

uv to napisany w Ruście menedżer do Pythona od zespołu Astral (twórców ruff). Zastępuje w jednym narzędziu to, do czego wcześniej trzeba było kilku: pip, venv/virtualenv, pip-tools, pyenv, pipx, a w dużej mierze także poetry. Jego znakiem firmowym jest szybkość — instalacje i rozwiązywanie zależności są zwykle o rząd wielkości szybsze niż w pip, dzięki agresywnemu cache'owaniu i równoległości.

Ten artykuł to praktyczny samouczek: co zainstalować, jak zrobić środowisko dla repozytorium, jakie uv daje możliwości i o czym warto wiedzieć.

Dlaczego warto

• Jedno narzędzie zamiast pięciu — Python, wirtualne środowiska, pakiety, narzędzia CLI, lockfile.
• Szybkość — globalny, współdzielony cache i twardolinkowanie plików sprawiają, że powtórne instalacje są niemal natychmiastowe.
• Instaluje też sam interpreter Pythona — nie musisz mieć „systemowego" Pythona w danej wersji; uv pobierze standalone build (np. 3.12), nie ruszając systemu.
• Zgodność z ekosystemem — potrafi działać jak pip (interfejs uv pip), czytać requirements.txt oraz pyproject.toml.

Instalacja

Oficjalny instalator (Linux/macOS):

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

Alternatywy:

# via pipx
pipx install uv

# macOS (Homebrew)
brew install uv

Weryfikacja i aktualizacja:

uv --version
uv self update

uv instaluje się do katalogu użytkownika (np. ~/.local/bin), więc nie wymaga uprawnień administratora.

Zarządzanie wersjami Pythona

uv może pobierać i przełączać interpretery niezależnie od systemu — to jego duża przewaga.

uv python list                 # available and installed versions
uv python install 3.12         # download a standalone CPython 3.12
uv python install 3.11 3.13    # several at once
uv python pin 3.12             # write .python-version for this project

uv python pin tworzy plik .python-version, który uv honoruje przy tworzeniu środowisk — dobry sposób, by całe repo używało spójnej wersji.

Przykład z praktyki: system miał tylko Pythona 3.14, a sklonowane repo wymagało 3.12. Wystarczyło uv python install 3.12 i środowisko powstało na właściwej wersji — bez instalowania czegokolwiek „na systemie".

Dwa modele pracy

uv obsługuje dwa style, które warto rozróżnić:

1. Tryb „pip-compatible" (uv venv + uv pip …) — jesteś blisko klasycznego pip/venv, tylko szybciej. Idealny do istniejących repozytoriów i szybkiego startu.
2. Tryb projektowy (uv init/uv add/uv sync) — uv zarządza pyproject.toml i plikiem uv.lock, dając pełną, reprodukowalną obsługę projektu (odpowiednik poetry).

Poniżej oba.

Szybki start: środowisko dla sklonowanego repo (tryb pip)

Najczęstszy scenariusz — masz sklonowane repo i chcesz je uruchomić lokalnie.

cd my-repo

# 1. Create a virtualenv (defaults to .venv) on a chosen Python version.
uv venv --python 3.12

# 2. Install dependencies. Pick whichever matches the repo:
uv pip install -r requirements.txt          # classic requirements file
uv pip install -e .                          # editable install from pyproject/setup
uv pip install numpy pandas "astropy~=7.1"   # explicit packages

# 3. Run things (either activate, or call binaries directly)
source .venv/bin/activate                    # optional
uv run python -m pytest                       # runs inside the project env

Kilka przydatnych wariantów uv pip install:

# Install a wheel from a custom index (e.g. a project-specific wheel host)
uv pip install --find-links https://example.org/wheels "somepkg==1.2.3"

# Use an alternative package index
uv pip install --index-url https://my.mirror/simple/ requests

Przykład z praktyki: w projekcie z wxPython (który na Linuksie nie ma zwykłych wheeli na PyPI) zadziałało uv pip install --find-links <indeks-wheeli> "wxPython==4.2.3" razem z resztą zależności — jedną komendą, bez kompilacji ze źródeł.

Domyślnie środowisko powstaje w .venv w katalogu projektu — wygodne dla edytorów (patrz sekcja o VS Code).

Tryb projektowy: uv init, add, sync, run

Gdy zakładasz nowy projekt albo chcesz pełnej reprodukowalności:

uv init my-project        # scaffold: pyproject.toml, .python-version, README, src/
cd my-project

uv add requests           # add a dependency (updates pyproject.toml + uv.lock)
uv add --dev pytest ruff  # dev-only dependencies
uv remove requests        # remove a dependency

uv sync                   # make the env match uv.lock exactly
uv lock                   # regenerate the lockfile from pyproject.toml

uv run pytest             # run a command in the project env (auto-syncs first)
uv run python app.py

Najważniejsze pliki:

• pyproject.toml — deklarowane zależności i metadane projektu.
• uv.lock — dokładnie zamrożone wersje (do commitowania, gwarantuje identyczne środowisko u każdego).
• .python-version — przypięta wersja interpretera.

uv run jest tu kluczowe: przed uruchomieniem komendy uv w tle upewnia się, że środowisko jest zsynchronizowane z lockiem — nie musisz ręcznie aktywować venva ani pamiętać o uv sync.

Praca z istniejącymi projektami (pip / requirements / poetry)

• requirements.txt — uv pip install -r requirements.txt. Do generowania i „pinowania" użyj uv pip compile:

bash uv pip compile requirements.in -o requirements.txt # resolve and pin uv pip sync requirements.txt # make env match exactly

• pyproject.toml (PEP 621) — uv czyta go natywnie: uv sync albo uv pip install -e ..
• Projekt w Poetry — jeśli pyproject.toml używa sekcji [tool.poetry], możesz nadal skorzystać z trybu pip (uv venv + uv pip install <zależności>), a docelowo rozważyć migrację metadanych do standardu [project], który uv obsługuje w pełni.

Narzędzia globalne: uv tool i uvx (zamiennik pipx)

Do instalowania narzędzi CLI w izolacji (jak pipx):

uv tool install ruff        # install a CLI tool globally, isolated
uv tool list                # list installed tools
uv tool upgrade --all

uvx ruff check .            # run a tool ephemerally, without installing it
uvx black@25.1.0 .          # pin a specific version for a one-off run

uvx to skrót do „pobierz i uruchom w locie" — świetne do jednorazowych zadań bez zaśmiecania systemu.

Lockfile i reprodukowalność

W trybie projektowym uv.lock zapewnia, że wszyscy (i CI) dostają identyczne wersje.

uv lock                 # create/refresh the lockfile
uv sync                 # install exactly what the lock says
uv sync --frozen        # fail if the lock is out of date (good for CI)
uv sync --no-dev        # production install without dev dependencies

Zasada: commituj uv.lock dla aplikacji. Dla bibliotek zwykle nie (biblioteka nie powinna narzucać dokładnych wersji swoim użytkownikom).

Integracja z VS Code / edytorem

• Twórz środowisko jako .venv w katalogu projektu (domyślne dla uv venv) — edytory wykrywają je automatycznie.
• W VS Code wskaż interpreter: Ctrl+Shift+P → „Python: Select Interpreter" → ./.venv/bin/python.
• Taski i konfiguracje uruchomieniowe warto kierować wprost na .venv/bin/… (.venv/bin/python, .venv/bin/ruff), żeby działały niezależnie od tego, czy terminal ma aktywny venv.
• Jeśli auto-aktywacja w terminalu bywa zawodna, można wymusić ją własnym profilem terminala (bash --init-file), który sam sourceuje .venv/bin/activate.

Ściąga najważniejszych komend

Pułapki i dobre praktyki

• uv pip install to nie pip „na systemie" — instaluje do aktywnego (lub wskazanego) środowiska, nie globalnie. To dobrze, ale bywa mylące dla osób przyzwyczajonych do pip install bez venva.
• Wskazuj środowisko jawnie, gdy nie masz aktywnego venva: uv pip install --python .venv/bin/python ….
• Commituj uv.lock (aplikacje) i .python-version — to fundament reprodukowalności.
• Cache jest globalny — powtórne instalacje są szybkie; gdy brakuje miejsca, uv cache clean.
• Twardolinkowanie działa najlepiej, gdy cache i projekt są na tym samym systemie plików; w innym wypadku uv ostrzega i kopiuje (można wymusić --link-mode=copy).
• Nie mieszaj bez potrzeby uv pip (tryb pip) z uv add/uv sync (tryb projektowy) w jednym projekcie — wybierz jeden model pracy.

Podsumowanie

uv upraszcza pracę z Pythonem do kilku szybkich komend: sam pobiera interpreter, tworzy środowisko, instaluje zależności i uruchamia kod, a w trybie projektowym daje reprodukowalny uv.lock. Na start wystarczy uv venv + uv pip install; gdy potrzebujesz pełnej kontroli i powtarzalności — przejdź na uv init/uv add/uv sync/uv run. W praktyce zastępuje pip, venv, pyenv i pipx, a często również poetry — przy zauważalnie krótszym czasie oczekiwania.

Referencje

• uv — dokumentacja (Astral)
• uv — repozytorium na GitHubie
• uv — instalacja
• uv — praca z projektami
• uv — interfejs uv pip
• uv — zarządzanie wersjami Pythona
• uv — narzędzia (uv tool/uvx)