Data: 30.07.2026

Python uv – co to jest i jak zastępuje pip, poetry i pyenv?

Spis treści

• Python uv – co to jest i jak zastępuje pip, poetry i pyenv?
  • Czym jest uv?
  • W jakich obszarach używać uv?
  • Czym jest środowisko wirtualne?
  • Jakie problemy uv rozwiązuje?
  • Instalacja uv
    • macOS oraz Linux
    • Windows
    • Weryfikacja instalacji
    • Aktualizacja uv
  • Tworzenie nowego projektu i środowiska w Pythonie
    • Plik pyproject.toml
    • Wersja Pythona i Git
    • Instalacja Pythona
    • Katalog .venv
  • Aplikacja w Pythonie
  • Dodanie biblioteki
  • Dodatkowe operacje w uv
    • uv remove
    • uv tree
    • uv sync
    • uv sync --upgrade
    • uv cache
    • uv init
    • uv run
    • uv lock
    • uv publish
  • Przypadek użycia - kompatybilność z narzędziem pip
  • Podsumowanie

Czym jest uv?

uv to nowoczesne narzędzie do zarządzania pakietami i projektami w Pythonie, które zyskuje coraz większą popularność dzięki swojej szybkości i wszechstronności.

Zostało zaprojektowane jako kompleksowy zamiennik wielu rozproszonych dotąd narzędzi w ekosystemie Pythona — takich jak pip, pip-tools, virtualenv, poetry, pipx czy pyenv.

Zamiast używać kilku programów: jednego do instalacji pakietów, drugiego do zarządzania wersjami Pythona, trzeciego do środowisk wirtualnych, możemy użyć uv, który łączy różne funkcje w jednym, spójnym i szybko działającym interfejsie CLI (Command Line Interface — po polsku: interfejs wiersza poleceń lub interfejs linii komend).

W jakich obszarach używać uv?

Główne obszary zastosowania uv obejmują:

• Zarządzanie pakietami (kompatybilność z pip): pozwala na błyskawiczną instalację, aktualizację i usuwanie bibliotek, służąc jako bezpośredni, znacznie szybszy zamiennik dla tradycyjnego polecenia pip.
• Zarządzanie środowiskami wirtualnymi: błyskawicznie tworzy i aktywuje izolowane środowiska (.venv) dla projektów.
• Zarządzanie wersjami Pythona: potrafi pobierać, instalować i przełączać różne wersje interpretera Python, bez konieczności niezależnej instalacji Pythona w systemie.
• Obsługę projektów i zależności: oferuje zaawansowane zarządzanie projektem (odpowiednik Poetry czy Hatch), automatycznie tworząc pliki blokujące wersje (uv.lock) i synchronizując zależności za pomocą poleceń takich jak uv init, uv add czy uv sync.
• Uruchamianie narzędzi CLI (uvx / uv tool): pozwala na natychmiastowe uruchamianie narzędzi napisanych w Pythonie (np. ruff, black, cowsay) w izolowanym środowisku wirtualnym, z zachowaniem czystości globalnej instalacji Pythona – odpowiednik pipx.

Czym jest środowisko wirtualne?

Środowisko wirtualne (ang. virtual environment) to izolowany, odrębny od reszty systemu zestaw interpretera Pythona wraz z zainstalowanymi bibliotekami, przypisany do jednego konkretnego projektu.

Bez niego wszystkie instalowane biblioteki trafiałyby do jednej, globalnej instalacji Pythona w systemie, co rodzi problemy, gdy różne projekty wymagają różnych, niekompatybilnych ze sobą wersji tej samej biblioteki.

uv tworzy środowisko wirtualne automatycznie, w postaci katalogu .venv wewnątrz projektu, bez konieczności ręcznego zakładania i aktywowania środowiska, jak to było robione w starszych narzędziach (python -m venv, source venv/bin/activate).

Jakie problemy uv rozwiązuje?

uv powstał, aby rozwiązać dwa konkretne problemy, z którymi na co dzień mierzy się wielu programistów Pythona:

• Skomplikowana instalacja i zarządzanie wersjami interpretera Python - zainstalowanie czystego Pythona w konkretnej wersji bywało uciążliwe. Wymagało dodatkowych narzędzi lub ręcznej konfiguracji, zwłaszcza na niektórych systemach operacyjnych. uv potrafi samoczynnie pobrać i zainstalować żądaną wersję interpretera w kilka sekund, bez ingerencji w system.

