...
Eroare Docker · Dockerfile și docker build

error: externally-managed-environment

Pe scurt

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

Greșit
BASH
FROM debian:12
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install -r requirements.txt
Corect
BASH
FROM python:3.12-slim
RUN pip install --no-cache-dir -r requirements.txt

Imaginea oficială python are pip-ul propriu, fără marcajul „externally managed”.

2Ai nevoie de baza Debian/Ubuntu

Greșit
BASH
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y python3-pip
RUN pip install flask
Corect
BASH
FROM 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ă

Greșit
BASH
RUN pip install flask
Corect
BASH
RUN pip install --break-system-packages flask

Merge, dar poate strica pachete Python ale sistemului; folosește-l doar dacă știi că imaginea nu depinde de ele.

Repară tu

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"].

Alte forme ale mesajului

  • × This environment is externally managed
  • ERROR: 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

← Toate erorile Docker

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Î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.