Sửa lỗi 'error: externally-managed-environment' Khi Cài Package Python bằng pip

Lỗi Gặp Phải

Bạn chạy một lệnh pip install đơn giản và gặp phải lỗi sau:

$ pip install requests
error: externally-managed-environment

× This environment is managed by an external package manager.
╰─> To install Python packages system-wide, use apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have the python3-full apt package installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have the pipx package
    installed.

    If you are using a Python Virtual Environment (like .venv), make
    sure it is active before running pip install. Consult the
    python3 venv documentation for instructions.

    For more information, visit https://packaging.python.org/en/latest/specifications/externally-managed-environments/

Nguyên Nhân

Bắt đầu từ Python 3.11 và PEP 668, các bản phân phối như Ubuntu 23.04+, Debian 12 (Bookworm) và Fedora 38+ đánh dấu Python hệ thống của họ là "externally managed" (được quản lý bên ngoài). Trình quản lý gói của distro — apt, dnf, hay bất kỳ thứ gì — là chủ sở hữu của cài đặt Python đó. pip bị chặn, không được can thiệp vào.

Trước khi có thay đổi này, pip install sẽ âm thầm đẩy các gói vào site-packages của Python hệ thống. Điều đó gây ra không ít đau đầu: các gói cài qua pip sẽ xung đột với các gói do distro đóng gói, làm hỏng các công cụ hệ thống phụ thuộc vào phiên bản cụ thể. Ví dụ, trình quản lý gói cập nhật python3-requests từ 2.28 lên 2.31 có thể âm thầm phá vỡ một gói cài qua pip đang ghim vào API cũ hơn.

Việc chặn được thực thi bởi một file đánh dấu duy nhất:

/usr/lib/python3.x/EXTERNALLY-MANAGED

pip phát hiện file đó và từ chối tiến hành. Đơn giản vậy thôi.

Cách Sửa: Dùng Virtual Environment (Cách Đúng)

Chín phần mười trường hợp, đây là cách nên làm. Virtual environment cho project của bạn một Python và thư mục gói riêng biệt, hoàn toàn tách rời khỏi Python hệ thống.

Bước 1: Tạo virtual environment

# Trong thư mục project của bạn
python3 -m venv .venv

Bước 2: Kích hoạt

# Trên Linux/macOS
source .venv/bin/activate

# Trên Windows (nếu không dùng WSL)
.venv\Scripts\activate

Bước 3: Cài đặt gói bình thường

pip install requests

Kiểm tra kết quả

# Kiểm tra pip đang trỏ đến đâu
which pip
# Kết quả phải là: /your/project/.venv/bin/pip

# Xác nhận gói đã được cài
pip show requests

Khi xong việc, thoát khỏi virtual environment bằng:

deactivate

Cách Sửa: Với CLI Tools — Dùng pipx

Cần cài một công cụ dòng lệnh độc lập? Đừng dùng venv của project cho mục đích đó. pipx được tạo ra chính xác cho trường hợp này. Nó tạo một môi trường riêng biệt cho từng công cụ, rồi gắn binary vào PATH — bạn không cần bận tâm gì thêm.

# Cài pipx
sudo apt install pipx
pipx ensurepath

# Sau đó cài bất kỳ CLI tool nào
pipx install black
pipx install httpie

Sau đó, black và http hoạt động từ bất kỳ đâu. Không cần kích hoạt venv, không cần quản lý môi trường.

Cách Sửa: Bỏ Qua Giới Hạn (Nhanh Nhưng Rủi Ro)

Bạn có thể ép pip vượt qua giới hạn bằng flag --break-system-packages:

pip install requests --break-system-packages

Tên flag được đặt cố tình để gây lo ngại. Nó tồn tại để bạn không thể đổ lỗi cho ai khác ngoài chính mình.

Có những trường hợp dùng hợp lý — ví dụ bên trong Docker container, nơi hệ thống đã được cô lập và bạn không quan tâm đến xung đột gói. Nhưng trên máy dev thực của bạn? Đừng làm vậy. Một gói cài qua pip xung đột với gói hệ thống có thể làm hỏng apt, network manager, hoặc bất cứ thứ gì dựa vào Python hệ thống.

Cách Sửa: Xóa File Đánh Dấu (Không Khuyến Nghị)

Một số hướng dẫn bảo bạn chỉ cần xóa file kích hoạt lỗi:

# Tìm file
python3 -c "import sys; print(sys.prefix)"

# Ví dụ đường dẫn trên Ubuntu 23.10
sudo rm /usr/lib/python3.11/EXTERNALLY-MANAGED

Đúng là nó hoạt động. Nhưng cũng tương đương với việc tháo pin khỏi đầu báo khói. Lớp bảo vệ biến mất vĩnh viễn, và các lần pip install sau sẽ lặng lẽ ghi đè lên các gói hệ thống. Tạo một venv chỉ mất 10 giây — hãy làm vậy thay thế.

Cách Sửa: Cài Qua apt Cho Gói Toàn Hệ Thống

Một số gói thực sự cần có mặt trên toàn bộ hệ thống, không chỉ một project. Hãy kiểm tra xem distro của bạn đã có sẵn chưa:

# Tìm kiếm gói có sẵn
apt search python3-requests

# Cài qua apt
sudo apt install python3-requests

Các gói cài qua apt tích hợp gọn gàng vào hệ thống và không bao giờ kích hoạt lỗi này. Điểm hạn chế: các gói của distro thường đi sau PyPI, đôi khi vài tháng.

Tình Huống Thực Tế: Khởi Tạo Project Mới Từ Đầu

Đây là quy trình đầy đủ từ đầu đến cuối:

# 1. Đảm bảo python3-venv đã được cài (Ubuntu)
sudo apt install python3-venv python3-full

# 2. Tạo project
mkdir myproject && cd myproject

# 3. Tạo virtual environment
python3 -m venv .venv

# 4. Kích hoạt
source .venv/bin/activate

# 5. Cài gói thoải mái
pip install flask sqlalchemy gunicorn

# 6. Lưu danh sách dependencies
pip freeze > requirements.txt

Tình Huống Thực Tế: Docker Container

Các base image Debian và Ubuntu cũng kích hoạt lỗi này trong Dockerfile. Do container đã được cô lập sẵn, dùng --break-system-packages là lựa chọn thực tế ở đây:

FROM python:3.12-slim

COPY requirements.txt .
RUN pip install --break-system-packages -r requirements.txt

Hai lựa chọn khác: chuyển sang image python:3.12 chính thức (không có giới hạn), hoặc tạo một venv thực sự bên trong container nếu bạn muốn cô lập triệt để.

Phòng Tránh

Tạo .venv ngay từ đầu mỗi Python project — coi đó như việc tạo repo, không phải thứ bạn làm khi mọi thứ hỏng.
Thêm .venv/ vào .gitignore ngay lập tức.
Dùng pipx khi cài CLI tool, không phải thư viện.
Làm việc nhóm? Ghi hướng dẫn setup venv vào README. Đồng nghiệp tương lai sẽ cảm ơn bạn.
Hãy thử xem uv — một công cụ thay thế pip và venv viết bằng Rust, nhanh hơn 10–100 lần và tự động xử lý việc tạo môi trường: uv venv && uv pip install requests.