Môi trường ảo Python: venv, kích hoạt và requirements.txt

Vấn đề mà môi trường ảo giải quyết

Cài Python, chạy pip install requests, và package đó nằm ở một nơi duy nhất dùng chung cho cả máy. Với một dự án thì ổn. Đến dự án thứ ba, rắc rối bắt đầu:

• Dự án A cần django==3.2. Dự án B cần django==5.0. Chỉ một trong hai có thể cài phiên bản của mình ở cấp toàn máy.
• Bạn muốn thử một thư viện mới nhưng không muốn nó làm bẩn mọi dự án khác trên máy.
• Một đồng đội clone repo của bạn và không biết bạn thực sự phụ thuộc vào phiên bản nào của package nào.

Môi trường ảo (virtual environment) chính là giải pháp. Đó là một thư mục độc lập chứa một trình thông dịch Python và thư mục cài thư viện riêng. Khi môi trường được kích hoạt, python và pip trong terminal sẽ trỏ vào bên trong thư mục đó thay vì Python của toàn hệ thống. Các package cài ở đó sẽ ở yên đó.

Tạo môi trường bằng venv

venv đi kèm sẵn với Python 3, không cần cài gì thêm. Từ bên trong thư mục dự án:

python3 -m venv .venv

Lệnh này tạo một thư mục .venv/ cạnh code của bạn. Tên .venv là quy ước gần như phổ quát; dấu chấm ở đầu giúp nó không xuất hiện trong phần lớn các danh sách thư mục, và các trình soạn thảo như VS Code tự động nhận ra nó.

Sau khi lệnh chạy xong, thư mục chứa một bản cài Python đầy đủ (vài chục megabyte, điều này là bình thường) và một pip riêng.

Kích hoạt môi trường

Kích hoạt sẽ sửa lại PATH của shell để python và pip trỏ đến các bản nằm trong .venv/. Lệnh tùy theo nền tảng:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Dấu nhắc lệnh sẽ có thêm tiền tố (.venv) khi môi trường đang hoạt động, như một lời nhắc trực quan. Mọi lệnh pip install bạn chạy lúc này chỉ ảnh hưởng đến dự án này.

Khi xong việc trong ngày, deactivate sẽ khôi phục trạng thái trước đó:

deactivate

Bạn không cần deactivate trước khi đóng terminal: thoát shell cũng có tác dụng tương tự.

Cài package

Khi môi trường đang hoạt động, hãy cài những gì bạn cần:

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

Xem những gì đã cài bằng pip list. Gỡ một package bằng pip uninstall requests.

Các package đã cài nằm trong .venv/lib/pythonX.Y/site-packages/. Bạn không bao giờ sửa tay những thứ đó: pip quản lý thư mục này.

Cố định phụ thuộc bằng requirements.txt

Dự án của bạn chỉ tái tạo được nếu người khác cài được đúng các phiên bản bạn đã dùng. Cách đơn giản nhất để ghi lại điều đó là requirements.txt:

pip freeze > requirements.txt

pip freeze in ra mọi package đã cài kèm phiên bản chính xác. Hãy commit tệp này lên git.

Khi một người cùng làm (hoặc chính bạn trên máy mới) clone repo:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Ba lệnh và môi trường của họ khớp với của bạn.

Một cách thiết lập dự án phổ biến

Toàn bộ quy trình, từ đầu đến cuối:

# Create the project folder
mkdir my_tool && cd my_tool

# Create and activate the venv
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install requests rich

# Save them
pip freeze > requirements.txt

# Work on your code...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# When you're done
deactivate

Thêm .venv vào .gitignore

Đừng bao giờ commit thư mục .venv/. Nó phụ thuộc vào nền tảng và có thể tạo lại từ requirements.txt:

# .gitignore
.venv/
__pycache__/
*.pyc

Commit nó sẽ làm repo phình to, hỏng trên máy khác và để lộ mọi tệp nhị phân riêng của hệ điều hành mà trình thông dịch của bạn có.

Phiên bản Python nào?

Mặc định, python3 -m venv .venv dùng bản python3 mà shell của bạn tìm thấy. Nếu bạn cài nhiều bản Python (chẳng hạn 3.12 và 3.13), hãy chỉ rõ bản nào:

python3.13 -m venv .venv

Khi venv đã tồn tại, trình thông dịch của nó được cố định: chạy python bên trong venv đã kích hoạt luôn dùng đúng phiên bản đó, kể cả khi Python của hệ thống thay đổi.

Khi có trục trặc

Vài triệu chứng thường gặp và cách khắc phục:

• pip install chạy được, nhưng import lại lỗi. Bạn đã cài vào nhầm Python. Hãy kích hoạt venv trước khi pip install, rồi kiểm tra lại bằng which python (macOS/Linux) hoặc where python (Windows).
• "ModuleNotFoundError" sau khi kích hoạt. Venv được tạo mà thiếu một số thư viện, hoặc package đã được cài vào một venv khác. pip list cho thấy chính xác những gì có trong venv hiện tại.
• Không tìm thấy script kích hoạt trên Windows. PowerShell có thể chặn các script chưa được ký. Chạy Set-ExecutionPolicy -Scope CurrentUser RemoteSigned một lần để cho phép script cục bộ.
• "No module named venv". Trên một số bản phân phối Linux, venv là một package riêng. Dùng sudo apt install python3-venv trên Debian/Ubuntu.

Ngoài venv: Poetry, uv, pipenv

Khi đã quen với venv + pip + requirements.txt, bạn sẽ gặp những công cụ bọc cùng các ý tưởng đó nhưng tiện dụng hơn:

• Poetry: quản lý venv, phụ thuộc và đóng gói chỉ với một tệp pyproject.toml.
• uv: công cụ thay thế pip cực nhanh, dùng được ngay; xử lý cả venv.
• pipenv: công cụ cũ hơn đã phổ biến mô hình "Pipfile + Pipfile.lock".

Tất cả đều tốt. Không cái nào bắt buộc khi học. Hãy làm quen với quy trình venv thuần trước; những thứ còn lại chỉ là tối ưu thêm.

Điều cần nhớ

• Mọi dự án Python thực tế đều có môi trường ảo riêng.
• Tạo một môi trường bằng python3 -m venv .venv, kích hoạt nó, rồi thoải mái pip install.
• Cố định phụ thuộc bằng pip freeze > requirements.txt và commit tệp đó.
• Đừng bao giờ commit chính thư mục .venv/.
• Khi import có vấn đề, hãy kiểm tra Python nào đang được kích hoạt trước tiên.

Tiếp theo: mẫu __main__

Khi dự án đã được thiết lập và package đã cài xong, còn một cách viết quen thuộc cuối cùng khép lại chương này: điều kiện bảo vệ if __name__ == "__main__". Nó có mặt trong gần như mọi tệp Python được viết để chạy như một script, và là chủ đề của trang tiếp theo.