• Problemy z determinizmem i powtarzalnością środowisk - dzięki szybkiemu mechanizmowi tworzenia plików blokujących (uv.lock), uv gwarantuje, że projekt będzie działał dokładnie tak samo na komputerze dewelopera, jak i na serwerze produkcyjnym.

Efekt jest taki, że zamiast łączyć kilka narzędzi i pilnować ich wzajemnej zgodności, deweloper otrzymuje jedno spójne rozwiązanie, które prowadzi go od pierwszej instalacji Pythona aż po powtarzalne wdrożenia na produkcję.

Instalacja uv

macOS oraz Linux

Instalacja uv w systemie macOS i Linux sprowadza się do wpisania i wykonania jednej komendy w terminalu.

Otwórz konsolę i wykonaj:

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

Powyższy skrypt pobiera i instaluje najnowszą wersję uv bezpośrednio z oficjalnego repozytorium, bez potrzeby wcześniejszej instalacji Pythona.

W systemie macOS możesz alternatywnie skorzystać z menedżera pakietów Homebrew:

brew install uv

Obydwa sposoby instalacji są bezpieczne. Wybór zależy głównie od tego, czy masz już skonfigurowany w systemie menedżer pakietów Homebrew.

Windows

Aby zainstalować uv w systemie Windows, z menu Start wybierz konsolę Windows PowerShell, otwórz ją i wykonaj w niej skrypt:

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

Weryfikacja instalacji

Po zakończeniu instalacji, niezależnie od systemu operacyjnego, warto sprawdzić, czy uv został poprawnie dodany do ścieżki systemowej.

Przed rozpoczęciem weryfikacji zamknij konsolę Windows PowerShell i ponownie ją otwórz. Następnie wykonaj poniższe polecenie:

uv --version
# uv 0.12.0 (b88d7c5c4 2026-07-28 x86_64-pc-windows-msvc)

Aktualizacja uv

uv rozwija się bardzo szybko, dlatego warto od czasu do czasu sprawdzać, czy pojawiła się nowsza wersja. Aktualizację możesz zrobić poniższym poleceniem:

uv self update

Polecenie uv self update sprawdza dostępność nowszej wersji i, jeśli taka istnieje, instaluje ją bez konieczności ponownego pobierania całego instalatora.

Jednym z głównych obszarów, w których uv sprawdza się najlepiej, jest zarządzanie projektami. Obejmuje ono np.

• utworzenie struktury katalogów
• dodawanie zależności, czyli zewnętrznych bibliotek i pakietów
• zapisywanie dokładnych wersji zależności, dzięki czemu mogą zostać odtworzone tak samo na każdym komputerze.

W kolejnych krokach pokażemy, jak założyć nowy projekt w Pythonie z użyciem uv.

Tworzenie nowego projektu i środowiska w Pythonie

Projekt to katalog z kodem. Ma on ma jasno określoną strukturę i konfigurację. Dzięki temu:

• wiadomo, jakich bibliotek (zależności) potrzebuje kod, aby działać
• wiadomo, jakiej wersji Pythona wymaga
• można go łatwo uruchomić, przetestować, spakować i udostępnić innym — bez wyjaśniania, co trzeba kolejno instalować.

Te wszystkie informacje zapisane są w jednym pliku — pyproject.toml. To on formalnie czyni katalog "projektem", a nie tylko zbiorem luźnych skryptów .py.

Dzięki temu można pobrać projekt z Gita i jedną komendą (uv sync) odtworzyć dokładnie takie samo środowisko — z tą samą wersją Pythona i tymi samymi bibliotekami.

W skrócie: projekt = kod + plik konfiguracyjny opisujący, jak ten kod uruchomić.

Projekty w Pythonie przechowujemy w osobnym katalogu. Aby założyć nowy projekt, wykonaj w konsoli poniższe polecenia:

mkdir moj_projekt
cd moj_projekt
uv init

Polecenia:

