pip

Warnings

• breaking pip.main() was removed years ago and is not a supported API. Calling `import pip; pip.main(...)` will raise AttributeError. pip intentionally exposes no stable programmatic Python API.
  Fix: Use `subprocess.check_call([sys.executable, '-m', 'pip', 'install', ...])` to invoke pip from Python code.
• breaking setup.py bdist_wheel build mechanism removed. --no-use-pep517 flag is gone. PEP 517 builds are now always used.
  Fix: Add a pyproject.toml to your project or use --use-pep517 explicitly. Remove any --no-use-pep517 flags from scripts or CI.
• breaking Python 3.8 support dropped in pip 25.1. Running pip 25.x+ on Python 3.8 is unsupported.
  Fix: Upgrade to Python 3.9+ or pin pip<25.1 for Python 3.8 environments.
• breaking PEP 668 'externally managed environment' error blocks pip install on modern Debian/Ubuntu/Homebrew system Pythons. pip refuses to modify OS-managed site-packages by default.
  Fix: Always work inside a virtual environment (`python -m venv .venv`). For disposable containers only, pass --break-system-packages. Never delete the EXTERNALLY-MANAGED marker file on production systems.
• breaking Pre-release specifier semantics changed. Using `<2.0dev` or `>1.0a1` in version specifiers now implies accepting pre-releases for that range (packaging 24.2 behaviour, shipped in pip 24.3+).
  Fix: Replace pre-release version strings in `<`/`>` specifiers with final release strings (e.g. use `<2.0` instead of `<2.0dev`) to avoid unintentionally pulling pre-releases.
• deprecated Using pkg_resources to inspect installed packages is deprecated. pip 25.x emits a warning when the pkg_resources metadata backend is active, and on Python 3.14+ it cannot be used at all.
  Fix: Switch to `from importlib.metadata import version, packages_distributions` (stdlib since Python 3.8).
• gotcha Running `pip install` without an active virtual environment installs into the global or user site-packages, causing version conflicts across projects and potential breakage of system tools.
  Fix: Always activate a virtual environment before running pip install. Use `python -m venv .venv && source .venv/bin/activate` (Unix) or `.venv\Scripts\activate` (Windows) before installing.

Install

• python -m pip install --upgrade pip Upgrade pip (recommended)
• python -m ensurepip --upgrade Bootstrap pip via stdlib (no network)

Imports

• pip (CLI invocation)

  import subprocess, sys
  subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'requests'])

  pip.main() was removed; there is no supported public Python API. The correct pattern is to invoke pip as a subprocess using the current interpreter's sys.executable.
• importlib.metadata (inspect installed packages)

  from importlib.metadata import version, packages_distributions
  version('requests')

  pkg_resources is deprecated for inspecting installed packages. Use importlib.metadata (stdlib since Python 3.8) instead. pip 25.x emits a warning when the pkg_resources backend is active.

Quickstart

Correct programmatic usage of pip via subprocess. pip has no supported public Python API; always call it through sys.executable to target the active interpreter or venv.

import subprocess
import sys

# Correct way to invoke pip programmatically — always use sys.executable
# so the right interpreter/venv is targeted.
def pip_install(*packages):
    subprocess.check_call(
        [sys.executable, '-m', 'pip', 'install', *packages],
    )

# Example: install/upgrade a package
pip_install('requests>=2.31')

# Verify the installed version using importlib.metadata (no pkg_resources)
from importlib.metadata import version
print('requests', version('requests'))

# List outdated packages (machine-readable JSON)
result = subprocess.run(
    [sys.executable, '-m', 'pip', 'list', '--outdated', '--format=json'],
    capture_output=True, text=True, check=True,
)
import json
outdated = json.loads(result.stdout)
for pkg in outdated:
    print(f"{pkg['name']} {pkg['version']} -> {pkg['latest_version']}")