pipenv — a practitioner’s cheat sheet

[TL;DR] Cheat sheet for npm users

npm vs. pipenv cheat sheet

Why pipenv

Coming from a embedded systems world as a practitioner, I had been reluctant to adopt Python’s virtual environment tools. The major excuse was that it denied me straightforward access to relevant files, which just adds to the complexity of installing and troubleshooting the libraries I need to meet the deadline. Another substantial reason is that I don’t understand the word virtual environment and it made me feel unsafe. I blamed the people who are still using Python 2 and the lack of a default package manager (before pip was shipped by default) for my troubles.

Around 3 years ago, I picked up NodeJS, and had a great experience with npm, partly because it’s called a package manager which is something I understand. Then I started to see the value a virtual environment aka package manager aka development environment manager can provide. When I started a new Python project, I spent the extra time to learn to use pipenv and to write this article to demonstrate how it can help your busy cross-platform team have a good time writing Python.

It’s easy to use pipenv

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

First install pipenv from pip, and it’ll be the only thing you need to install into the OS paths.

pip install pipenv

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

mkdir somethingelse
cd somethingelse

Make a managed development environment inside 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 quite 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 not-as-readable Pipfile.lock. (Too long to show)

Now you have a development environment ready to use that features Python 3.5 + some version of Flask. Now let’s verify the environment is really virtual by first verifying flask is not available from a interpreter invoked directly.

$ 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'
>>>

Then verify 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'
>>>

Now exit the development environment.

$ exit

Replicate the environment with version control

So this kinda works for the individual, but how does this help others? 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

Then running one command will replicate the exact development environment. But let’s be fancy (actually less magical and more practical IMHO) and set the PIPENV_VENV_IN_PROJECT environment variable to 1.

export PIPENV_VENV_IN_PROJECT=1
pipenv sync

Observe in contrast to the previous section, there is an additional .venv directory, which contains the necessary files for the development environment. Let’s verify with the same method in the previous section.

$ 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 first step can be replaced by committing both Pipfile and Pipfile.lock to git (or anything else you like). And if you can convince the team to first run pipenv sync when some library is missing, you are on the way to saving a bunch of time debugging everyone’s OS hacks. Once there is a working baseline, each person can choose her own IDE (Anaconda / Spider / other reptiles or arthropods).