{"id":256,"library":"pip","title":"pip","description":"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.","status":"active","version":"26.0.1","language":"python","source_language":"en","source_url":"https://github.com/pypa/pip","tags":["packaging","installer","pypa","devtools","cli"],"install":[{"cmd":"python -m pip install --upgrade pip","lang":"bash","label":"Upgrade pip (recommended)"},{"cmd":"python -m ensurepip --upgrade","lang":"bash","label":"Bootstrap pip via stdlib (no network)"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import pip; pip.main(['install', 'requests'])","symbol":"pip (CLI invocation)","correct":"import subprocess, sys\nsubprocess.check_call([sys.executable, '-m', 'pip', 'install', 'requests'])"},{"note":"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.","wrong":"import pkg_resources; pkg_resources.get_distribution('requests').version","symbol":"importlib.metadata (inspect installed packages)","correct":"from importlib.metadata import version, packages_distributions\nversion('requests')"}],"quickstart":{"code":"import subprocess\nimport sys\n\n# Correct way to invoke pip programmatically — always use sys.executable\n# so the right interpreter/venv is targeted.\ndef pip_install(*packages):\n    subprocess.check_call(\n        [sys.executable, '-m', 'pip', 'install', *packages],\n    )\n\n# Example: install/upgrade a package\npip_install('requests>=2.31')\n\n# Verify the installed version using importlib.metadata (no pkg_resources)\nfrom importlib.metadata import version\nprint('requests', version('requests'))\n\n# List outdated packages (machine-readable JSON)\nresult = subprocess.run(\n    [sys.executable, '-m', 'pip', 'list', '--outdated', '--format=json'],\n    capture_output=True, text=True, check=True,\n)\nimport json\noutdated = json.loads(result.stdout)\nfor pkg in outdated:\n    print(f\"{pkg['name']} {pkg['version']} -> {pkg['latest_version']}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Use `subprocess.check_call([sys.executable, '-m', 'pip', 'install', ...])` to invoke pip from Python code.","message":"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.","severity":"breaking","affected_versions":"<= 9.x (removed after 9.x)"},{"fix":"Add a pyproject.toml to your project or use --use-pep517 explicitly. Remove any --no-use-pep517 flags from scripts or CI.","message":"setup.py bdist_wheel build mechanism removed. --no-use-pep517 flag is gone. PEP 517 builds are now always used.","severity":"breaking","affected_versions":">=26.0"},{"fix":"Upgrade to Python 3.9+ or pin pip<25.1 for Python 3.8 environments.","message":"Python 3.8 support dropped in pip 25.1. Running pip 25.x+ on Python 3.8 is unsupported.","severity":"breaking","affected_versions":">=25.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=23.0"},{"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.","message":"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+).","severity":"breaking","affected_versions":">=24.3"},{"fix":"Switch to `from importlib.metadata import version, packages_distributions` (stdlib since Python 3.8).","message":"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.","severity":"deprecated","affected_versions":">=25.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T19:20:32.238Z","next_check":"2026-06-25T00:00:00.000Z","problems":[{"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.","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.","error":"pip: command not found"},{"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`.","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.","error":"ERROR: Could not find a version that satisfies the requirement <package_name>"},{"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.","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.","error":"ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied"},{"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.","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.","error":"WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available."},{"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.","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.","error":"ModuleNotFoundError: No module named '<module_name>'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"26.1.1"}