Published on

Pipenv Cheat Sheet

Table of Contents

What is Pipenv?

Pipenv is a production-ready tool that brings the best of all packaging worlds (bundled dependencies, development packages, deterministic builds, and security) to the Python ecosystem. It automatically creates and manages a virtual environment for your projects, while adding and removing packages from your Pipfile as you install or uninstall them.

The Problem Pipenv Solves

Traditional Python dependency management involves juggling multiple tools:

  • pip for installing packages
  • virtualenv for creating isolated environments
  • requirements.txt for tracking dependencies
  • Manual version pinning for reproducibility
  • No distinction between production and development dependencies

Pipenv consolidates all of this into a single, elegant workflow.

Key Features

FeatureDescription
Automatic Virtual EnvironmentsCreates and manages project-specific environments automatically
PipfileModern, declarative dependency specification (replaces requirements.txt)
Pipfile.lockDeterministic builds with cryptographic hashes for security
Dev DependenciesSeparate development and production dependencies
Security ScanningBuilt-in vulnerability checking with pipenv check
Dependency GraphVisualize dependency relationships with pipenv graph
Python Version ManagementSpecify and enforce Python versions per project
Environment VariablesAutomatic .env file loading for configuration

Installation

Install Pipenv Globally

# Using pip (recommended)
pip install pipenv

# Using pip3 (if pip points to Python 2)
pip3 install pipenv

# Using Homebrew (macOS)
brew install pipenv

# Using apt (Ubuntu/Debian)
sudo apt install pipenv

# Using dnf (Fedora)
sudo dnf install pipenv

Verify Installation

pipenv --version
# Output: pipenv, version 2023.x.x

Upgrade Pipenv

pip install --upgrade pipenv

Quick Start Guide

1. Create a New Project

# Create project directory
mkdir myproject
cd myproject

# Initialize Pipenv environment
pipenv install

# This creates:
# - Pipfile (dependency list)
# - Virtual environment (stored globally by default)

2. Specify Python Version

# Use specific Python version
pipenv --python 3.11

# Use system Python 3
pipenv --python 3

# Use absolute path
pipenv --python /usr/bin/python3.11

3. Install Your First Package

# Install a package
pipenv install requests

# Your Pipfile now contains:
# [packages]
# requests = "*"

4. Activate the Virtual Environment

# Activate shell
pipenv shell

# Your prompt changes to:
# (myproject) user@host:~/myproject$

# Deactivate (when done)
exit

Essential Commands

Project Initialization

# Initialize new project with default Python
pipenv install

# Initialize with specific Python version
pipenv --python 3.11

# Initialize from existing requirements.txt
pipenv install -r requirements.txt

# Create environment but don't install packages
pipenv --python 3.11 --skip-lock

Installing Packages

# Install a package
pipenv install requests

# Install specific version
pipenv install requests==2.28.0

# Install with version constraint
pipenv install "requests>=2.28.0,<3.0.0"

# Install latest compatible version
pipenv install requests~=2.28.0  # Installs 2.28.x but not 2.29.0

# Install from Git repository
pipenv install git+https://github.com/user/repo.git@branch

# Install from Git with egg name
pipenv install -e git+https://github.com/user/repo.git#egg=package

# Install multiple packages
pipenv install requests pandas numpy

# Install all dependencies from Pipfile
pipenv install

# Install all including dev dependencies
pipenv install --dev

Development Dependencies

Development dependencies are packages you need during development but not in production (e.g., testing tools, linters, formatters).

# Install as dev dependency
pipenv install --dev pytest

# Install multiple dev packages
pipenv install --dev pytest black pylint mypy

# Install only production dependencies
pipenv install --ignore-pipfile

# Install only dev dependencies (useful for CI/CD)
pipenv install --dev --system

Example Pipfile with dev dependencies:

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
django = ">=4.0.0"
psycopg2-binary = "*"
gunicorn = "*"

[dev-packages]
pytest = "*"
pytest-django = "*"
black = "*"
pylint = "*"
faker = "*"

[requires]
python_version = "3.11"

Updating Packages

# Update a specific package
pipenv update requests

# Update all packages
pipenv update

# Update and prune (remove unused packages)
pipenv update --prune

# Update only dev packages
pipenv update --dev