• mkdir moj_projekt — tworzy nowy, pusty katalog o nazwie moj_projekt
• cd moj_projekt — przechodzi do wnętrza tego katalogu — od tego momentu wszystkie kolejne polecenia w konsoli będą wykonywane właśnie w nim.
• uv init inicjalizuje nowy projekt Pythona w bieżącym katalogu — tworzy podstawową strukturę plików i katalogów, dzięki czemu nie musimy robić tego ręcznie.

Narzędzie uv tworzy cztery pliki i dwa katalogi:

.
├── .git/               <-- ukryty katalog repozytorium Git (tworzony automatycznie)
├── .gitignore          <-- ukryty plik ignorowanych elementów dla Git
├── .python-version     <-- ukryty plik z przypisaną wersją Pythona
├── README.md           <-- opis projektu
├── pyproject.toml      <-- główny plik konfiguracyjny (zależności, metadane)
└── src/                <-- katalog źródłowy projektu (układ src-layout)
    └── moj_projekt/
        └── __init__.py <-- plik inicjalizujący pakiet / punkt wejścia

Polecenie uv init domyślnie tworzy moduł (bibliotekę) z przykładowym kodem w katalogu src/.

Jeśli zamiast tego chcesz utworzyć zwykłą aplikację (bez struktury pakietu), użyj flagi:

uv init --no-package moj_projekt

Pliki README.md oraz __init__.py są jedynie przykładowe — można je usunąć lub nadpisać własną treścią.

Plik pyproject.toml

Najważniejszym plikiem projektu jest pyproject.toml. To w nim znajdują się kluczowe informacje:

• lista wymaganych bibliotek (dependencies)
• minimalna wersja Pythona (requires-python)
• dane projektu i autora
• konfiguracja systemu budowania (build-system)

[project]
name = "moj-projekt"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
    { name = "Rafał", email = "rafał@example.com" }
]
requires-python = ">=3.13"
dependencies = []

[project.scripts]
moj-projekt = "moj_projekt:main"

[build-system]
requires = ["uv_build>=0.12.0,<0.13.0"]
build-backend = "uv_build"

Nazwa w name (moj-projekt) i nazwa katalogu w src/ (moj_projekt) to dwie różne rzeczy:

• name w pliku pyproject.toml to nazwa pakietu do instalacji (pip install moj-projekt). Zgodnie ze standardem Pythona podkreślenia zamieniane są tutaj na myślniki
• katalog w src/ — nazwa modułu do importu (import moj_projekt). Tutaj musi zostać podkreślenie, gdyż myślnik jest niedozwolony w nazwach Pythona.

uv robi tę zamianę automatycznie.

Wersja Pythona i Git

Plik .python-version zawiera jedną linię z konkretną wersją Pythona np. 3.13. Działa jak swojego rodzaju lockfile — dzięki niemu projekt zawsze korzysta z tej samej, ustalonej wersji.

uv init zakłada też puste repozytorium Git — powstają katalog .git oraz plik .gitignore. Repozytorium nie powstaje, jeśli już istnieje .git w którymś z wyższych katalogów.

Wszystkie wygenerowane pliki, oprócz katalogu .venv, powinny trafić do repozytorium.

Katalog .venv pojawia się dopiero w kolejnym kroku, gdy uruchomisz coś, co faktycznie tworzy środowisko wirtualne i instaluje do niego zależności, czyli np. uv sync.

Plik .gitignore, utworzony automatycznie przez uv init, zawiera już domyślnie wpis ignorujący .venv/. Dzięki temu, gdy w kolejnym kroku pojawi się katalog środowiska wirtualnego, Git automatycznie pominie go przy commitowaniu — nie trzeba nic dodawać ręcznie.

Instalacja Pythona

Jeśli potrzebujemy konkretnej wersji Pythona, instalujemy ją poleceniem:

uv python install 3.14
# Installed Python 3.14.6 in 13.43s
#  + cpython-3.14.6-windows-x86_64-none (python3.14.exe)

uv sam zarządza wersjami Pythona — nie musimy nic instalować globalnie w systemie.

Aby sprawdzić, czy interpreter działa, możemy go uruchomić bezpośrednio z poziomu projektu:

uv run python
# Python 3.14.6 (main, Jul 23 2026, 14:44:54) [MSC v.1944 64 bit (AMD64)] on win32
# Type "help", "copyright", "credits" or "license" for more information.

Katalog .venv

