Articles

pip Verbose Logging: Debug Install Failures (2026)

April 18, 2026 5 min read

pip’s verbose logging is your best friend when pip install decides to throw a tantrum. It’s not just about seeing more output; it’s about seeing the right output that points to the exact moment and reason a package installation went south.

Let’s say you’re trying to install a package, and it just hangs or fails with a cryptic error message. The first thing you’ll want to do is rerun that pip install command with the -v (verbose) flag.

pip install --verbose some_package

If that’s not enough, you can crank it up to eleven with -vv, -vvv, or even -vvvv. Each additional v reveals more of pip’s internal monologue.

pip install -vvv some_package

This level of detail is crucial because pip interacts with many external systems during an install: network sockets to download packages, file system operations to unpack and place them, and sometimes even external build tools or compilers. When something breaks, it’s usually one of these interactions that fails.

Common Failure Points and How to Diagnose Them

  1. Network Connectivity/Proxy Issues:

    • Diagnosis: Look for lines like GET /simple/some_package/ or Connection to pypi.org timed out. If you see HTTP/1.1 407 Proxy Authentication Required, your proxy needs credentials.
    • Fix: If a proxy is required, set the HTTP_PROXY and HTTPS_PROXY environment variables:
      export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080"
pip install some_package
      This tells pip how to route its HTTP/HTTPS requests through your proxy.
    • Why it works: pip uses these environment variables to construct the correct proxy URLs, allowing it to reach PyPI and other package indexes.

  2. Package Index (PyPI) Unavailability or DNS Resolution Failure:

    • Diagnosis: Errors like Could not find a version that satisfies the requirement some_package or Non-interactive prompt on a tty (hide this warning and allow fake interaction!) when pip can’t reach the index. More critically, you might see Name or service not known or [Errno -2] Name or service not known if DNS is failing.
    • Fix: Ensure your DNS is working and that pypi.org (or your custom index) is reachable. Try ping pypi.org or dig pypi.org. If you’re using a custom index, verify its URL and accessibility. If you suspect an issue with pip’s default index, you can explicitly point to it:
      pip install --index-url https://pypi.org/simple/ some_package
    • Why it works: Explicitly specifying the index URL bypasses any potential misconfiguration in pip’s default settings and ensures it’s attempting to connect to the correct, known-good location.

  3. SSL/TLS Certificate Verification Errors:

    • Diagnosis: Look for SSL: CERTIFICATE_VERIFY_FAILED or _ssl.c:3030: error:14090086:SSL routines:ssl3_get_server_certificate:certificate verify failed. This often happens when pip cannot verify the SSL certificate of the package index server.
    • Fix: The most secure way is to ensure your system’s CA certificates are up-to-date. On macOS, this might involve running Install Certificates.command in your Python installation’s SharedFrameworks directory. On Linux, ensure your ca-certificates package is updated (sudo apt update && sudo apt install ca-certificates on Debian/Ubuntu). If you absolutely must bypass this (not recommended for general use), you can use --trusted-host pypi.org (or your index host), but this weakens security by disabling certificate checks for that host:
      pip install --trusted-host pypi.org some_package
    • Why it works: Updating CA certificates allows pip to correctly validate the identity of the server it’s connecting to. Using --trusted-host tells pip to skip this validation step, which can be a temporary workaround but leaves you vulnerable to man-in-the-middle attacks.

  4. Build Dependencies Missing (for packages with C extensions):

    • Diagnosis: Errors mentioning gcc, clang, make, build_err, or command 'gcc' failed. You’ll see output from the compiler or build system failing. For example, fatal error: Python.h: No such file or directory indicates the Python development headers are missing.
    • Fix: Install the necessary build tools and development headers for your operating system.
      • Debian/Ubuntu: sudo apt update && sudo apt install python3-dev build-essential
      • Fedora/CentOS/RHEL: sudo dnf groupinstall "Development Tools" and sudo dnf install python3-devel
      • macOS: Install Xcode Command Line Tools: xcode-select --install
      • Windows: Install the Microsoft C++ Build Tools from Visual Studio or the Visual Studio Build Tools installer. Ensure you select the "Desktop development with C++" workload.
    • Why it works: These packages provide the compilers (like GCC or Clang), linkers, and header files (like Python.h) that pip’s build process needs to compile C/C++ extensions into Python modules.

  5. Permissions Issues:

    • Diagnosis: Errors like Permission denied: '/usr/local/lib/python3.9/site-packages/some_package' or Could not install package because of OS interference during file writing operations.
    • Fix: The recommended fix is to install into a user-specific location using the --user flag, which avoids needing root privileges:
      pip install --user some_package
      If you need to install system-wide and lack permissions, use sudo (though this is generally discouraged for package management):
      sudo pip install some_package
    • Why it works: The --user flag installs packages into your home directory (e.g., ~/.local/lib/pythonX.Y/site-packages), where you have write permissions. sudo elevates your privileges to root, allowing writes to system directories.

  6. Conflicts with Existing Packages or Version Specifiers:

    • Diagnosis: ERROR: Cannot install some_package because these package versions have conflicting dependencies. The conflict is caused by: some_package 1.0 depends on dependency_a<2.0, but dependency_a 2.0 is already installed. Verbose logs will show pip attempting to resolve dependencies and hitting a wall.
    • Fix: Carefully examine the conflict message. You might need to:
      • Install a specific version of some_package that is compatible with your existing dependencies: pip install "some_package==1.5.2"
      • Upgrade or downgrade the conflicting dependency: pip install "dependency_a<2.0"
      • Use a virtual environment (venv or conda) to isolate your project’s dependencies and avoid system-wide conflicts.
    • Why it works: Virtual environments create self-contained Python installations, preventing package version clashes between different projects or with system-level packages. Explicitly specifying versions or ranges allows pip to find a compatible set of packages.

After fixing these, the next error you might encounter could be related to a package’s post-installation script failing, often due to environment-specific configurations or missing runtime dependencies.

Want structured learning?

Take the full Pip course →