Pipenv Configuration

This document covers the various ways to configure Pipenv's behavior through environment variables, configuration files, and command-line options.

Environment Variables

Pipenv can be customized through environment variables, which is particularly useful for CI/CD pipelines, team-wide settings, or personal preferences.

Setting Environment Variables

Temporary (Session-Only)

# Unix/Linux/macOS
$ export PIPENV_VENV_IN_PROJECT=1
$ pipenv install

# Windows (Command Prompt)
> set PIPENV_VENV_IN_PROJECT=1
> pipenv install

# Windows (PowerShell)
> $env:PIPENV_VENV_IN_PROJECT=1
> pipenv install

Permanent

For Unix/Linux/macOS, add to your shell profile (e.g., ~/.bashrc, ~/.zshrc):

export PIPENV_VENV_IN_PROJECT=1

For Windows, set through System Properties > Environment Variables.

Boolean Options

To enable boolean options, set the variable to a true value: "1", "true", "yes", or "on".

To disable a boolean option, set it to a false value: "0", "false", "no", or "off".

Available Environment Variables

Virtual Environment

Installation and Dependencies

File Locations

Behavior

Security and Credentials

Runtime Environment Variables

These variables are automatically set by Pipenv when running pipenv run or pipenv shell:

The PIPENV_PROJECT_DIR variable is particularly useful for scripts that need to reference project-relative paths regardless of the current working directory:

# Pipfile
[scripts]
test = "pytest $PIPENV_PROJECT_DIR/tests"
mypy = "mypy --config-file=$PIPENV_PROJECT_DIR/mypy.ini $PIPENV_PROJECT_DIR/src"

Examples

Store virtualenvs in the project directory

export PIPENV_VENV_IN_PROJECT=1

This creates a .venv directory in your project, making it easier to manage and find the virtualenv.

Use a custom Python version by default

export PIPENV_DEFAULT_PYTHON_VERSION=3.10

This sets Python 3.10 as the default when creating new environments.

Skip lock file generation during development

export PIPENV_SKIP_LOCK=1

This speeds up installation during development, but should not be used in production environments.

Use a PyPI mirror

export PIPENV_PYPI_MIRROR=https://mirrors.aliyun.com/pypi/simple/

This is useful in regions where accessing the official PyPI might be slow.

Increase timeout for large packages

export PIPENV_INSTALL_TIMEOUT=1800

This increases the timeout to 30 minutes for installing large packages.

Configuration with pip

Pipenv uses pip under the hood, so you can also use pip's configuration options. These can be set through:

1. Environment variables (e.g., PIP_TIMEOUT, PIP_INDEX_URL)
2. pip configuration files (pip.conf or pip.ini)

Common pip Environment Variables

Examples

Using a private package index

export PIP_INDEX_URL=https://private-repo.example.com/simple
export PIP_TRUSTED_HOST=private-repo.example.com

Passing additional options to pip

export PIP_INSTALL_OPTION="--no-deps"

Combining with Pipenv options

export PIP_INDEX_URL=https://private-repo.example.com/simple
export PIPENV_TIMEOUT=60
pipenv install requests

Project-Specific Configuration

Using .env Files

Pipenv automatically loads environment variables from .env files in your project directory. This is useful for project-specific settings:

# .env file
PIPENV_VENV_IN_PROJECT=1
PIP_INDEX_URL=https://private-repo.example.com/simple

Custom .env Location

You can specify a custom location for your .env file:

export PIPENV_DOTENV_LOCATION=/path/to/custom/.env
pipenv shell

Disabling .env Loading

If you don't want Pipenv to load .env files:

export PIPENV_DONT_LOAD_ENV=1
pipenv shell

Command-Line Options

Many configuration options can also be set directly via command-line arguments, which take precedence over environment variables:

pipenv install --python 3.9 --site-packages

Advanced Configuration

Changing Cache Location

The default cache location is ~/.cache/pipenv on Unix/Linux/macOS and %LOCALAPPDATA%\pipenv\Cache on Windows. You can change this:

export PIPENV_CACHE_DIR=/path/to/custom/cache

This is useful when:

• You have limited space in your home directory
• You want to share the cache across users
• You're working in an environment with restricted permissions

Network Configuration in Restricted Environments

For environments with network restrictions:

# Increase timeout for slow connections
export PIPENV_TIMEOUT=60
export PIP_TIMEOUT=60

# Use a proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# Specify trusted hosts that don't need HTTPS
export PIP_TRUSTED_HOST=internal-repo.example.com

CI/CD Pipeline Configuration

For continuous integration environments:

# Non-interactive mode
export PIPENV_YES=1
export PIPENV_NOSPIN=1
export PIPENV_QUIET=1

# Fail if lock file is out of date
pipenv install --deploy

Development vs. Production Settings

Development

# Development environment
export PIPENV_VENV_IN_PROJECT=1  # Keep virtualenv with project
export PIPENV_MAX_DEPTH=20        # Allow deeper dependency resolution

Production

# Production environment
export PIPENV_IGNORE_PIPFILE=1    # Use only the lock file
export PIPENV_NOSPIN=1            # Disable spinner for cleaner logs
pipenv install --deploy           # Fail if lock file is out of date

Troubleshooting Configuration Issues

Checking Current Configuration

To see what environment variables Pipenv is using:

pipenv --support

This shows all active Pipenv-related environment variables and their values.

Common Configuration Problems

Virtualenv Creation Fails

If virtualenv creation fails, check:

• PIPENV_PYTHON points to a valid Python executable
• You have permissions to write to the virtualenv directory
• PIPENV_VENV_IN_PROJECT=1 if you're in a directory with restricted permissions

Package Installation Timeouts

If package installations time out:

• Increase PIPENV_TIMEOUT and PIPENV_INSTALL_TIMEOUT
• Check network connectivity to PyPI or your custom index
• Consider using a PyPI mirror with PIPENV_PYPI_MIRROR

Lock File Generation Issues

If lock file generation fails:

• Ensure there are no conflicting dependencies
• Try PIPENV_RESOLVE_VCS=0 if you have VCS dependencies causing issues
• Increase PIPENV_MAX_DEPTH for complex dependency trees

Best Practices

1. Version Control: Don't commit environment-specific settings to version control. Use .env files that are excluded via .gitignore.

2. Documentation: Document required environment variables in your project's README.

3. Consistency: Use the same configuration across development, testing, and production environments when possible.

4. Minimal Configuration: Only set the variables you need to change from defaults.

5. Security: Be careful with security-sensitive settings like API keys. Use environment variables rather than committing them to files.