pipenv/docs/cli.md

Pipenv Command Line Interface

This comprehensive guide covers Pipenv's command line interface, including all available commands, options, and usage examples.

Overview

Pipenv provides a powerful command line interface (CLI) that simplifies Python dependency management and virtual environment workflows. The CLI follows a consistent pattern:

pipenv [OPTIONS] COMMAND [ARGS]...

Global Options

These options can be used with any Pipenv command:

Option	Description
--where	Output project home information
--venv	Output virtualenv information
--py	Output Python interpreter information
--envs	Output environment variable options
--rm	Remove the virtualenv (deprecated: use pipenv remove instead)
--bare	Minimal output
--man	Display manpage
--support	Output diagnostic information for GitHub issues
--site-packages	Enable site-packages for the virtualenv
--python TEXT	Specify which Python version to use
--clear	Clear caches (pipenv, pip)
-q, --quiet	Quiet mode
-v, --verbose	Verbose mode
--pypi-mirror TEXT	Specify a PyPI mirror
--version	Show the version and exit
-h, --help	Show help message and exit

Core Commands

install

Installs packages and adds them to Pipfile, or installs all packages from Pipfile.lock if no packages are specified.

pipenv install [OPTIONS] [PACKAGES]...

Options

Option	Description
--dev	Install both development and default packages
--categories TEXT	Install packages to specified category groups
--system	Install to system Python instead of virtualenv
--deploy	Abort if Pipfile.lock is out-of-date
--ignore-pipfile	Install from Pipfile.lock, ignoring Pipfile
--skip-lock	Skip locking of dependencies
--requirements, -r TEXT	Import a requirements.txt file
--extra-pip-args TEXT	Pass additional arguments to pip
--python TEXT	Specify which Python version to use
--dry-run	Show what would happen without making changes

Examples

Install a specific package:

$ pipenv install requests

Install a package with version constraint:

$ pipenv install "requests>=2.20.0"

Install a development dependency:

$ pipenv install pytest --dev

Install from requirements.txt:

$ pipenv install -r requirements.txt

Install with deployment check:

$ pipenv install --deploy

uninstall

Uninstalls a provided package and removes it from Pipfile.

pipenv uninstall [OPTIONS] [PACKAGES]...

Options

Option	Description
--all	Purge all files from the virtual environment
--all-dev	Remove all development packages
--skip-lock	Skip locking of dependencies
--categories TEXT	Uninstall from specified category groups

Examples

Uninstall a package:

$ pipenv uninstall requests

Uninstall all packages:

$ pipenv uninstall --all

Uninstall all development packages:

$ pipenv uninstall --all-dev

lock

Generates Pipfile.lock with all dependencies and their sub-dependencies.

pipenv lock [OPTIONS]

Options

Option	Description
--pre	Allow pre-releases
--clear	Clear the dependency cache
--verbose	Show verbose output
--categories TEXT	Lock specified categories only
--keep-outdated	Keep outdated dependencies
--python TEXT	Specify which Python version to use for resolution
--extra-pip-args TEXT	Pass additional arguments to pip

Examples

Generate a lock file:

$ pipenv lock

Generate a lock file with pre-releases:

$ pipenv lock --pre

Lock specific categories:

$ pipenv lock --categories="docs,tests"

sync

Installs all packages specified in Pipfile.lock.

pipenv sync [OPTIONS]

Options

Option	Description
--dev	Install both development and default packages
--all	Install packages from all categories defined in the Pipfile
--categories TEXT	Install packages from specified category groups
--python TEXT	Specify which Python version to use
--extra-pip-args TEXT	Pass additional arguments to pip

Examples

Install packages from lock file:

$ pipenv sync

Install development packages too:

$ pipenv sync --dev

Install all categories (default, dev, and any custom categories):

$ pipenv sync --all

Install specific categories:

$ pipenv sync --categories="docs,tests"

update

Runs lock when no packages are specified, or upgrade for specific packages, and then sync.

pipenv update [OPTIONS] [PACKAGES]...

Options

Option	Description
--dev	Update development packages
--all	Update packages from all categories defined in the Pipfile
--categories TEXT	Update packages in specified categories
--outdated	List out-of-date dependencies
--dry-run	Show what would happen without making changes
--python TEXT	Specify which Python version to use
--clear	Clear the dependency cache

Examples

Update all packages:

$ pipenv update

Update specific packages:

$ pipenv update requests pytest

Check for outdated packages:

$ pipenv update --outdated

upgrade

Updates the lock file for specified dependencies without installing them.

pipenv upgrade [OPTIONS] [PACKAGES]...

Options

Option	Description
--dev	Upgrade development packages
--all	Upgrade packages from all categories defined in the Pipfile
--categories TEXT	Upgrade packages in specified categories
--dry-run	Show what would happen without making changes
--python TEXT	Specify which Python version to use
--clear	Clear the dependency cache

Examples

Upgrade a specific package in the lock file:

$ pipenv upgrade requests

Upgrade development packages:

$ pipenv upgrade --dev

check

Checks for security vulnerabilities and PEP 508 marker compliance.

pipenv check [OPTIONS]

Note: The check command is deprecated and will be unsupported beyond 01 June 2025. In future versions, the check command will run the scan command by default. Use the --scan option to run the new scan command now.

Options