Po uruchomieniu polecenia uv run python, w projekcie pojawia się ukryty katalog .venv/. Jest to lokalne środowisko wirtualne, w którym znajduje się interpreter Pythona oraz zainstalowane pakiety:

.
├── .python-version
├── .venv
│   ├── .gitignore
│   ├── .lock
│   ├── CACHEDIR.TAG
│   ├── bin
│   │   ├── activate
│   │   ├── activate.bat
│   │   ├── activate.csh
│   │   ├── activate.fish
│   │   ├── activate.nu
│   │   ├── activate.ps1
│   │   ├── activate_this.py
│   │   ├── deactivate.bat
│   │   ├── pydoc.bat
│   │   ├── python -> /home/rafal/.local/share/uv/python/cpython-3.14-linux-x86_64-gnu/bin/python3.14
│   │   ├── python3 -> python
│   │   └── python3.14 -> python
│   ├── lib
│   │   └── python3.14
│   │       └── site-packages
│   │           ├── __pycache__
│   │           │   └── _virtualenv.cpython-314.pyc
│   │           ├── _virtualenv.pth
│   │           └── _virtualenv.py
│   ├── lib64 -> lib
│   └── pyvenv.cfg
├── pyproject.toml
└── uv.lock

Katalog .venv nie trafia do repozytorium GIT — jest generowany lokalnie i można go odtworzyć poleceniem uv sync.

Zawartość pliku .python-version można sprawdzić poleceniem:

cat .python-version # Linuks i macOS
cd moj_projekt # Windows - wejście do katalogu projektu
Get-Content .python-version # Windows - sprawdzenie wersji Pythona

Aplikacja w Pythonie

Aplikacja to program, który wykonuje określone zadanie np. wyświetla stronę internetową, przelicza dane w arkuszu kalkulacyjnym albo wypisuje komunikat na ekranie. W praktyce aplikacja to zestaw instrukcji (kodu), które komputer wykonuje po kolei, aby zrobić to, co zaplanował programista.

W naszym przykładzie napiszemy bardzo prostą aplikację konsolową — czyli taką, która nie ma okienek ani przycisków, tylko wyświetla tekst w terminalu. Jej zadaniem będzie wypisanie powitania oraz informacji o wersji Pythona.

Gdy projekt jest gotowy, możemy napisać w nim własną aplikację. Aby to zrobić otwieramy plik src/moj_projekt/__init__.py i zastępujemy jego zawartość poniższym kodem:

import sys

def main():
    print("Hello from moj_projekt!")
    print(sys.version)

if __name__ == "__main__":
    main()

Wyjaśnienie kodu:

• import sys — wczytujemy wbudowany moduł sys, dzięki któremu mamy dostęp m.in. do informacji o wersji Pythona.
• def main(): — definiujemy funkcję main(), czyli główny punkt startowy naszej aplikacji. To właśnie ją uruchamia uv po wpisaniu polecenia uv run moj_projekt
• print("Hello from moj_projekt!") — wypisuje na ekranie komunikat powitalny.
• print(sys.version) — wypisuje wersję Pythona, w której aktualnie działa nasz program.
• if __name__ == "__main__": main() — to popularny w Pythonie "strażnik", który sprawia, że funkcja main() uruchamia się tylko wtedy, gdy plik jest wykonywany bezpośrednio, a nie importowany jako moduł w innym pliku.

Aby uruchomić naszą aplikację, wpisujemy w konsoli Windows PowerShell:

cd moj_projekt # wchodzimy do katalogu projektu
uv run moj-projekt # uruchamiamy kod
# Hello from moj_projekt!
# 3.13.2 (tags/v3.13.2:4f8bb39, Feb  4 2025, 15:23:48) [MSC v.1942 64 bit (AMD64)]

uv automatycznie wykrywa środowisko wirtualne (.venv), aktywuje je i uruchamia nasz kod — nie musimy nic robić ręcznie.

W powyższym kodzie zdefiniowaliśmy funkcję main(). Jeśli nie wiesz jeszcze, czym są funkcje w Pythonie i jak je tworzyć, sprawdź artykuł Jak tworzyć własne funkcje w Pythonie.

Dodanie biblioteki

Biblioteka to gotowy zestaw kodu, który możemy wykorzystać w projekcie. Wystarczy ją zainstalować oraz zaimportować w kodzie, aby zacząć z niej korzystać.

