Hướng dẫn sử dụng uv quản lý Package và môi trường ảo Python: Bộ công cụ All-in-one siêu tốc - ITFROMZERO - Share tobe shared! Sau 6 tháng đưa uv vào thực tế, thời gian build CI/CD và cài đặt thư viện Python giảm từ vài phút xuống còn vài giây. Hướng dẫn chi tiết cách dùng uv thay thế trọn bộ pip, poetry và pyenv.

Table of Contents

Bối cảnh: Cơn đau đầu mang tên môi trường Python

Cảnh chờ pip tải gói và giải quyết xung đột (dependency resolution) có lẽ là trải nghiệm quen thuộc đến ngán ngẩm với dân Python. Mọi chuyện còn tệ hơn khi hệ sinh thái bị phân mảnh quá nhiều: đổi phiên bản Python thì bật pyenv, tạo môi trường ảo phải gọi venv, quản lý gói dùng poetry hoặc pip, còn muốn chốt version chuẩn xác cho production lại cần pip-tools.

Quá nhiều mắt xích rời rạc. Hậu quả là setup cồng kềnh, chậm chạp và liên tục phát sinh lỗi lệch môi trường giữa máy dev với server. Trong một dự án FastAPI với hơn 70 dependencies mà team mình từng làm, mỗi lần onboard nhân sự mới hay build lại Docker mất gần nửa tiếng chỉ để chờ pip resolve thư viện và compile C-extension.

Astral — nhóm đứng sau linter siêu tốc Ruff — đã giải quyết dứt điểm bài toán này bằng uv. Viết hoàn toàn bằng Rust, uv gom toàn bộ vai trò của pyenv, pip, poetry, pipx và virtualenv vào một binary duy nhất. Tốc độ là điểm vượt trội nhất: uv chạy nhanh hơn pip từ 10 đến 100 lần nhờ tối ưu đa luồng và cơ chế global cache thông minh.

Cài đặt uv cực nhanh

Điểm cộng lớn: máy bạn thậm chí chưa cần cài sẵn Python. File binary độc lập của uv sẽ tự tải và thiết lập mọi thứ.

Trên Linux hoặc macOS, bạn chỉ cần một lệnh cURL duy nhất:

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

Với Windows, mở PowerShell và chạy script:

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

Cài xong, reload lại shell (như source ~/.bashrc hoặc source ~/.zshrc). Kiểm tra thành quả:

uv --version

Terminal trả về phiên bản (chẳng hạn uv 0.6.x) là bạn đã sẵn sàng thay đổi hoàn toàn workflow cũ.

Workflow chuẩn hóa từ khởi tạo đến vận hành

Dưới đây là 4 bước chuẩn hóa dự án Python với uv mà bạn có thể áp dụng ngay cho team.

1. Tải và quản lý phiên bản Python

Quên việc chờ build Python từ source hàng chục phút qua pyenv đi. uv tải thẳng bản build standalone tối ưu cho từng OS chỉ trong 5-10 giây:

# Tải Python 3.12 bản mới nhất
uv python install 3.12

# Liệt kê các phiên bản đang có trên máy
uv python list

2. Khởi tạo cấu trúc dự án

Khởi tạo project theo chuẩn pyproject.toml hiện đại:

mkdir my-fastapi-app && cd my-fastapi-app
uv init --app
# Khóa phiên bản Python cố định cho repo
uv python pin 3.12

Lệnh trên sinh ngay file pyproject.toml, cấu hình .python-version và file mẫu main.py.

3. Thêm thư viện và tự động khóa version

Thay vì chạy pip install rồi nhớ tay pip freeze > requirements.txt, uv tự cập nhật pyproject.toml và sinh file uv.lock:

# Thêm production package
uv add fastapi "uvicorn[standard]" pydantic

# Thêm dev tool phục vụ kiểm thử và format code
uv add --dev pytest pytest-cov ruff

File uv.lock chạy nhất quán trên cả Linux, macOS lẫn Windows. Toàn bộ package đều có mã băm SHA256 để chống giả mạo mã nguồn.

4. Chạy lệnh trực tiếp, không cần activate venv

Bạn không cần gõ source .venv/bin/activate mỗi khi mở tab terminal mới. Hãy để uv run tự lo:

# Khởi động server FastAPI
uv run uvicorn main:app --reload

# Chạy test suite
uv run pytest

Nếu dùng VS Code hay PyCharm, uv vẫn tạo sẵn thư mục .venv trong project để IDE tự nhận diện interpreter mượt mà.

Kiểm tra, tối ưu và dọn dẹp cache

Khi đưa uv vào pipeline CI/CD, có 3 thao tác kiểm tra bạn nên đưa vào checklist.

1. Soi cây phụ thuộc (Dependency Tree)

Để biết một thư viện kéo theo những gói con nào và tìm xung đột version:

uv tree

Giao diện cây trực quan giúp bạn phát hiện ngay các package nặng bất thường để loại bỏ kịp thời.

2. Kiểm tra tính toàn vẹn của Lockfile trên CI/CD

Tránh tình trạng code sửa dependencies mà quên commit lockfile trước khi deploy:

# Báo lỗi ngay nếu lockfile lệch với pyproject.toml
uv lock --check

# Cài đặt nguyên trạng môi trường production (tương đương npm ci)
uv sync --frozen --no-dev

3. Tiết kiệm ổ cứng nhờ Global Cache

uv dùng cơ chế hard-link từ global cache. Nếu 10 project cùng dùng torch hay pydantic==2.6.0, uv chỉ tải đúng một lần về máy. Ổ cứng tiết kiệm được hàng chục gigabyte dung lượng thừa.

Kiểm tra vị trí và dung lượng thư mục cache:

uv cache dir

Sau nhiều tháng chạy thử nghiệm các package khác nhau, bạn có thể dọn dẹp:

# Xóa các package không còn project nào trỏ tới
uv cache prune

# Xóa sạch cache nếu cần giải phóng triệt để ổ cứng
uv cache clean

Hiệu quả thấy rõ nhất là ở CI pipeline: thời gian build Docker image cho một app FastAPI 50MB code giảm từ hơn 2 phút 30 giây xuống còn vỏn vẹn 11 giây. Nếu đang đau đầu vì pip chậm chạp, uv là khoản đầu tư chuyển đổi xứng đáng nhất cho bạn ngay hôm nay.