Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pip (CLI invocation)
✓ import subprocess, sys
subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'requests'])
✗ import pip; pip.main(['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')
✗ import pkg_resources; pkg_resources.get_distribution('requests').version
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.
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']}")
pip --version
Debug
Known issues
breakingpip.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.fixUse `subprocess.check_call([sys.executable, '-m', 'pip', 'install', ...])` to invoke pip from Python code.
affects: <= 9.x (removed after 9.x)
breakingsetup.py bdist_wheel build mechanism removed. --no-use-pep517 flag is gone. PEP 517 builds are now always used.fixAdd a pyproject.toml to your project or use --use-pep517 explicitly. Remove any --no-use-pep517 flags from scripts or CI.
affects: >=26.0
breakingPython 3.8 support dropped in pip 25.1. Running pip 25.x+ on Python 3.8 is unsupported.fixUpgrade to Python 3.9+ or pin pip<25.1 for Python 3.8 environments.
affects: >=25.1
breakingPEP 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.fixAlways 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.
affects: >=23.0
breakingPre-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+).fixReplace 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.
affects: >=24.3
deprecatedUsing 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.fixSwitch to `from importlib.metadata import version, packages_distributions` (stdlib since Python 3.8).
affects: >=25.0
gotchaRunning `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.fixAlways 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.
affects: all
gotchaShell 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.fixReview 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.
affects: all
gotchaA 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.fixExamine 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.
affects: all
Errors
Common errors & fixes
pip: command not found
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.
fixEnsure 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>
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.
fixDouble-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
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.
fixInstall 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.
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.
fixReinstall 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>'
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.
fixVerify 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.
Upgrade
Version history
26.2.1latest on PyPI · released Aug 4, 2026
Audit
Dependencies
No dependency data recorded yet.