pip

pip Error Classes

Exception classes raised by pip, Python's package installer. Errors subclass PipError and surface during package installation, dependency resolution, network access, and hash verification.

15 codes

references pip.pypa.io/en/stable/github.com/pypa/pip/blob/main/src/pip/_internal/exceptions.py

· All codes 15 codes

CommandError CommandError Raised when a pip command is invoked with incorrect arguments or options. The exception message describes the usage error, such as a missing required argument or a mutually exclusive option combination.
DirectoryUrlHashUnsupported DirectoryUrlHashUnsupported Raised in hash-checking mode when a requirement points to a local directory path. Directory-based installs are not hashable. Use a pre-built wheel or sdist archive to enable hash verification.
HashMismatch HashMismatch Raised when the hash of a downloaded distribution file does not match the expected value specified in the requirements file or index. Ensures integrity of downloaded packages; check the index or requirements file for stale hashes.
InstallationError InstallationError Raised when an error occurs during package installation. This is the general-purpose installation failure; more specific subclasses such as InstallationSubprocessError or HashMismatch are raised when the cause is known.
InstallationSubprocessError InstallationSubprocessError Raised when a subprocess invoked during installation exits with a non-zero status. Common causes include a failing build backend (setuptools, flit, meson-python), a C extension compiler error, or a failing post-install script.
InvalidRequirement InvalidRequirement Raised when a requirement string in requirements.txt or on the command line cannot be parsed as a valid PEP 508 dependency specifier. Common causes include version specifier syntax errors or missing package names.
InvalidWheelFilename InvalidWheelFilename Raised when a wheel file has a name that does not conform to the wheel naming convention (<name>-<version>(-<build>)?-<python>-<abi>-<platform>.whl). The filename encodes compatibility tags that pip uses for platform matching.
MetadataInconsistent MetadataInconsistent Raised when the metadata in a built wheel is inconsistent with what was requested — for example the name or version in METADATA does not match the wheel filename. Often indicates a broken or misconfigured build backend.
NetworkConnectionError NetworkConnectionError Raised when pip cannot establish a connection to the package index or a download URL. Commonly caused by no internet access, a corporate proxy, DNS failures, or an unreachable private index.
NoneMetadataError NoneMetadataError Raised when a distribution package has None as the value of a required metadata attribute. Usually indicates a corrupt or incomplete installation in the site-packages directory.
PipError PipError Base exception class for all pip errors. All other pip exceptions inherit from this class, so catching PipError catches any pip-specific failure.
UninstallationError UninstallationError Raised when an error occurs during package uninstallation. Typically means the package was not found in the environment or its installed-files record is missing or corrupt.
UnsupportedWheel UnsupportedWheel Raised when a wheel file is structurally valid but cannot be installed because it targets a different Python version, ABI, or platform than the current environment.
UserInstallationInvalid UserInstallationInvalid Raised when pip is asked to install into the user site-packages directory (--user) but the user site directory is disabled or unusable in the current environment, such as inside a virtual environment.
VcsHashUnsupported VcsHashUnsupported Raised in hash-checking mode when a requirement points to a VCS source URL (git+, svn+, hg+, bzr+). Version control checkouts cannot be hashed because their content can change. Pin to a fixed commit or use a release archive instead.