# Dry run (see what would be updated)
pipenv update --dry-run

Uninstalling Packages

# Uninstall a package
pipenv uninstall requests

# Uninstall multiple packages
pipenv uninstall requests pandas numpy

# Uninstall all packages
pipenv uninstall --all

# Uninstall all dev packages
pipenv uninstall --all-dev

Viewing Dependencies

# Show dependency graph
pipenv graph

# Show reverse dependency tree
pipenv graph --reverse

# Show only top-level dependencies
pipenv graph --bare

# List installed packages (simple format)
pipenv run pip list

# Show outdated packages
pipenv update --outdated

Example pipenv graph output:

requests==2.28.2
  - certifi [required: >=2017.4.17, installed: 2022.12.7]
  - charset-normalizer [required: >=2,<4, installed: 3.1.0]
  - idna [required: >=2.5,<4, installed: 3.4]
  - urllib3 [required: >=1.21.1,<1.27, installed: 1.26.15]

Locking Dependencies

# Generate/update Pipfile.lock
pipenv lock

# Lock and update all packages to latest versions
pipenv lock --update

# Lock with verbose output
pipenv lock --verbose

# Lock without installing
pipenv lock --keep-outdated

# Clear cache before locking (fixes issues)
pipenv lock --clear

Running Commands

# Run Python script without activating shell
pipenv run python script.py

# Run Python command
pipenv run python -c "print('Hello World')"

# Run any command in the virtual environment
pipenv run pytest
pipenv run black .
pipenv run python manage.py runserver

# Run with custom scripts (defined in Pipfile)
pipenv run server

Virtual Environment Management

# Show virtual environment path
pipenv --venv

# Show project directory path
pipenv --where

# Show Python interpreter path
pipenv --py

# Activate shell
pipenv shell

# Remove virtual environment
pipenv --rm

# Remove virtual environment and delete Pipfile.lock
pipenv --rm && rm Pipfile.lock

Security and Maintenance

# Check for security vulnerabilities
pipenv check

# Check with detailed output
pipenv check --system

# Clean up unused dependencies
pipenv clean

# Verify Pipfile.lock is up to date
pipenv verify

# Show environment information
pipenv --support

Example pipenv check output:

Checking PEP 508 requirements...
Passed!
Checking installed package safety...

  ██████████████████████████████████████████ 40478/4047800:00:03
All good!

Advanced Usage

Custom Scripts in Pipfile

Define custom commands in your Pipfile:

[scripts]
server = "python manage.py runserver"
test = "pytest tests/ -v"
lint = "black . && pylint src/"
format = "black ."
migrate = "python manage.py migrate"
shell = "python manage.py shell"

Run scripts with:

pipenv run server
pipenv run test
pipenv run lint

Environment Variables (.env)

Pipenv automatically loads .env files when you run pipenv shell or pipenv run.

Create .env file:

# .env
DEBUG=True
SECRET_KEY=your-secret-key-here
DATABASE_URL=postgresql://localhost/mydb
API_KEY=abc123xyz
ENVIRONMENT=development

Access in Python:

import os

debug = os.getenv('DEBUG', 'False') == 'True'
secret_key = os.getenv('SECRET_KEY')
db_url = os.getenv('DATABASE_URL')

print(f"Debug mode: {debug}")

Important: Add .env to .gitignore to avoid committing secrets!

# .gitignore
.env
.env.local
.env.*.local

Specify Python Version

# In Pipfile
[requires]
python_version = "3.11"  # Exact version: 3.11.x
python_full_version = "3.11.5"  # Exact full version

To change Python version:

# Remove old environment
pipenv --rm

# Create new with different version
pipenv --python 3.10

# Reinstall packages
pipenv install

Working with Private Package Indexes

