Bài 14. Môi trường và quản lý dự án với uv

Dự án thật cần quản lý phiên bản Python, thư viện và cấu trúc thư mục. Bài này giới thiệu uv, công cụ hiện đại và rất nhanh đang dần thay pip/venv, cùng tệp pyproject.toml và Ruff.

40 phútTrung cấp
Bạn sẽ học được
  • Hiểu môi trường ảo và vì sao cần nó
  • Tạo dự án, thêm thư viện bằng uv
  • Đọc hiểu pyproject.toml và uv.lock
  • Định dạng, kiểm tra mã bằng Ruff
Thuật ngữ cần biết
Môi trường ảo
Thư mục chứa Python và thư viện riêng cho một dự án.
pyproject.toml
Tệp cấu hình chuẩn của dự án Python.
Lockfile
Tệp ghi phiên bản chính xác mọi thư viện.
uv
Trình quản lý gói và dự án Python viết bằng Rust.

Khái niệm và lý thuyết

Nếu cài mọi thư viện vào Python chung của máy, các dự án sẽ xung đột phiên bản (dự án A cần pandas 2.2, dự án B cần 3.0). Môi trường ảo tách riêng thư viện cho từng dự án. Bài 8 đã dùng venv + pip; uv gộp tất cả (cài Python, tạo môi trường, cài gói, khóa phiên bản, chạy script) vào một công cụ nhanh hơn pip 10–100 lần.

Cài uv và tạo dự án

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.15     # cài Python nếu máy chưa có
uv init so-chi-tieu
cd so-chi-tieu
uv add requests rich       # thêm thư viện
uv add --dev pytest ruff   # thư viện cho phát triển
uv run main.py             # chạy trong môi trường của dự án

Cấu trúc dự án

so-chi-tieu/
├── pyproject.toml      # tên, phiên bản, thư viện
├── uv.lock             # phiên bản chính xác (commit lên Git)
├── .venv/              # môi trường ảo (không commit)
├── src/so_chi_tieu/
│   ├── __init__.py
│   └── core.py
└── tests/test_core.py
[project]
name = "so-chi-tieu"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["requests>=2.32", "rich>=14"]

Ruff: định dạng và kiểm tra

uv run ruff format .     # định dạng như Black
uv run ruff check --fix .  # tìm lỗi, tự sửa

Người khác lấy dự án về chỉ cần uv sync là có đúng môi trường. Chạy nhanh một công cụ không cần cài: uvx ruff check.

Mẹo hay

Script một tệp có thể tự khai báo thư viện ở đầu tệp (inline metadata); uv run script.py sẽ tự cài đủ rồi chạy.

Lưu ý

Đừng commit thư mục .venv lên Git; thêm vào .gitignore (uv init đã tạo sẵn).

Thực hành
  1. Cài uv, tạo dự án mới, thêm thư viện rich và in bảng màu ra terminal.
  2. Chuyển dự án Bài 10 sang cấu trúc uv với thư mục src.
  3. Chạy ruff check và sửa các cảnh báo.
  4. Xóa .venv rồi chạy uv sync để tái tạo môi trường.
Tóm tắt bài học
  • Mỗi dự án một môi trường ảo.
  • uv: cài Python, quản lý gói, khóa phiên bản, chạy script.
  • pyproject.toml + uv.lock mô tả dự án.
  • Ruff định dạng và kiểm tra mã.