pip

Common errors

• 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: 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: 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.

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

• 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 Upgrade pip (recommended)
• python -m ensurepip --upgrade Bootstrap pip via stdlib (no network)

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']}")