Dzięki bibliotekom nie musimy np. samodzielnie pisać kodu do wczytywania i przetwarzania danych tabelarycznych — możemy skorzystać z gotowej, przetestowanej przez tysiące programistów biblioteki pandas.

Dodanie biblioteki do projektu jest potrzebne, aby móc jej używać w kodzie. Przykładowo biblioteke pandas do obsługi tabel dodajemy poniższym poleceniem:

uv add pandas

Podczas wykonywania tego polecenia uv:

• sprawdza dostępne wersje biblioteki pandas oraz jej zależności (np. numpy, python-dateutil) i wybiera wersje zgodne z wymaganą wersją Pythona oraz innymi bibliotekami już obecnymi w projekcie
• pobiera wybrane paczki z repozytorium PyPI
• instaluje pobrane paczki do katalogu .venv/ — czyli lokalnego środowiska projektu.
• aktualizuje pliki pyproject.toml (dodaje wpis w sekcji dependencies) oraz uv.lock (zapisuje dokładne, użyte wersje wszystkich zainstalowanych paczek).

Cały proces jest automatyczny — nie musimy ręcznie aktywować środowiska ani nic doinstalowywać.

Zawartość pliku pyproject.toml po dodaniu biblioteki pandas:

[project]
name = "moj-projekt"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
    { name = "Rafał", email = "rafał@example.com" }
]
requires-python = ">=3.13"
dependencies = [
    "pandas>=3.0.5",
]

[project.scripts]
moj-projekt = "moj_projekt:main"

[build-system]
requires = ["uv_build>=0.12.0,<0.13.0"]
build-backend = "uv_build"

Zwróć uwagę, że w dependencies zapisana jest wersja pandas>=3.0.5 — czyli dowolna wersja od 3.0.5 wzwyż. Jest to wygodny zapis, ale niejednoznaczny: za jakiś czas uv add pandas mógłby zainstalować już nowszą wersję.

Żeby mieć pewność, że projekt zawsze korzysta z dokładnie tych samych wersji bibliotek — niezależnie od tego, kto i kiedy go uruchomi — uv zapisuje pełne, konkretne wersje w osobnym pliku: uv.lock.

Katalog .venv/ nie jest przenoszony razem z projektem np. na serwer. Jest zbyt duży, a poza tym zawiera pliki dopasowane do konkretnego systemu operacyjnego. Zamiast go kopiować, na nowym komputerze odtwarzamy go od nowa na podstawie pliku uv.lock.

Za pomocą poniższego polecenia możemy odbudować katalog .venv/ na bazie plików uv.lock oraz .python-version:

uv sync

W praktyce nie trzeba jednak pamiętać o ręcznym wywoływaniu uv sync. Jeśli program uruchamiamy poleceniem uv run np. uv run moj-projekt, a katalog .venv nie istnieje lub jest nieaktualny, uv sam odtworzy go automatycznie przed uruchomieniem kodu.

Dodatkowe operacje w uv

Poza dodawaniem bibliotek, uv udostępnia zestaw poleceń przydatnych na co dzień przy pracy z projektem np.

• usuwanie zależności
• podgląd tego, co jest zainstalowane
• odbudowę środowiska
• publikację pakietu.

Poniżej krótki przegląd najważniejszych poleceń.

uv remove

Polecenie uv remove usuwa bibliotekę z zależności projektu - aktualizuje zarówno pyproject.toml, jak i uv.lock. W przykładzie usunięta zostanie biblioteka pandas.

uv remove pandas # usuwa zależność

uv tree

Polecenie uv tree wyświetla listę wszystkich zainstalowanych bibliotek w postaci drzewa — łącznie z zależnościami samych bibliotek. Dzięki temu widać nie tylko to, co dodaliśmy sami, ale też co zostało doinstalowane "przy okazji".

W poleceniach poniżej:

• uv add flask — dodaje do projektu bibliotekę flask razem z jej zależnościami np. jinja2, werkzeug i zapisuje ją w pyproject.toml oraz w uv.lock
• uv add requests — analogicznie dodaje bibliotekę requests wraz z jej własnymi zależnościami np. urllib3, certifi
• uv tree — nie instaluje niczego nowego, tylko wyświetla wszystkie zainstalowane biblioteki w postaci drzewa, aby zobaczyć zarówno to, co dodaliśmy sami (flask, requests), jak i to, co zostało doinstalowane "przy okazji" jako ich zależności.