# In Pipfile
[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[[source]]
url = "https://private.pypi.company.com/simple"
verify_ssl = true
name = "private"

[packages]
requests = "*"
company-package = {version = "*", index = "private"}

Installing Editable Packages

Useful for developing packages locally:

# Install local package in editable mode
pipenv install -e .

# Install from local path
pipenv install -e /path/to/package

# Install from Git in editable mode
pipenv install -e git+https://github.com/user/repo.git#egg=package

In Pipfile:

[packages]
mypackage = {editable = true, path = "."}

Deployment Best Practices

1. Generate Deterministic Lock File

# Before deployment, ensure lock file is up to date
pipenv lock

2. Install from Lock File (Production)

# Install exactly what's in Pipfile.lock
pipenv sync

# Install only production dependencies (no dev)
pipenv sync --ignore-pipfile

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

3. Install System-Wide (Docker/CI)

# Install to system Python (not in virtual env)
pipenv install --system

# Production deployment
pipenv install --system --deploy --ignore-pipfile

4. Export to requirements.txt (Legacy Systems)

# Export production dependencies
pipenv requirements > requirements.txt

# Export dev dependencies
pipenv requirements --dev > requirements-dev.txt

# Export with hashes (more secure)
pipenv requirements --hash > requirements.txt

Docker Integration

Example Dockerfile:

FROM python:3.11-slim

# Set working directory
WORKDIR /app

# Install pipenv
RUN pip install pipenv

# Copy Pipfile and Pipfile.lock
COPY Pipfile Pipfile.lock ./

# Install dependencies system-wide
RUN pipenv install --system --deploy --ignore-pipfile

# Copy application
COPY . .

# Run application
CMD ["python", "app.py"]

Optimized Multi-stage Dockerfile:

# Build stage
FROM python:3.11-slim AS builder

WORKDIR /app

# Install pipenv
RUN pip install pipenv

# Copy dependency files
COPY Pipfile Pipfile.lock ./

# Install to local directory
RUN PIPENV_VENV_IN_PROJECT=1 pipenv install --deploy

# Runtime stage
FROM python:3.11-slim

WORKDIR /app

# Copy virtual environment from builder
COPY --from=builder /app/.venv ./.venv

# Copy application
COPY . .

# Use virtual environment
ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "app.py"]

CI/CD Integration

GitHub Actions Example

name: Python Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install pipenv
        run: pip install pipenv

      - name: Install dependencies
        run: pipenv install --dev --deploy

      - name: Run tests
        run: pipenv run pytest

      - name: Check security
        run: pipenv check

      - name: Lint code
        run: pipenv run black --check .

GitLab CI Example

# .gitlab-ci.yml
image: python:3.11

before_script:
  - pip install pipenv
  - pipenv install --dev --deploy

test:
  script:
    - pipenv run pytest --cov=src tests/
    - pipenv check

lint:
  script:
    - pipenv run black --check .
    - pipenv run pylint src/

build:
  script:
    - pipenv lock --requirements > requirements.txt
  artifacts:
    paths:
      - requirements.txt

Common Workflows

Starting a New Project

# 1. Create project directory
mkdir myproject && cd myproject

# 2. Initialize git
git init

# 3. Create .gitignore
echo ".env" >> .gitignore
echo "*.pyc" >> .gitignore

# 4. Initialize Pipenv
pipenv --python 3.11

# 5. Install packages
pipenv install django psycopg2-binary
pipenv install --dev pytest black

# 6. Create Django project
pipenv run django-admin startproject config .

# 7. Create .env file
echo "DEBUG=True" > .env
echo "SECRET_KEY=change-me" >> .env

# 8. Commit
git add Pipfile Pipfile.lock .gitignore
git commit -m "Initial commit with Pipenv setup"

Cloning an Existing Project

# 1. Clone repository
git clone https://github.com/user/project.git
cd project

# 2. Install dependencies
pipenv install --dev

# 3. Copy environment template
cp .env.example .env

# 4. Edit .env with your settings
vim .env

# 5. Activate shell
pipenv shell

# 6. Run migrations (Django example)
python manage.py migrate

# 7. Start development server
python manage.py runserver

Updating Dependencies

# 1. Check for outdated packages
pipenv update --outdated

# Output example:
# Package      Current  Latest
# ───────────────────────────────
# requests     2.28.0   2.31.0
# django       4.1.0    4.2.5

# 2. Update specific package
pipenv update requests

# 3. Update all packages
pipenv update

# 4. Lock new versions
pipenv lock

# 5. Test your application
pipenv run pytest

# 6. Commit changes
git add Pipfile Pipfile.lock
git commit -m "Update dependencies"

Adding a New Dependency

# 1. Install package
pipenv install pandas

