error: externally-managed-environment
Imaginile Debian 12 și Ubuntu 23.04+ interzic pip install în Python-ul sistemului (PEP 668), iar build-ul cade la RUN pip install. Pornește din imaginea oficială python (FROM python:3.12-slim), unde pip merge direct, sau folosește un mediu virtual (python3 -m venv).
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Pe distribuțiile noi, Python-ul instalat cu apt e „gestionat extern”: pachetele lui aparțin sistemului de pachete. Ca să nu strice uneltele sistemului, pip refuză să instaleze global și afișează error: externally-managed-environment, urmat de un text care îți recomandă apt install python3-xyz sau un mediu virtual.
În Docker apare când pornești din debian:12, ubuntu:24.04 sau dintr-o imagine construită peste ele, instalezi python3-pip cu apt-get și apoi rulezi pip install. Build-ul se oprește la acel RUN cu exit code: 1.
Imaginile oficiale python:3.x (inclusiv -slim și -alpine) nu au restricția: Python-ul lor e compilat separat, în /usr/local, iar pip install merge cum te aștepți. De aceea, pentru aplicații Python, imaginea python e alegerea firească.
De ce apare: cauzele frecvente
1Python din apt peste debian/ubuntu
FROM debian:12
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install -r requirements.txtFROM python:3.12-slim
RUN pip install --no-cache-dir -r requirements.txtImaginea oficială python are pip-ul propriu, fără marcajul „externally managed”.
2Ai nevoie de baza Debian/Ubuntu
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y python3-pip
RUN pip install flaskFROM ubuntu:24.04
RUN apt-get update && apt-get install -y python3-venv
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install flaskÎntr-un mediu virtual pip are voie să instaleze, iar PATH face ca python și pip să fie cele din venv.
3Ocolirea forțată
RUN pip install flaskRUN pip install --break-system-packages flaskMerge, dar poate strica pachete Python ale sistemului; folosește-l doar dacă știi că imaginea nu depinde de ele.
Repară eroarea, direct în pagină
În ~/flask, Dockerfile-ul pornește din debian:12, instalează python3-pip și rulează pip3 install -r requirements.txt, iar build-ul cade cu error: externally-managed-environment. Rescrie Dockerfile-ul pe imaginea python:3.12-slim, construiește api:1.0 și pornește containerul api pe portul 5000 (pagina trebuie să afișeze Salut).
Indiciu
FROM python:3.12-slim, apoi WORKDIR /app, COPY, RUN pip install -r requirements.txt, CMD ["python", "app.py"].
Reparația
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
CMD ["python", "app.py"]docker build -t api:1.0 .
docker run -d --name api -p 5000:5000 api:1.0
curl -s localhost:5000SalutDe ce merge
Python-ul din apt al lui Debian 12 e marcat ca gestionat de sistem, deci pip refuza instalarea globală. Imaginea python:3.12-slim are Python și pip instalate separat, în /usr/local, unde pip install e permis. Build-ul trece, Flask e instalat, iar containerul răspunde pe portul 5000 pentru că app.py ascultă pe 0.0.0.0.
Alte forme ale mesajului
× This environment is externally managedERROR: failed to solve: process "/bin/sh -c pip3 install -r requirements.txt" did not complete successfully: exit code: 1
Cum o eviți pe viitor
Pentru aplicații Python, pornește din python:3.12-slim (sau versiunea ta), nu din debian/ubuntu cu Python din apt. Dacă baza trebuie să fie alta, creează un mediu virtual în Dockerfile și pune-l în PATH. Fixează versiunea de Python în tag, ca build-ul să nu se schimbe singur când apare o versiune nouă de Debian.
Întrebări frecvente
De ce pe laptop merge pip install?
Probabil ai Python instalat separat (python.org, Homebrew, pyenv) sau lucrezi într-un venv. Restricția se aplică doar Python-ului de sistem al distribuțiilor noi.
Pot folosi apt install python3-flask?
Da, dacă pachetul există în Debian, dar primești versiunea din distribuție, de obicei mai veche decât cea din requirements.txt. În imaginea python controlezi exact versiunile.
Erori înrudite
ERROR: failed to solve: process "/bin/sh -c npm instal" did not complete successfully: exit code: 1 Comanda dintr-un RUN a eșuat în timpul build-ului (codul 1). Motivul real e în liniile de deasupra mesajului, în blocul > [3/3] RUN ...: o comandă scrisă greșit, un pachet inexistent, apt-get install fără apt-get update sau un fișier necopiat încă. ERROR: Could not find a version that satisfies the requirement flsk (from versions: none) pip nu găsește pe PyPI niciun pachet sau nicio versiune potrivită pentru ce ai cerut: nume scris greșit (flsk), versiune inexistentă sau incompatibilă cu Python-ul din imagine, ori lipsă de acces la internet în build. Corectează linia din requirements.txt și reconstruiește. ModuleNotFoundError: No module named 'flask' Aplicația Python pornește în container, dar pachetul flask nu e instalat în imagine, așa că se oprește imediat cu Exited (1). Adaugă în Dockerfile COPY requirements.txt . și RUN pip install --no-cache-dir -r requirements.txt, apoi reconstruiește imaginea. Învață Docker de la zero, cu exerciții la fiecare lecție
Curs Docker: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.
