- Published on
Pipenv Cheat Sheet
Table of Contents
- What is Pipenv?
- Installation
- Quick Start Guide
- Essential Commands
- Advanced Usage
- Common Workflows
- Troubleshooting
- Pipenv vs Other Tools
- Best Practices
- Quick Reference Card
- Summary
- Related Topics
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
Feature | Description |
---|---|
Automatic Virtual Environments | Creates and manages project-specific environments automatically |
Pipfile | Modern, declarative dependency specification (replaces requirements.txt) |
Pipfile.lock | Deterministic builds with cryptographic hashes for security |
Dev Dependencies | Separate development and production dependencies |
Security Scanning | Built-in vulnerability checking with pipenv check |
Dependency Graph | Visualize dependency relationships with pipenv graph |
Python Version Management | Specify and enforce Python versions per project |
Environment Variables | Automatic .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/40478 — 00: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 /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
Feature | Pipenv | pip + virtualenv |
---|---|---|
Setup | Single command | Multiple tools |
Dependency tracking | Automatic (Pipfile) | Manual (requirements.txt) |
Lock file | Automatic with hashes | Manual pinning |
Dev dependencies | Built-in | Manual separation |
Security scanning | pipenv check | Requires separate tool |
Complexity | Medium | High |
Pipenv vs Poetry
Feature | Pipenv | Poetry |
---|---|---|
Primary use case | Applications | Libraries & applications |
Lock speed | Slower | Faster |
Build system | No | Yes (PEP 517) |
Publishing | No | Yes (PyPI) |
Dependency resolution | Good | Excellent |
Maturity | Mature | Newer 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
Feature | Pipenv | Conda |
---|---|---|
Python-only | Yes | No (multi-language) |
System packages | No | Yes |
Binary packages | No | Yes |
Data science | Good | Excellent |
Size | Small | Large |
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 environments ✅ Separating development and production dependencies ✅ Providing deterministic builds with Pipfile.lock ✅ Including built-in security vulnerability scanning ✅ Supporting environment variables via .env files ✅ Offering clear dependency visualization ✅ Simplifying 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
Related Topics
- How to use Pipenv with Jupyter and VSCode - Complete setup guide for data science workflows
- Python Cheat Sheet - Quick reference for Python syntax
- Docker Best Practices - Containerizing Python applications
Last updated: October 2025
Related Articles
The power of Pipenv and Jupyter Notebook
A comprehensive guide to using Pipenv with Jupyter Notebook and VSCode. Learn how to manage Python dependencies, create isolated environments, and configure your development workflow for data science projects.
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.