uv add flask
uv add requests
uv tree

Wynik działania:

moj_projekt v0.1.0
├── flask v3.1.0
│   ├── blinker v1.9.0
│   ├── click v8.1.8
│   ├── itsdangerous v2.2.0
│   ├── jinja2 v3.1.6
│   │   └── markupsafe v3.0.2
│   └── werkzeug v3.1.3
│       └── markupsafe v3.0.2
└── requests v2.32.3
    ├── certifi v2025.4.26
    ├── charset-normalizer v3.4.2
    ├── idna v3.10
    └── urllib3 v2.4.0

uv sync

Polecenie uv sync służy do odbudowania katalogu .venv/, który zawiera interpreter Pythona i biblioteki projektu. Polecenia można użyć po skasowaniu katalogu wirtualnego środowiska .venv/.

uv sync

uv sync --upgrade

Polecenie uv sync --upgrade ponownie ocenia zależności (z pominięciem tych z przypiętą wersją) i regeneruje plik blokujący uv.lock.

Aktualizuje tylko uv.lock:

uv sync --upgrade

Warto pamiętać, że plik pyproject.toml pozostaje niezmieniony — nadal będzie tam widniał zapis w stylu pandas>=3.0.5, mimo że faktycznie zainstalowana zostanie nowsza wersja.

Jeśli chcemy, aby minimalne wersje w pyproject.toml również zostały podniesione do wersji zapisanych w uv.lock, można skorzystać z zewnętrznego (niezwiązanego bezpośrednio z uv) narzędzia uv-bump:

uvx uv-bump

uvx uruchamia narzędzie jednorazowo, w tymczasowym, izolowanym środowisku, bez dodawania go do projektu. Nic nie zapisuje się w pyproject.toml.

uv-bump to nie biblioteka, z której korzystamy w kodzie, tylko samodzielne narzędzie wiersza poleceń (podobnie jak np. black czy ruff). Uruchamiamy je raz, aby zaktualizowało plik pyproject.toml, a potem nie jest już nam potrzebne. Dlatego naturalnym wyborem jest uvx uv-bump, a nie uv add uv-bump.

uv add uv-bump dodałoby narzędzie uv-bump jako stałą zależność projektu — wpis pojawiłby się w pyproject.toml (w sekcji dependencies) i w uv.lock, a samo narzędzie zostałoby zainstalowane na stałe w katalogu .venv.

uv cache

Program uv przechowuje pobrane wcześniej paczki w globalnym cache (np. /home/rafal/.cache/uv). Dzięki temu kolejne instalacje tych samych bibliotek są dużo szybsze. Z czasem cache może jednak zająć sporo miejsca na dysku — można je wtedy wyczyścić lub przenieść.

Polecenie uv cache clean czyści globalny cache (np. /home/rafal/.cache/uv), aby zminimalizować zużycie dysku.

# czyści cache
uv cache clean

# wyświetla lokalizację folderu z cache
uv cache dir

# ustawienia nowej lokalizacji w ~/.config/uv/uv.toml (macOS i Linuks), %APPDATA%\uv\uv.toml (Windows):
cache-dir = "/path/to/your/new/cache"

uv init

Polecenie uv init tworzy nowy katalog z zalążkiem nowego projektu. Może to być projekt dla nowego modułu albo nowej aplikacji.

# tworzy szkielet nowego modułu z plikiem src/__init__.py
uv init

# tworzy szkielet nowej aplikacji z plikiem main.py
uv init --no-package moj_projekt_app

Wariant --no-package generuje prostszą strukturę — bez katalogu src/, za to z pojedynczym plikiem main.py:

uv init --no-package tworzy pliki:

• main.py
• pyproject.toml
• README.md

Zawartość pliku pyproject.toml, ale w wersji "startowej" — powstałej po wykonaniu uv init --no-package moj_projekt_app, czyli po utworzeniu projektu aplikacji (bez struktury src/).

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

Plik .python-version z aktualnie używaną wersją Pythona zostanie utworzony automatycznie. Jeśli chcemy wygenerować go ponownie np. po zmianie wersji Pythona, możemy użyć polecenia:

