uv (Astral) thay cho pip, pip-tools, virtualenv, pyenv, pipx bằng một binary. Lệnh dưới đã kiểm tra với uv 0.11. Project dùng pyproject.toml + uv.lock, venv nằm ở .venv/.
Cài đặt, cập nhật
| Mục đích | Lệnh |
|---|---|
| Cài uv (Linux/macOS) | curl -LsSf https://astral.sh/uv/install.sh | sh |
| Cập nhật uv (bản cài bằng script) | uv self update |
| Bật shell completion (bash) | echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc |
Project
| Mục đích | Lệnh |
|---|---|
| Tạo project app (mặc định) | uv init netinv |
| Tạo project dạng package / library | uv init --package netinv / uv init --lib netlib |
| Thêm dependency | uv add "fastapi[standard]" httpx |
| Thêm dependency dev | uv add --dev pytest ruff |
| Thêm vào group tuỳ chọn | uv add --group docs mkdocs |
| Thêm extra (optional-dependencies) | uv add --optional netconf ncclient |
| Nhập từ requirements.txt cũ | uv add -r requirements.txt |
| Gỡ dependency | uv remove httpx |
| Xem cây dependency / gói có bản mới | uv tree / uv tree --outdated |
| Ai kéo gói X vào | uv tree --invert --package urllib3 |
| Xem / tăng version project | uv version / uv version --bump minor |
Lock và sync
| Mục đích | Lệnh |
|---|---|
Tạo/cập nhật uv.lock |
uv lock |
| Nâng toàn bộ / một gói trong lock | uv lock --upgrade / uv lock --upgrade-package fastapi |
Kiểm tra lock khớp pyproject.toml (CI) |
uv lock --check |
| Cài môi trường đúng theo lock | uv sync |
| CI: lỗi nếu lock cần cập nhật | uv sync --locked |
| Cài theo lock, không resolve lại | uv sync --frozen |
| Production, bỏ dev group | uv sync --no-dev |
| Kèm mọi extras / mọi group | uv sync --all-extras --all-groups |
| Xuất requirements.txt cho hệ thống cũ | uv export --format requirements.txt --no-dev -o requirements.txt |
Chạy
| Mục đích | Lệnh |
|---|---|
| Chạy lệnh trong venv project (tự sync) | uv run pytest -q |
| Chạy kèm gói tạm thời | uv run --with rich python script.py |
| Nạp biến từ file env | uv run --env-file .env python -m app |
Chạy tool một lần, không cài (uvx = uv tool run) |
uvx ruff check . |
| Chạy tool phiên bản cụ thể | uvx ruff@0.14.0 --version |
| Chạy tool mà tên lệnh khác tên gói | uvx --from ansible-core ansible-playbook --version |
Script một file (PEP 723)
| Mục đích | Lệnh |
|---|---|
| Tạo script có khối metadata | uv init --script check_bgp.py --python 3.12 |
| Thêm dependency vào script | uv add --script check_bgp.py ncclient |
| Chạy script (tự tạo env riêng) | uv run check_bgp.py |
# /// script
# requires-python = ">=3.12"
# dependencies = ["ncclient"]
# ///
from ncclient import managerThêm shebang #!/usr/bin/env -S uv run --script để chạy trực tiếp ./check_bgp.py.
Python
| Mục đích | Lệnh |
|---|---|
| Liệt kê bản có sẵn / đã cài | uv python list |
| Cài Python | uv python install 3.12 3.13 |
Ghim version cho project (.python-version) |
uv python pin 3.12 |
| Đường dẫn interpreter đang dùng | uv python find |
| Tạo project với Python cụ thể | uv init -p 3.12 netinv |
Tool cài lâu dài (thay pipx)
| Mục đích | Lệnh |
|---|---|
| Cài tool | uv tool install ruff |
| Cài kèm plugin | uv tool install ansible-core --with ncclient --with paramiko |
| Liệt kê / nâng tất cả | uv tool list / uv tool upgrade --all |
| Gỡ | uv tool uninstall ruff |
| Thêm thư mục bin của tool vào PATH | uv tool update-shell |
venv và giao diện pip
| Mục đích | Lệnh |
|---|---|
| Tạo venv | uv venv / uv venv --python 3.12 .venv |
| Tạo venv có sẵn pip (cho tool cũ cần pip) | uv venv --seed |
| Cài như pip | uv pip install -r requirements.txt |
| Compile lock kiểu pip-tools | uv pip compile requirements.in -o requirements.txt |
| Đồng bộ đúng theo file (gỡ gói thừa) | uv pip sync requirements.txt |
| Liệt kê / freeze | uv pip list / uv pip freeze |
Cache, CI
| Mục đích | Lệnh |
|---|---|
| Thư mục cache / dung lượng | uv cache dir / uv cache size |
| Dọn cache | uv cache clean |
| Dọn cache trước khi lưu ở CI | uv cache prune --ci |
Trong GitHub Actions dùng astral-sh/setup-uv với enable-cache: true, rồi uv sync --locked. Xem GitHub Actions cheatsheet.
Commit uv.lock vào Git (với app). Không commit .venv/.