# 2. Verify it works
pipenv run python -c "import pandas; print(pandas.__version__)"

# 3. Lock dependencies
pipenv lock

# 4. Commit
git add Pipfile Pipfile.lock
git commit -m "Add pandas dependency"

Troubleshooting

Issue 1: Pipenv Lock Takes Forever

Symptoms: pipenv install or pipenv lock hangs for extended periods.

Solutions:

# Skip lock generation (development only)
pipenv install --skip-lock requests

# Clear resolver cache
pipenv lock --clear

# Use pre-release resolver (faster)
pipenv lock --pre

# Increase timeout
PIPENV_TIMEOUT=600 pipenv install

Issue 2: Virtual Environment in Wrong Location

Problem: Want virtual environment in project directory instead of global location.

Solution:

# Set environment variable
export PIPENV_VENV_IN_PROJECT=1

# Or add to shell profile (~/.bashrc, ~/.zshrc)
echo 'export PIPENV_VENV_IN_PROJECT=1' >> ~/.bashrc

# Remove existing environment
pipenv --rm

# Create new environment (will be in .venv/)
pipenv install

Issue 3: Pipfile.lock Out of Sync

Symptoms: pipenv install --deploy fails with lock file mismatch.

Solution:

# Regenerate lock file
pipenv lock

# Or install and ignore lock file warning
pipenv install

# Or force sync from lock file
pipenv sync

Issue 4: Python Version Not Found

Symptoms: Warning: Python X.X was not found on your system...

Solutions:

# Check available Python versions
which python3  # Linux/Mac
where python   # Windows

# Use absolute path
pipenv --python /usr/bin/python3.11

# Or install Python first with pyenv
pyenv install 3.11.5
pipenv --python 3.11.5

Issue 5: SSL Certificate Errors

Symptoms: Certificate verification errors when installing packages.

Solutions:

# Disable SSL verification (not recommended for production)
pipenv install --cert=''

# Or in Pipfile:
[[source]]
url = "https://pypi.org/simple"
verify_ssl = false  # Change to false
name = "pypi"

# Better: Install proper certificates
# macOS
brew install openssl

# Ubuntu/Debian
sudo apt-get install ca-certificates

Issue 6: Import Errors After Installation

Symptoms: ModuleNotFoundError even though package is installed.

Solutions:

# Check Python interpreter
import sys
print(sys.executable)

# Should point to Pipenv virtual environment
# Ensure you're using Pipenv's Python
pipenv run python script.py

# Or activate shell first
pipenv shell
python script.py

# Verify package is installed
pipenv graph | grep package-name

Issue 7: Dependency Conflicts

Symptoms: ERROR: Could not find a version that matches...

Solutions:

# Try updating all packages
pipenv update

# Clear cache and retry
pipenv lock --clear

# Check dependency tree
pipenv graph

# If specific conflict, manually specify compatible versions
pipenv install "package1>=1.0,<2.0" "package2>=2.0,<3.0"

Issue 8: Removing All Dependencies

# Uninstall all packages
pipenv uninstall --all

# Remove virtual environment entirely
pipenv --rm

# Start fresh
pipenv install

Pipenv vs Other Tools

Pipenv vs pip + virtualenv

FeaturePipenvpip + virtualenv
SetupSingle commandMultiple tools
Dependency trackingAutomatic (Pipfile)Manual (requirements.txt)
Lock fileAutomatic with hashesManual pinning
Dev dependenciesBuilt-inManual separation
Security scanningpipenv checkRequires separate tool
ComplexityMediumHigh

Pipenv vs Poetry

FeaturePipenvPoetry
Primary use caseApplicationsLibraries & applications
Lock speedSlowerFaster
Build systemNoYes (PEP 517)
PublishingNoYes (PyPI)
Dependency resolutionGoodExcellent
MaturityMatureNewer but active

Use Pipenv when: Building applications, need simple workflow, already familiar with pip.

Use Poetry when: Building libraries, publishing to PyPI, need faster dependency resolution.

Pipenv vs Conda

FeaturePipenvConda
Python-onlyYesNo (multi-language)
System packagesNoYes
Binary packagesNoYes
Data scienceGoodExcellent
SizeSmallLarge

Use Pipenv when: Pure Python projects, web applications, microservices.

