docs/diagnose.md
This guide provides comprehensive information on diagnosing and resolving common issues with Pipenv, including detailed troubleshooting steps, diagnostic commands, and best practices.
Pipenv includes several built-in tools to help diagnose issues with your environment and dependencies.
--support FlagThe --support flag generates diagnostic information that can be helpful when reporting issues:
$ pipenv --support
This command outputs:
Include this output when filing issues on GitHub to help maintainers understand your environment.
For more detailed output during Pipenv operations, use the verbose flag:
$ pipenv install --verbose
This shows detailed information about what Pipenv is doing, which can help identify where issues are occurring.
For even more detailed debugging information, set the PIPENV_DEBUG environment variable:
$ PIPENV_DEBUG=1 pipenv install
This enables debug-level logging, showing internal operations that can help diagnose complex issues.
If Pipenv can't resolve your dependencies, try clearing the resolver cache:
$ pipenv lock --clear
If that doesn't work, try manually deleting the cache directory:
~/.cache/pipenv%LOCALAPPDATA%\pipenv\pipenv\Cache~/Library/Caches/pipenvBy default, Pipenv doesn't install pre-release versions. To enable them:
# Command line flag
$ pipenv install --pre package-name
# Or in Pipfile
# [pipenv]
# allow_prereleases = true
If you have conflicting dependencies:
pipenv graph to visualize your dependency treeIf you get "No module named X" errors:
Verify the package is installed:
$ pipenv graph | grep package-name
Check if you're running the command within the Pipenv environment:
$ pipenv run python -c "import package_name"
Ensure you're not mixing system packages with Pipenv:
$ pipenv --rm # Remove the virtual environment
$ pipenv install # Recreate it
If Pipenv can't find the specified Python version:
Check available Python versions:
# If using pyenv
$ pyenv versions
# If using asdf
$ asdf list python
Install the required version:
# With pyenv
$ pyenv install 3.10.4
# With asdf
$ asdf install python 3.10.4
Specify the Python version explicitly:
$ pipenv --python 3.10
Pipenv by default uses the Python it was installed against. To use your current pyenv interpreter:
$ pipenv --python $(pyenv which python)
This is a common issue on macOS due to a bug in locale detection:
# Add to your shell configuration file (~/.bashrc, ~/.zshrc, etc.)
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
You can change both the en_US and UTF-8 parts to match your preferred language and encoding.
This may be related to locale settings. Apply the same fix as above.
If your lock file is out of date:
$ pipenv lock
If an exception occurs during locking:
$ pipenv lock --clear
This clears the cache and forces a fresh resolution of all dependencies.
If you encounter hash verification failures:
Update your lock file:
$ pipenv lock
If that doesn't work, try installing with:
$ pipenv install --ignore-pipfile
If you're still having issues, check for network problems or proxy settings that might be interfering with downloads.
If Pipenv can't find your virtual environment:
Check if it exists:
$ pipenv --venv
If it doesn't exist, create it:
$ pipenv install
If you've moved or renamed your project, remove the old environment and create a new one:
$ pipenv --rm
$ pipenv install
If pipenv shell doesn't work correctly:
Try compatibility mode (the default):
$ pipenv shell
If that doesn't work, try fancy mode:
$ pipenv shell --fancy
If neither works, use pipenv run instead:
$ pipenv run python
If a package can't be found:
$ pipenv install package-name --verbose
If you're having authentication issues with private repositories:
For complex dependency resolution issues:
$ PIPENV_RESOLVER_DEBUG=1 pipenv install
This shows detailed information about the dependency resolution process, including which packages are being considered and why certain versions are being selected or rejected.
To understand what changed in your lock file:
$ git diff Pipfile.lock
Look for:
To inspect the packages installed in your virtual environment:
# List all installed packages
$ pipenv run pip list
# Show details for a specific package
$ pipenv run pip show package-name
# Check for outdated packages
$ pipenv update --outdated
To identify conflicting dependencies:
# Show the dependency graph
$ pipenv graph
# Show reverse dependencies (what depends on a package)
$ pipenv graph --reverse
Look for packages that appear multiple times with different version constraints.
If you suspect path or environment issues:
# Show the Python interpreter path
$ pipenv --py
# Show environment variables
$ pipenv --envs
# Run a command with verbose output
$ PIPENV_VERBOSE=1 pipenv run python -c "import sys; print(sys.path)"
Perform regular maintenance to prevent issues:
Keep Pipenv updated:
$ pip install --user --upgrade pipenv
Regularly update dependencies:
$ pipenv update
Scan for security vulnerabilities:
$ pipenv scan
--deploy flag in production environments$ pipenv clean
When reporting issues to the Pipenv maintainers:
Include the --support output:
$ pipenv --support
Provide a minimal reproducible example:
Include relevant logs:
--verbose or PIPENV_DEBUG=1Specify your environment:
Diagnosing issues with Pipenv often involves understanding the underlying dependency resolution process, virtual environment management, and Python environment configuration. By using the diagnostic tools and following the troubleshooting steps in this guide, you can resolve most common Pipenv issues.
Remember that Pipenv is a tool that combines pip, virtualenv, and Pipfile to simplify Python dependency management. Understanding how these components interact can help you diagnose and resolve issues more effectively.
If you encounter persistent issues that aren't covered in this guide, consider reaching out to the Pipenv community through: