4.5 KiB
Przewodnik po uv
Czym jest uv?
uv to niezwykle szybki menedżer pakietów i środowisk Pythona, napisany w Rust przez Astral (twórców Ruff). Jest on 10-100x szybszy od pip i pip-tools.
Instalacja uv
Linux/macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh
Przez pip:
pip install uv
Sprawdź instalację:
uv --version
⚠️ Ważne: Flaga --no-project w projekcie Izochrona
W tym projekcie używamy uv run --no-project zamiast uv run:
# Zamiast: uv run app.py
uv run --no-project app.py
Dlaczego?
- Projekt Izochrona nie jest pakietem Pythona przeznaczonym do instalacji
--no-projectmówi uv aby nie próbował instalować projektu jako editable package- Tylko uruchamiamy skrypty, korzystając ze środowiska wirtualnego i zainstalowanych zależności
Bez --no-project: uv próbuje zbudować i zainstalować cały projekt używając pyproject.toml, co może powodować błędy.
Podstawowe komendy
Tworzenie środowiska wirtualnego:
cd backend
uv venv
Instalacja zależności:
# Z requirements.txt
uv pip install -r requirements.txt
# Z pyproject.toml (w katalogu głównym projektu)
uv sync
# Pojedynczy pakiet
uv pip install flask
Uruchamianie skryptów:
# uv automatycznie używa środowiska wirtualnego
uv run --no-project app.py
uv run --no-project download_gtfs.py
# Lub z katalogu głównego
uv run --no-project backend/app.py
Aktualizacja pakietów:
uv pip install --upgrade flask
uv pip install --upgrade -r requirements.txt
Lista zainstalowanych pakietów:
uv pip list
uv pip freeze
Dlaczego uv?
Szybkość:
- Instalacja pakietów: 10-100x szybsza niż pip
- Rozwiązywanie zależności: bardzo szybkie
- Cache: globalny cache pakietów (oszczędność miejsca)
Wygoda:
- Automatyczna aktywacja venv:
uv runautomatycznie używa środowiska - Brak
source venv/bin/activate: nie musisz ręcznie aktywować środowiska - Kompatybilność z pip: używa tych samych formatów (requirements.txt, pyproject.toml)
Przykład - porównanie:
Tradycyjnie (pip):
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt # ~30-60s
python app.py
Z uv:
uv venv
uv pip install -r requirements.txt # ~2-5s
uv run --no-project app.py
Użycie w projekcie Izochrona
Pierwsze uruchomienie:
./setup.sh # Używa uv
Codzienne użycie:
# Uruchomienie serwera
./run.sh # lub: uv run --no-project backend/app.py
# Pobranie danych
uv run --no-project backend/download_gtfs.py
# Przykłady API
uv run --no-project examples/api_examples.py
Dodawanie nowych pakietów:
Opcja A - requirements.txt:
cd backend
echo "matplotlib>=3.8.0" >> requirements.txt
uv pip install -r requirements.txt
Opcja B - pyproject.toml (zalecane):
# Edytuj pyproject.toml, dodaj do dependencies:
# "matplotlib>=3.8.0",
# Następnie:
uv sync
Porady
1. Nie musisz aktywować środowiska:
# Zamiast:
source venv/bin/activate
python app.py
# Użyj:
uv run --no-project app.py
2. Global cache:
uv przechowuje pakiety globalnie, więc instalacja w nowych projektach jest ultra-szybka.
3. Lock file (opcjonalnie):
uv pip compile requirements.txt -o requirements.lock
uv pip sync requirements.lock # Deterministyczna instalacja
4. Różne wersje Pythona:
# uv może zarządzać wersjami Pythona
uv python install 3.11
uv venv --python 3.11
Migracja z pip do uv
Jeśli masz istniejący projekt z pip:
# 1. Usuń stare venv (opcjonalnie)
rm -rf venv/
# 2. Stwórz nowe z uv
uv venv
# 3. Zainstaluj zależności
uv pip install -r requirements.txt
# 4. Gotowe! Używaj uv run zamiast python
uv run --no-project app.py
Zasoby
- Dokumentacja: https://docs.astral.sh/uv/
- GitHub: https://github.com/astral-sh/uv
- Blog: https://astral.sh/blog
FAQ
Q: Czy uv jest kompatybilne z pip? A: Tak! uv używa tych samych formatów (requirements.txt, pyproject.toml, wheel).
Q: Czy mogę używać uv i pip jednocześnie? A: Technicznie tak, ale nie jest to zalecane. Wybierz jedno.
Q: Co jeśli pakiet nie działa z uv? A: Bardzo rzadki przypadek. Zawsze możesz wrócić do pip w konkretnym środowisku.
Q: Czy uv obsługuje editable installs?
A: Tak! uv pip install -e .
Q: Gdzie jest cache pakietów?
A: ~/.cache/uv/ (Linux/macOS) lub %LOCALAPPDATA%\uv\cache (Windows)