Option	Description
--db TEXT	Path or URL to a PyUp Safety vulnerabilities database
--ignore, -i TEXT	Ignore specified vulnerability
--output [screen|text|json|bare]	Specify output format
--key TEXT	Safety API key from PyUp.io
--use-installed	Use installed packages instead of lockfile
--categories TEXT	Check packages in specified categories
--auto-install	Automatically install safety if not already installed
--scan	Use the new scan command instead

Examples

Check for vulnerabilities:

$ pipenv check

Check with a specific output format:

$ pipenv check --output json

Use the new scan command:

$ pipenv check --scan

scan

Enhanced security scanning (replacement for check).

pipenv scan [OPTIONS]

Options

Similar to the check command, with enhanced functionality.

Examples

Scan for vulnerabilities:

$ pipenv scan

Scan with a specific output format:

$ pipenv scan --output json

run

Spawns a command installed into the virtualenv.

pipenv run [OPTIONS] COMMAND [ARGS]...

Examples

Run a Python script:

$ pipenv run python app.py

Run tests:

$ pipenv run pytest

Run a custom script defined in Pipfile:

$ pipenv run start

shell

Spawns a shell within the virtualenv.

pipenv shell [OPTIONS] [SHELL_ARGS]...

Options

Option	Description
--fancy	Use a fancy shell activation method

Examples

Activate the virtual environment:

$ pipenv shell

Activate with fancy mode:

$ pipenv shell --fancy

graph

Displays currently-installed dependency graph information.

pipenv graph [OPTIONS]

Options

Option	Description
--bare	Output graph in bare format
--json	Output graph in JSON format
--json-tree	Output graph as JSON tree
--reverse	Reversed dependency graph

Examples

Show dependency graph:

$ pipenv graph

Show reverse dependencies:

$ pipenv graph --reverse

Show JSON output:

$ pipenv graph --json

clean

Uninstalls all packages not specified in Pipfile.lock.

pipenv clean [OPTIONS]

Options

Option	Description
--dry-run	Show what would be removed without removing

Examples

Remove unused packages:

$ pipenv clean

Preview what would be removed:

$ pipenv clean --dry-run

requirements

Generate a requirements.txt from Pipfile.lock.

pipenv requirements [OPTIONS]

Options

Option	Description
--dev	Include development packages
--dev-only	Only include development packages
--hash	Include package hashes
--exclude-markers	Exclude PEP 508 markers
--categories TEXT	Include packages from specified categories

Examples

Generate requirements.txt:

$ pipenv requirements > requirements.txt

Include development packages:

$ pipenv requirements --dev > requirements-dev.txt

Include hashes:

$ pipenv requirements --hash > requirements.txt

scripts

Lists scripts defined in the current environment config.

pipenv scripts [OPTIONS]

Examples

List available scripts:

$ pipenv scripts

open

Opens a Python module in your editor.

pipenv open [OPTIONS] MODULE

Examples

Open the requests module:

$ pipenv open requests

Open with a specific editor:

$ EDITOR=code pipenv open requests

verify

Verifies that the Pipfile.lock is up-to-date with the Pipfile.

pipenv verify [OPTIONS]

Examples

Verify lock file integrity:

$ pipenv verify

Environment Variables

Pipenv's behavior can be customized through environment variables. Here are some commonly used ones:

Variable	Description
PIPENV_VENV_IN_PROJECT	Create virtualenv in project directory
PIPENV_IGNORE_VIRTUALENVS	Ignore active virtualenvs
PIPENV_PIPFILE	Custom Pipfile location
PIPENV_DOTENV_LOCATION	Custom .env file location
PIPENV_CACHE_DIR	Custom cache directory
PIPENV_TIMEOUT	Timeout for pip operations
PIPENV_SKIP_LOCK	Skip lock file generation
PIPENV_PYPI_MIRROR	PyPI mirror URL
PIPENV_MAX_DEPTH	Maximum depth for dependency resolution
PIPENV_DONT_LOAD_ENV	Don't load .env files

For a complete list, see the Configuration page.

Command Relationships

Understanding how Pipenv commands relate to each other can help you use them more effectively:

• install: Adds packages to Pipfile and updates Pipfile.lock
• lock: Updates Pipfile.lock without installing packages
• sync: Installs packages from Pipfile.lock without modifying it
• update: Combines lock and sync (or upgrade and sync for specific packages)
• upgrade: Updates Pipfile.lock for specific packages without installing them
• uninstall: Removes packages from virtualenv and Pipfile
• clean: Removes packages from virtualenv that aren't in Pipfile.lock
• remove: Deletes the entire virtualenv for the current project

Best Practices

CI/CD Pipelines

For continuous integration and deployment:

# Verify the lock file is up-to-date
$ pipenv verify

# Install dependencies
$ pipenv sync --dev

# Run tests
$ pipenv run pytest

Production Deployment

For production environments:

# Install only production dependencies
$ pipenv install --deploy

# Or for systems without virtualenv support
$ pipenv install --system --deploy

Development Workflow

For daily development:

# Install dependencies including development packages
$ pipenv install --dev

# Activate environment
$ pipenv shell

# Run your application
$ python app.py

Troubleshooting

Common Issues

• Command not found: Ensure Pipenv is installed and in your PATH
• Pipfile not found: Run commands from your project directory
• Lock file out of date: Run pipenv lock to update it
• Dependency conflicts: Try pipenv lock --clear to clear the cache

For more troubleshooting tips, see the Troubleshooting guide.

Conclusion

Pipenv's CLI provides a comprehensive set of commands for managing Python dependencies and virtual environments. By understanding these commands and their options, you can streamline your Python development workflow and ensure consistent, reproducible environments.