pipenv

The pipenv project aims to combine pip and virtualenv into one single toolchain. It is currently the recommended packaging tool of the Python Packaging Authority, while slowly being surpassed in popularity by poetry.

It introduces two new files to your project: Pipfile and Pipfile.lock. The first is similar to requirements.txt and tracks all packages that you explicitly installed. The latter is an extended version of the pip freeze output and precisely tracks the versions of all installed dependencies. This file is the key to recreating exactly the same environment on a different machine for full reproducibility. While you can still fine-tune the Pipfile by hand, both files can be fully managed by pipenv commands.

Usage

If you are working on a project with an existing Pipfile.lock, one single command is sufficient to create a virtual environment and install all listed dependencies.

$ pipenv sync

Tip

By default pipenv creates all virtual environments in the common ~/.local/share/virtualenvs/ directory. We recommend to set the environment variable PIPENV_VENV_IN_PROJECT=1 to instead use the .venv directory inside the project’s root.

On a new project, simply start by installing the required packages with pipenv, thereby initializing the virtual environment and Pipfile[.lock] files.

$ pipenv install <package>

Tip

Always add Pipfile and Pipfile.lock to your version-control system. Not only does it help your collaborators to use the same package versions, but it also tracks all package updates in the git history.

Note

Some packages may fail to install on macOS, because the system is reporting a version number >10, but they expect 10.x. Even though this should be patched in the upstream versions, you may still encounter the bug in rare cases. A simple fix is to configure the system to report a compatible version number before installing the problematic packages.

$ export SYSTEM_VERSION_COMPAT=1

To run the code of your project you can, as usual, activate the virtual environment, or use pipenv helper commands.

$ pipenv shell          # spawn shell with activated virtual environment
$ pipenv run <command>  # run given command inside the virtual environment

Development dependencies

In addition to the standard package dependencies, one can define a list of dependencies useful when developing on the project. This could include formatters and linters that are important when writing code, but are not required in production.

$ pip install --dev <package>       # install package as development dependency

Similarly, use pipenv sync --dev to include dev packages when re-creating the virtual environment from an existing Pipfile.lock.

Upgrading dependencies

With the pipenv update subcommand it’s easy to list outdated packages and install all available updates.

$ pipenv update [--dev] --outdated  # list outdated packages with available updates
$ pipenv update [--dev]             # install all available updates

Other commands

$ pipenv graph          # show graph of package dependencies
$ pipenv requirements   # generate a requirements.txt file with the package dependencies
$ pipenv clean          # uninstall all packages not specified in Pipfile.lock
$ pipenv --rm           # delete virtual environment