Pipenv — A Practitioner’s Cheat Sheet

[TL;DR] Cheat sheet for npm users

Why pipenv

Coming from an embedded systems background, I was initially reluctant to adopt Python’s virtual environment tools. My main excuse was that they denied me straightforward access to relevant files, which added complexity to installing and troubleshooting the libraries I needed to meet deadlines. Another significant reason was that I didn’t fully understand the term virtual environment, which made me feel uneasy. I blamed the continued use of Python 2 and the lack of a default package manager (before pip was bundled) for my troubles.

About three years ago, I picked up NodeJS and had a great experience with npm, partly because it was clearly defined as a package manager—something I could easily understand. This helped me appreciate the value a virtual environment (aka package manager, aka development environment manager) could offer. When I started a new Python project, I decided to spend some time learning pipenv and writing this article to demonstrate how it can help a busy, cross-platform team enjoy writing Python.

It’s easy to use pipenv

The following is a digest of the official documentation at https://docs.pipenv.org.

First, install pipenv using pip. It’s the only tool you’ll need to install into the OS paths.

pip install pipenv

Next, create a new directory for our test and change into it.

mkdir somethingelse
cd somethingelse

Create a managed development environment in the current directory with a specific version of Python.

pipenv --python 3.5

Install some packages for your project.

pipenv install flask

Observe the directory—you should find a readable Pipfile:

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

[dev-packages]

[packages]
flask = "*"

[requires]
python_version = "3.5"

You should also find a Pipfile.lock file, which is less readable (and too long to include here).

Now you have a development environment ready to use with Python 3.5 and some version of Flask. Let’s verify that the environment is truly virtual by first confirming Flask is unavailable when directly invoking the interpreter.

$ python3.5
Python 3.5.2 (default, Nov 23 2017, 16:37:01)
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import flask
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named 'flask'
>>>

Now, verify that Flask is available after activating the development environment.

$ pipenv shell
(somethingelse-OjhD42Bo) $ python3.5
Python 3.5.2 (default, Nov 23 2017, 16:37:01)
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import flask
>>> flask.__version__
'1.0.2'
>>>

Finally, exit the development environment.

$ exit

Replicate the environment with version control

This process works well for individuals, but how does it help a team? By allowing easy replication and version control. First, let’s copy the files to a new directory.

cd ..
mkdir second
cd second
cp ../somethingelse/Pipfile .
cp ../somethingelse/Pipfile.lock .

Now, running one command replicates the exact development environment. For added practicality, set the PIPENV_VENV_IN_PROJECT environment variable to 1.

export PIPENV_VENV_IN_PROJECT=1
pipenv sync

Unlike the earlier setup, you’ll notice an additional .venv directory containing the necessary files for the development environment. Verify this with the same method as before.

$ pipenv shell
(second) $ python3.5
Python 3.5.2 (default, Nov 23 2017, 16:37:01)
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import flask
>>> flask.__version__
'1.0.2'
>>>

The initial steps can be streamlined by committing both the Pipfile and Pipfile.lock to git (or another version control system). Encourage your team to run pipenv sync when a library is missing. This approach saves time debugging OS-specific hacks. Once you have a working baseline, each team member can choose their preferred IDE (Anaconda, Spyder, or others).