uv python pin

uv run

Polecenie uv run uruchamia projekt, a jeśli to konieczne — wcześniej odbudowuje dla niego środowisko wirtualne.

cd moj_projekt
uv run moj-projekt # projekt utworzony w uv init
cd moj_projekt_app
uv run main.py     # projekt utworzony w uv init --no-package

uv lock

Polecenie uv lock tworzy lub aktualizuje plik uv.lock, blokując tym samym aktualnie używane wersje bibliotek. Dzięki temu, nawet gdy w przyszłości pojawi się nowsza wersja jakiejś biblioteki, projekt nadal będzie korzystał z wersji zapisanej w pliku lock — dopóki świadomie jej nie zaktualizujemy.

uv lock             # aktualizuje plik lock zgodnie z pyproject.toml
uv lock --upgrade   # aktualizuje wszystkie biblioteki do najnowszych możliwych

uv publish

Polecenie uv publish służy do skompilowania i opublikowania modułu np. na PyPI, aby inni mogli go zainstalować przez pip install lub uv add.

uv publish           # wysyła paczkę na PyPI

W ramach tego artykułu skupiamy się na pracy lokalnej z projektem. Dlatego nie podajemy przykładu, w jaki sposób opublikować paczkę.

Przypadek użycia - kompatybilność z narzędziem pip

Aby ułatwić konwersję ze starego sposobu definiowania środowiska (narzędzie pip) na nowy (narzędzie uv), powstała opcja uv pip.

Narzędzie pip, podobnie jak uv, tworzy katalog .venv/, w którym zapisywane są zainstalowane moduły aktualnego środowiska wirtualnego — pod tym względem obydwa narzędzia działają tak samo.

Różnica polega natomiast na pliku, w którym przechowywana jest lista używanych modułów: pip korzysta z requirements.txt, a uv — z pyproject.toml.

Aby zbudować środowisko (katalog .venv) na podstawie pliku requirements.txt, należy wykonać polecenie:

uv pip install -r requirements.txt

Najczęściej używane polecenia uv pip:

• uv pip install -r requirements.txt — instaluje do .venv/ moduły z listy w pliku requirements.txt
• uv pip list — wyświetla listę zainstalowanych modułów w formacie narzędzia pip (z katalogu .venv/)
• uv pip install pandas — dodaje nowy moduł do środowiska projektu do .venv/, nie do requirements.txt
• uv add -r requirements.txt — dodaje nowe moduły do projektu z listy w pliku requirements.txt i zapisuje w pliku pyproject.toml.

Poniżej dwa przykłady uruchamiania programów w lokalnym środowisku wirtualnym .venv. Dzięki poleceniu uv run nie trzeba wcześniej ręcznie aktywować środowiska np. poleceniem source .venv/bin/activate, tak jak przy pracy z pip — uv robi to automatycznie za nas.

uv run main.py
uv run flask --app app --debug run --host=0.0.0.0 --port=6060

Pierwszy przykład uruchamia zwykły skrypt main.py. Drugi przykład uruchamia serwer aplikacji webowej napisanej we flask — z włączonym trybem debugowania (--debug), nasłuchującej na wszystkich adresach sieciowych (--host=0.0.0.0) i na porcie 6060 (--port=6060).

Podsumowanie

Program uv to obecnie jedno z najszybszych i najwygodniejszych narzędzi do pracy z Pythonem. Łączy on w sobie funkcje pip, virtualenv, pyenv, poetry i pipx w jednym spójnym interfejsie CLI.

Dzięki plikom pyproject.toml, uv.lock i .python-version projekt można łatwo odtworzyć na innym komputerze lub serwerze CI/CD, a polecenia takie jak uv init, uv add, uv sync i uv run pozwalają zarządzać całym cyklem życia projektu Python bez konieczności korzystania z kilku osobnych narzędzi.

Sprawne zarządzanie projektem to tylko jeden z elementów pracy z Pythonem. Jeśli chcesz pogłębić wiedzę o samym języku — programowaniu obiektowym, testowaniu, pracy z bazami danych, czy dobrymi praktykami budowy większych aplikacji — sprawdź nasz kurs Python na poziomie zaawansowanym.

Rafał Lelusz
Programista Python, C#

Udostępnij wpis: