pip

26.0.1 verified Tue May 12 auth: no python

pip is the PyPA-recommended package installer for Python. It installs packages from the Python Package Index (PyPI) and other indexes, supporting wheels, source distributions, VCS URLs, and local paths. Current version is 26.0.1 (bundled with CPython via ensurepip). Releases follow a roughly quarterly cadence aligned with CPython releases. pip is primarily a CLI tool; it intentionally exposes no stable programmatic Python API.

Common errors

error pip: command not found ↓

cause The 'pip' executable is either not installed or its directory is not included in the system's PATH environment variable, preventing the shell from locating the command. This also manifests as "'pip' is not recognized as an internal or external command" on Windows.

fix

Ensure Python was installed with pip (check the 'Add Python to PATH' option during Windows installation). If Python is installed, try running python -m ensurepip --upgrade to install/upgrade pip. Otherwise, use python -m pip <command> (or python3 -m pip <command>) to explicitly call pip via the Python interpreter.

error ERROR: Could not find a version that satisfies the requirement <package_name> ↓

cause The specified package name might be misspelled, the package may not exist on PyPI, the requested version is unavailable, or the package is incompatible with your current Python version or operating system.

fix

Double-check the package name and its spelling on pypi.org. Try installing without a specific version constraint (pip install <package_name>). Ensure your Python version meets the package's requirements. Upgrade pip to its latest version: python -m pip install --upgrade pip.

error ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied ↓

cause Pip is attempting to install packages into a system-wide directory that requires administrator or root privileges, but the current user does not have the necessary permissions.

fix

Install the package into your user directory: pip install --user <package_name>. Alternatively, use a virtual environment (python -m venv .venv then source .venv/bin/activate) to create an isolated, user-writable installation space. On Linux/macOS, sudo pip install <package_name> can force installation, but --user or virtual environments are generally safer and recommended.

error WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available. ↓

cause Your Python interpreter was built or installed without SSL (Secure Sockets Layer) support, meaning pip cannot securely connect to HTTPS-based package indexes like PyPI to download packages.

fix

Reinstall Python from a reliable source (e.g., the official python.org installer) that bundles SSL support. If you compiled Python from source, ensure OpenSSL development libraries (like openssl-devel or libssl-dev) were installed on your system *before* compiling Python.

error ModuleNotFoundError: No module named '<module_name>' ↓

cause Although a package might have been successfully installed using pip, the Python interpreter running your code cannot find it. This often happens due to multiple Python installations, incorrect virtual environment activation, or an IDE/editor configured to use a different Python interpreter than where the package was installed.

fix

Verify that the correct Python interpreter is active and that your IDE/editor is configured to use it. If using a virtual environment, ensure it is activated (source venv/bin/activate). Always use python -m pip install <package_name> to ensure pip installs into the environment associated with the currently active Python interpreter.

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.

gotcha Shell command failed with 'command not found' or 'invalid argument' error. This indicates that the command being executed either does not exist in the system's PATH, or was invoked with incorrect or unrecognized arguments, causing the shell to report that a component (like '-q') could not be found or executed as a command. ↓

fix Review the script or command being executed for typos. Ensure that all necessary tools and commands are installed and available in the system's PATH. Verify that all arguments passed to the command are valid and correctly formatted for the specific shell and command being used.

gotcha A shell command executed during the test failed with an 'unknown option' error (e.g., 'sh: -q: not found'). This indicates an issue with the shell or script executing commands, rather than a pip-specific problem. ↓

fix Examine the test runner's configuration, CI/CD scripts, or any pre- or post-install scripts that invoke shell commands. Ensure that all shell options and commands are valid for the specific shell environment where the tests are being run.

Install

python -m pip install --upgrade pip

python -m ensurepip --upgrade

Imports

pip (CLI invocation)
wrong
```
import pip; pip.main(['install', 'requests'])
```
correct
```
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)
wrong
```
import pkg_resources; pkg_resources.get_distribution('requests').version
```
correct
```
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']}")