Python ensurepip: Restore pip Offline

Python ensurepip installs or restores pip using components bundled with the interpreter. It does not access the internet. Its purpose is to bootstrap the package installer when setup skipped that step, when pip was removed, or when an environment needs a minimal functional version.

Most users never need to invoke ensurepip directly because official installers and venv usually include pip. Some Linux distributions package or disable it separately. In that case, follow the Python provider’s instructions rather than forcing changes into the operating system’s managed environment.

Check the active interpreter and pip

Before repairing anything, confirm which Python and pip are in use.

python -c "import sys; print(sys.executable)"
python -m pip --version

Prefer python -m pip over a standalone pip command. The module form uses the installer associated with the selected interpreter.

Basic bootstrap

The simplest command installs pip only when it is missing.

python -m ensurepip

The operation uses bundled wheels and does not download the newest release. The available version depends on the installed CPython maintenance release.

Upgrade to the bundled version

Use --upgrade to ensure the installed pip is at least as recent as the copy bundled with ensurepip.

python -m ensurepip --upgrade

This differs from python -m pip install --upgrade pip, which normally contacts a package index. Ensurepip remains offline.

Bootstrap inside a virtual environment

When a virtual environment is active, ensurepip installs into that environment.

python -m venv .venv
# Linux or macOS
source .venv/bin/activate
# Windows PowerShell:
# .venv\Scripts\Activate.ps1

python -m ensurepip --upgrade
python -m pip --version

This is the safest project workflow. Avoid modifying the system Python, which may be managed by the operating system.

Create a venv without pip

venv supports --without-pip.

python -m venv --without-pip environment
environment/bin/python -m ensurepip

On Windows, use environment\Scripts\python.exe. This pattern is useful for bootstrap tests and minimal images.

User installation

The --user option uses the user site-packages scheme.

python -m ensurepip --user

It is not allowed inside an active virtual environment. The user’s scripts directory may also need to be on PATH. Even then, python -m pip remains more predictable than relying on a global script name.

Install relative to another root

--root DIR installs relative to a supplied root.

python -m ensurepip --root /tmp/python-image

This is aimed at staging, image construction, and distribution packaging. It does not create a virtual environment and may produce paths intended for later installation.

Control installed script names

By default, ensurepip installs scripts such as pipX and pipX.Y, where X.Y matches the Python version.

--default-pip also creates the plain pip command:

python -m ensurepip --default-pip

--altinstall skips pipX. The two options cannot be combined.

Avoid multiple-version confusion

Machines with several Python installations can have scripts pointing to different environments.

python3.12 -m ensurepip --upgrade
python3.12 -m pip --version

On Windows:

py -3.12 -m ensurepip --upgrade
py -3.12 -m pip --version

Record sys.executable in diagnostics.

Read the bundled pip version

ensurepip.version() returns the pip version available for bootstrap.

import ensurepip

print(ensurepip.version())

This may be older than the newest published release. Its job is to provide a functional bundled installer compatible with the CPython release.

Use bootstrap() programmatically

import ensurepip

ensurepip.bootstrap(
    upgrade=True,
    default_pip=True,
    verbosity=1,
)

The function accepts root, upgrade, user, altinstall, default_pip, and verbosity. Setting both script-selection options raises ValueError.

Prefer a subprocess in tools

The programmatic bootstrap temporarily changes sys.path and os.environ. Administrative tools should invoke the CLI in another process.

import subprocess
import sys

subprocess.run(
    [sys.executable, '-m', 'ensurepip', '--upgrade'],
    check=True,
    timeout=120,
)

This isolates side effects and provides an exit code and timeout.

Audit events

Bootstrapping raises the audit event ensurepip.bootstrap with the selected root. Audit hooks may observe or block it.

In managed environments, record who requested bootstrap, which interpreter ran, and where files were installed.

Ensurepip installs only pip

The module bootstraps pip and its immediate bundled components. Use pip afterward for project dependencies.

python -m ensurepip --upgrade
python -m pip install -r requirements.txt

The site’s guide to installing Python packages covers requirements, pinned versions, and virtual environments.

Do not depend on pip’s internal dependencies

The bootstrap may install modules needed by pip, but applications must not assume those packages are always independently available. Pip may change or vendor dependencies differently.

Declare every library your application imports.

Optional availability

Ensurepip is optional in CPython builds and unavailable on Android, iOS, and WASI. Some Linux distributions remove it or provide it through another package.

If the module is missing, use the distribution’s official pip or venv package. Do not copy random files from another installation.

Externally managed Python

Modern operating systems may mark the global environment as externally managed. Installing or upgrading packages globally can break system tools.

python -m venv .venv
.venv/bin/python -m pip install package

For command-line applications, an isolated installer such as pipx may be more appropriate.

Permission errors

A permission error usually means the command is targeting global Python. Do not automatically solve it with sudo pip.

Confirm the destination, use a virtual environment or the user scheme, and build server environments with a dedicated deployment account.

Offline environments

Ensurepip works offline because its components ship with Python. Installing other dependencies still requires local wheels or an internal index.

python -m pip install \
  --no-index \
  --find-links /opt/wheels \
  -r requirements.txt

Verify wheel hashes and provenance. Offline does not automatically mean trusted.

Container images

Use ensurepip in a container only when the base Python lacks pip and the build needs it.

Remove caches and unnecessary build tools from the final image. Multi-stage builds can install dependencies in a separate stage.

Diagnose a broken pip

Check whether the pip module imports.

python -c "import pip; print(pip.__version__)"

If it fails, test ensurepip inside a fresh venv. When the new environment works, recreating the old venv is usually safer than repairing files manually.

Recreate instead of repairing

Virtual environments should be reproducible from dependency files.

rm -rf .venv
python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Use appropriate removal commands on Windows and never commit the venv directory.

Confirm with importlib.metadata

After bootstrap, Python importlib.metadata can report the installed distribution version.

from importlib.metadata import version

print(version('pip'))

This differs from ensurepip.version(), which reports the version bundled for bootstrap.

Test automation safely

Do not test bootstrap against the developer’s global Python. Create a temporary environment and run its interpreter.

import subprocess
import sys

subprocess.run(
    [sys.executable, '-m', 'venv', '--without-pip', 'tmp-venv'],
    check=True,
)
subprocess.run(
    ['tmp-venv/bin/python', '-m', 'ensurepip'],
    check=True,
)

Adapt the executable path for Windows and delete the environment afterward.

Common mistakes

• Using ensurepip to fetch the newest pip.
• Confusing global pip with virtual-environment pip.
• Calling bootstrap in a multithreaded process.
• Combining --altinstall and --default-pip.
• Forcing changes into system Python.
• Assuming ensurepip exists on every platform.
• Depending on modules installed internally for pip.

Best practices

• Use python -m pip.
• Prefer virtual environments.
• Use subprocesses for isolation.
• Confirm the interpreter and destination.
• Respect distributor policies.
• Recreate damaged venvs.
• Pin and verify later dependencies.

Conclusion

Python ensurepip provides an offline, predictable way to install or restore the pip bundled with CPython. It is especially useful for virtual environments created without pip and controlled recovery workflows.

Avoid modifying system Python and do not confuse bootstrap with an online upgrade. Consult the official ensurepip documentation and the PyPA package installation guide.