Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

You cannot pip install packages inside an Ubuntu Docker container

Errorpip: command not found

Short answer

If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update. If pip exists but refuses, the distribution marked its Python as externally managed (PEP 668): use a virtual environment, or in a single-purpose image pass --break-system-packages.

  • Applies to Docker Engine 27, ubuntu:24.04 image, Python 3.12, pip 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the base image on its own and ask which of python3 and pip exist. The result splits the causes.

    docker run --rm ubuntu:24.04 sh -c 'command -v python3; command -v pip3; echo done'
  2. 2Match what you see, then jump to its fix

    1. 1pip: command not found, or pip3 not found, in a fresh ubuntu imagepip is not installed in the imageFix
    2. 2apt cannot find the package in a build that has apt-get update on its own line, or a cached older layerapt-get update ran in a different layer from apt-get installFix
    3. 3pip exists, but pip install stops with externally-managed-environmentUbuntu's Python is externally managed (PEP 668)Fix

What does the error look like?

  • pip: command not found
  • error: externally-managed-environment

Cause 1 of 3

pip is not installed in the image

1Check

Ubuntu publishes pip as the python3-pip package. The first step shows whether the image has it; check whether your Dockerfile installs it.

grep -n 'python3-pip\|apt-get' Dockerfile

2Fix

Install it with apt, and call pip through python3 so it matches the interpreter.

RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip \
    && rm -rf /var/lib/apt/lists/*

3Verify

pip answers inside the image.

docker run --rm my-image python3 -m pip --version

Confirmed by packages.ubuntu.com

Did this fix it?

Cause 2 of 3

apt-get update ran in a different layer from apt-get install

1Check

Docker's best-practice guide says to always combine apt-get update with apt-get install in one RUN, because a lone update line is cached and later installs then fail.

grep -n -B1 -A1 'apt-get' Dockerfile

2Fix

Put both in one RUN instruction, and rebuild without the cache once to drop the stale layer.

RUN apt-get update && apt-get install -y --no-install-recommends python3-pip

3Verify

The build passes the apt step.

docker build --no-cache -t my-image .

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Ubuntu's Python is externally managed (PEP 668)

1Check

PEP 668 lets a distribution mark its Python as managed by the package manager, and installers must then refuse system-wide installs unless overridden. The marker is a file named EXTERNALLY-MANAGED in the Python library folder.

docker run --rm ubuntu:24.04 sh -c 'ls /usr/lib/python3*/EXTERNALLY-MANAGED'

2Fix

Best is a virtual environment: the PEP says even in containers this is a good idea, because OS commands written in Python can break. For a single-purpose image, the pip flag --break-system-packages is the documented override, shown here.

# single-purpose image only
RUN python3 -m pip install --break-system-packages -r requirements.txt

3Verify

pip lists the packages.

docker run --rm my-image python3 -m pip list

Confirmed by peps.python.org

Did this fix it?

How do I stop it coming back?

  • Always write apt-get update && apt-get install in one RUN.
  • Choose a base image that already has Python and pip when you do not need Ubuntu itself.
  • Pin dependency versions in requirements.txt so image builds repeat.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.