Use Conda when: Data science with non-Python dependencies (CUDA, MKL), need compiled binaries.

Best Practices

1. Always Commit Lock Files

# Do commit
git add Pipfile Pipfile.lock
git commit -m "Update dependencies"

# Never add to .gitignore
# ❌ Don't do this:
echo "Pipfile.lock" >> .gitignore

2. Separate Dev and Production Dependencies

# Development tools
pipenv install --dev pytest black pylint mypy ipython

# Production dependencies
pipenv install django gunicorn psycopg2-binary

3. Use Specific Versions for Critical Dependencies

[packages]
# Good: Specific with constraints
django = ">=4.2,<5.0"
celery = "~=5.3.0"

# Avoid: Too permissive
requests = "*"  # Can break unexpectedly

# Avoid: Too strict (unless necessary)
numpy = "==1.24.3"  # Hard to update

4. Run Security Checks Regularly

# Before deployment
pipenv check

# In CI/CD pipeline
pipenv check || exit 1

5. Use .env for Configuration

# Never commit secrets
echo ".env" >> .gitignore

# Provide template
cp .env .env.example
# Edit .env.example to remove sensitive values
git add .env.example

6. Document Custom Scripts

# In Pipfile - add comments
[scripts]
# Start development server on port 8000
dev = "python manage.py runserver"

# Run test suite with coverage
test = "pytest --cov=src tests/"

# Format code with Black
format = "black ."

7. Keep Pipenv Updated

# Check version
pipenv --version

# Update Pipenv
pip install --upgrade pipenv

8. Use --deploy in Production

# In production (Docker, servers, CI/CD)
pipenv install --deploy --system

# This ensures:
# - Lock file is up to date
# - Installs system-wide (no venv)
# - Fails if any issues

Quick Reference Card

# Setup
pipenv install                          # Initialize project
pipenv --python 3.11                    # Specify Python version
pipenv install -r requirements.txt      # Import from requirements.txt

# Install packages
pipenv install <package>                # Add production dependency
pipenv install --dev <package>          # Add dev dependency
pipenv install                          # Install from Pipfile
pipenv sync                             # Install from Pipfile.lock

# Update
pipenv update                           # Update all packages
pipenv update <package>                 # Update specific package
pipenv update --outdated                # Show outdated packages

# Remove
pipenv uninstall <package>              # Remove package
pipenv uninstall --all                  # Remove all packages
pipenv --rm                             # Delete virtual environment

# Information
pipenv graph                            # Dependency tree
pipenv --venv                           # Virtual environment location
pipenv --py                             # Python interpreter path
pipenv --where                          # Project location

# Security
pipenv check                            # Check vulnerabilities
pipenv verify                           # Verify lock file

# Run
pipenv shell                            # Activate shell
pipenv run python script.py             # Run without activating
pipenv run <command>                    # Run any command

# Lock
pipenv lock                             # Generate lock file
pipenv lock --clear                     # Clear cache and lock

# Export
pipenv requirements > requirements.txt  # Export to requirements.txt
pipenv requirements --dev               # Export dev requirements

Summary

Pipenv streamlines Python dependency management by:

Automatically creating and managing virtual environmentsSeparating development and production dependenciesProviding deterministic builds with Pipfile.lockIncluding built-in security vulnerability scanningSupporting environment variables via .env filesOffering clear dependency visualizationSimplifying the deployment workflow

When to Use Pipenv

  • ✅ Python application development
  • ✅ Web applications (Django, Flask, FastAPI)
  • ✅ API services and microservices
  • ✅ Data engineering pipelines
  • ✅ Scripts and automation tools
  • ✅ Projects requiring reproducible builds

When to Consider Alternatives

  • ❌ Building Python packages for PyPI → Use Poetry
  • ❌ Data science with non-Python deps → Use Conda
  • ❌ Very simple scripts → Use venv + pip
  • ❌ Legacy projects locked to requirements.txt → Stick with pip

Last updated: October 2025

Related Articles

Python Cheat Sheet

Awesome Python frameworks. A curated list of awesome Python frameworks, libraries, software and resources.

PyTorch for Python

PyTorch is a popular open-source library primarily used for deep learning applications but also offers versatility in general machine learning areas.