pip-debug

Show general debug information

$ pip debug

$ pip debug --platform [platform]

$ pip debug --python-version [version]

$ pip debug --implementation [implementation]

$ pip debug --abi [abi]

pip debug [global_options]

--verbose
    Increases the verbosity of output, showing more detailed information relevant for deep debugging.

--no-color
    Suppresses colored output, which can be useful for scripting or when redirecting output to plain text files.

--log <path>
    Specifies a file path where `pip` logging information, including debug details, will be written.

--isolated
    Runs `pip` in an isolated mode, ignoring environment variables and user configuration files. Useful for debugging interaction with a clean environment.

--disable-pip-version-check
    Disables the periodic check for a new version of `pip` on PyPI, which can prevent network calls during debugging.

The `pip debug` command is a vital subcommand of `pip`, the standard package installer for Python. It provides a comprehensive diagnostic overview of the Python environment in which `pip` is currently operating. This includes crucial details like the Python version, operating system information, `pip` version, location of configuration files (`pip.conf` or `pip.ini`), and relevant environment variables. Its primary purpose is to assist developers and users in troubleshooting issues related to package installation, dependency resolution, or general `pip` configuration problems. By consolidating disparate pieces of information into a single, structured output, `pip debug` significantly streamlines the process of identifying common misconfigurations, version incompatibilities, or incorrect environment setups without requiring manual inspection of numerous system paths and files.

The output of `pip debug` is specific to the Python environment (e.g., virtual environment) in which it is executed. Running it in different environments will show different details.
It's a diagnostic tool and does not modify any system or `pip` configuration. The output can be quite detailed, so consider piping it to a pager like `less` or redirecting it to a file for easier analysis.

The output of `pip debug` is typically structured into several sections, providing details such as Python and `pip` versions, operating system, filesystem encoding, virtual environment status, relevant environment variables, configuration files (`pip.ini` or `pip.conf`), and package index information. This structured output helps in quickly pinpointing the source of configuration or environment-related problems.

While `pip debug` provides a good overview by default, using the global `--verbose` option (e.g., `pip --verbose debug`) can further enhance the output with even more detailed information. This might include the full paths searched for configuration files, or more extensive environment variable dumps, which can be crucial for deep-dive diagnostics when default output isn't sufficient.

The `debug` subcommand was introduced in `pip` version 20.3 (released in late 2020). Prior to its introduction, users had to manually gather various pieces of environment and configuration information, often leading to incomplete or inconsistent debugging data. The `debug` command consolidates this information into a single, structured output, significantly streamlining the troubleshooting process for `pip` and Python environment-related issues.

pip(1): The main pip command for package management., python(1): The Python interpreter itself., pip config(1): For managing local and global pip configurations., pip show(1): Display information about installed packages., pip list(1): List installed packages in the current environment.