Môi trường ảo, pip, uv và pyproject.toml cho dự án Python
Mỗi dự án một môi trường: venv, pip, requirements.txt, rồi chuyển sang uv với pyproject.toml, uv.lock, uv add, uv run, uv sync.
Học xong bài này, bạn sẽ
- Tạo và dùng môi trường ảo cho từng dự án
- Cài, khóa phiên bản thư viện bằng pip và requirements.txt
- Quản lý dự án bằng uv và pyproject.toml
Nên học trước: Type hint nâng cao và kiểm tra kiểu bằng mypy
Nội dung bài viết
Dự án A cần requests 2.28, dự án B cần bản 2.34. Cài chung vào Python của máy thì một trong hai sẽ hỏng. Đồng nghiệp clone code của bạn về, chạy báo thiếu thư viện. Máy chủ cài bản khác máy bạn nên kết quả khác. Ba vấn đề này đều được giải bằng môi trường ảo và khóa phiên bản thư viện. Bài này dạy cách làm truyền thống với venv + pip, rồi cách hiện đại với uv.
1. Môi trường ảo là gì
Môi trường ảo là một thư mục (thường tên .venv) chứa một bản Python riêng và thư viện riêng của dự án. Mỗi dự án một môi trường, không ảnh hưởng nhau, không ảnh hưởng Python của hệ thống. Xóa thư mục .venv là xóa sạch, tạo lại lúc nào cũng được.
2. Cách truyền thống: venv và pip
PS D:\du-an> python -m venv .venv # tạo môi trường
PS D:\du-an> .venv\Scripts\Activate.ps1 # kích hoạt (Windows PowerShell)
(.venv) PS D:\du-an> python -m pip install requests
(.venv) PS D:\du-an> python -m pip freeze > requirements.txt
(.venv) PS D:\du-an> deactivate # thoát môi trường
$ source .venv/bin/activate # kích hoạt trên macOS, Linux
- Sau khi kích hoạt, dấu nhắc có
(.venv)và lệnhpython,piptrỏ vào môi trường của dự án. - Dùng
python -m pipthay vìpipđể chắc chắn cài vào đúng Python đang dùng. pip freeze > requirements.txtghi lại mọi thư viện kèm phiên bản chính xác. Người khác tái tạo bằngpip install -r requirements.txt.- Trên Windows, nếu PowerShell báo không được chạy script, chạy một lần:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
VS Code tự nhận .venv trong thư mục dự án; nếu không, chọn bằng Python: Select Interpreter. Cách này vẫn rất phổ biến và bạn cần biết, nhưng nó có nhược điểm: requirements.txt trộn thư viện bạn chọn với thư viện kéo theo, không tách thư viện cho dev (pytest) với thư viện chạy thật, và pip cài khá chậm.
3. Cách hiện đại: uv
uv (của Astral, cùng nhóm làm Ruff) là công cụ viết bằng Rust thay thế pip, venv, pip-tools và cả việc cài Python, nhanh hơn pip nhiều lần. Cài một lần:
PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
$ curl -LsSf https://astral.sh/uv/install.sh | sh # macOS, Linux
$ uv --version
uv 0.13.6
Tạo dự án
$ uv init chi-tieu
Initialized project `chi-tieu`
$ cd chi-tieu
$ tree /f (Windows; macOS, Linux dùng: tree -a)
chi-tieu
├── .gitignore
├── .python-version ← phiên bản Python của dự án
├── README.md
├── pyproject.toml ← khai báo dự án và thư viện
└── src
└── chi_tieu
└── __init__.py
Bản uv hiện tại mặc định tạo dự án dạng package với thư mục src/ (bài cuối của chặng sẽ giải thích vì sao đây là cấu trúc tốt). Muốn một dự án phẳng gồm file main.py cho script nhỏ, dùng uv init --no-package ten-du-an. Lệnh uv init còn tạo sẵn kho Git.
Thêm thư viện
$ uv add requests
Installed 6 packages in 32ms
+ certifi==2026.10.23
+ charset-normalizer==3.5.2
+ chi-tieu==0.1.0 (from file:///.../chi-tieu)
+ idna==3.20
+ requests==2.34.2
+ urllib3==2.8.0
$ uv add --dev pytest
Lần đầu, uv tự tạo .venv (và tự tải Python nếu máy chưa có bản phù hợp), cài thư viện, rồi cập nhật hai file:
# pyproject.toml
[project]
name = "chi-tieu"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
"requests>=2.34.2", ← chỉ thư viện BẠN chọn
]
[project.scripts]
chi-tieu = "chi_tieu:main" ← lệnh chạy được từ terminal
[dependency-groups]
dev = [
"pytest>=9.2.0", ← chỉ dùng khi phát triển
]
và uv.lock: ghi phiên bản chính xác của mọi thư viện kể cả thư viện kéo theo (certifi, idna...), cho mọi hệ điều hành. Commit cả pyproject.toml lẫn uv.lock vào Git; không commit .venv.
Chạy và đồng bộ
$ uv run chi-tieu # chạy lệnh khai báo trong [project.scripts]
Hello from chi-tieu!
$ uv run python -c "import requests; print(requests.__version__)"
2.34.2
$ uv run pytest # chạy công cụ trong môi trường dự án
$ uv sync # máy mới, vừa clone: cài đúng y như uv.lock
$ uv tree # xem cây phụ thuộc
$ uv remove requests # gỡ thư viện
uv run tự kiểm tra môi trường khớp với uv.lock rồi chạy lệnh trong đó: không cần kích hoạt môi trường, không lo quên cài.
Quản lý phiên bản Python
$ uv python install 3.15 # tải và cài Python 3.15
$ uv python pin 3.14 # ghi 3.14 vào .python-version của dự án
$ uv run --python 3.13 pytest # chạy thử với phiên bản khác
4. Quy trình làm việc hằng ngày
| Việc | pip + venv | uv |
|---|---|---|
| Tạo dự án | python -m venv .venv | uv init |
| Thêm thư viện | pip install x rồi pip freeze | uv add x |
| Thư viện cho dev | File requirements riêng | uv add --dev x |
| Máy mới | pip install -r requirements.txt | uv sync |
| Chạy | Kích hoạt rồi python main.py | uv run main.py |
pip install khi chưa kích hoạt môi trường nào sẽ cài vào Python chung của máy. Lâu dần các dự án xung đột phiên bản và rất khó dọn. Trên nhiều bản Linux mới, pip còn từ chối cài với lỗi externally-managed-environment. Muốn cài một công cụ dòng lệnh dùng chung (ví dụ ruff), dùng uv tool install ruff: mỗi công cụ một môi trường riêng.Tóm tắt
- Mỗi dự án một môi trường ảo
.venv; không commit.venv. - Truyền thống:
python -m venv .venv, kích hoạt,python -m pip install,requirements.txt. - uv:
uv init,uv add,uv add --dev,uv run,uv sync; commitpyproject.toml+uv.lock. uv python install/pinquản lý phiên bản Python;uv tool installcho công cụ dùng chung.
Bài tập
Bài 1. Dự án đầu tiên với uv
Tạo dự án bằng uv init, thêm requests và pytest (nhóm dev), sửa hàm main in phiên bản requests, chạy bằng uv run.
Xem đáp án
$ uv init thu-uv && cd thu-uv
$ uv add requests
$ uv add --dev pytest
Sửa src/thu_uv/__init__.py:
import requests
def main() -> None:
print(f"requests {requests.__version__}")
$ uv run thu-uv
requests 2.34.2
Mở pyproject.toml: requests nằm trong dependencies, pytest nằm trong [dependency-groups] dev. Khi đóng gói triển khai, có thể cài không kèm nhóm dev bằng uv sync --no-dev.
Bài 2. Tái tạo môi trường
Chép dự án bài 1 sang thư mục khác không kèm .venv, tái tạo môi trường và chạy lại.
Xem đáp án
$ git clone thu-uv thu-uv-ban-sao # uv init đã tạo kho git; cần commit trước
$ cd thu-uv-ban-sao
$ uv sync
$ uv run thu-uv
requests 2.34.2
Hoặc chép tay mọi file trừ .venv. uv sync đọc uv.lock và cài đúng từng phiên bản, nên kết quả giống hệt máy gốc. Đây chính là điều diễn ra khi đồng nghiệp clone dự án của bạn, hoặc khi máy chủ CI chạy test (chặng 10).
Nguồn tham khảo: venv: Creation of virtual environments; Python Packaging User Guide: pip và virtual environments; uv: Working on projects.
Bài tập thực hành
- Tạo dự án bằng uv init, thêm requests và pytest (nhóm dev), chạy script bằng uv run.
- Tái tạo môi trường của dự án trên một thư mục khác chỉ từ pyproject.toml và uv.lock.
Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.


