Pipenv: promises a lot, delivers very little

A 2020 update (updated)

This blog post was written in 2018, and it’s still pretty accurate when it comes to the criticisms of Pipenv, but something else happened since then.

No release was made between November 2018 and May 2020. Pipenv was effectively dead for 1.5 years, and the state of Pipenv maintenance is alarming.

A release of Pipenv was made in late 2018 (aptly named v2018.11.26). But then, there was silence. New commits were made (on the order of 600-700 by the end of the year). People asked for new releases, in more or less strong words, in May 2019, then in October, and again in December. Many people — including yours truly, in this post — considered Pipenv dead. On 13th December 2019, the current maintainer claimed a new release is almost finished.

Pipenv 2019/2020 was vaporware for five months. Not much progress was made since the December post until March 2020, when an issue from 2018 was renamed the March 2020 Release Tracking Issue. Some progress was happening, and many release dates were given, but delays stacked up. March became April. The first beta release was promised by 21st April, it was delayed until the 29th. The final release was scheduled for a week from that, but it didn’t happen. Finally, Beta 2 came out on 20th May 2020, and the final release landed as v2020.5.28.

If you read further into the post, you’ll encounter a chapter titled The break-neck pace of Pipenv. Am I being a hypocrite right now? No, not at all. Projects that are being depended on, such as a package manager, should have clear policies about how they’re maintained. A new release when the maintainer feels like adding a feature is too often. A new release every 1.5 years is not often enough. And silence from maintainers, when faced with questions about releases, is simply unacceptable. Pip, for example, has updates every few months in a fairly stable pace (with the exception of emergency bugfix releases), and pip has years of development behind it, unlike the fairly new Pipenv.

And even if the May release was successful, you can’t be sure about any future releases, and what will happen with Pipenv. At the same time, Pipenv isn’t a good tool, as this post tries to explain — those criticisms are still valid, since they are at the core of what Pipenv is. Instead, perhaps consider using pip-tools for locking dependencies? It does one thing, and one thing well. It doesn’t enforce any specific structures on users, and supports any workflow you have. (If you don’t need to lock dependencies, pip + venv will suffice.)

“Officially recommended tool”, or how we got here

“Pipenv — the officially recommended Python packaging tool from Python.org, free (as in freedom).”

Pipenv’s README used to have a version of the above line in their README for many months: it was added on 2017-08-31 and eventually disappeared on 2018-05-19. For a short while (2018-05-16), it was clarified (managing application dependencies, and PyPA instead of Python.org), and for about 15 minutes, the tagline called Pipenv the world’s worst or something along these lines (this coming from the maintainer).

The README tagline claimed that Pipenv is the be-all, end-all of Python packaging. The problem is: it isn’t that. There are some use cases that benefit from Pipenv, but for many others, trying to use that tool will only lead to frustration. We will explore this issue later.

Another issue with this tagline was the Python.org and official parts. The thing that made it “official” was a short tutorial [1] on packaging.python.org, which is the PyPA’s packaging user guide. Also of note is the Python.org domain used. It makes it sound as if Pipenv was endorsed by the Python core team. PyPA (Python Packaging Authority) is a separate organization — they are responsible for the packaging parts (including pypi.org, setuptools, pip, wheel, virtualenv, etc.) of Python. This made the endorsement misleading. Of course, PyPA is a valued part of the Python world; an endorsement by the core team — say, inclusion in official Python distributions — is something far more important.

This tagline has led to many discussions and flamewars, perhaps with this Reddit thread from May being the most heated and most important. The change was the direct result of this Reddit thread. I recommend reading this thread in full.

What pipenv does

We’ve already learned that Pipenv is used to manage application dependencies. Let’s learn what that term really means.

What pipenv doesn’t do

The workflow I mentioned above looks pretty reasonable, right? There are some deficiencies, but other than that, it seems to work well. The main issue with Pipenv is: it works with one workflow, and one workflow only. Try to do anything else, and you end up facing multiple obstacles.

$ ~/virtualenvs/foobar/bin/python ~/Downloads/repro.py

$ cd ~/git/foobar
$ pipenv run python ~/Downloads/repro.py

$ cd ~/git/foobar
$ pipenv shell
(foobar-Mwd1l2m9)$ cd ~/Downloads
(foobar-Mwd1l2m9)$ python repro.py
(foobar-Mwd1l2m9)$ exit  # (not deactivate!)

$ cd ~/Downloads
$ workon foobar
(foobar)$ python repro.py
(foobar)$ deactivate

The part where I try to measure times

Pipenv is famous for being slow. But how slow is it really? I put it to the test. I used two test environments:

• Remote: a DigitalOcean VPS, the cheapest option (1 vCPU), Python 3.6/Fedora 28, in Frankfurt

• Local: my 2015 13” MacBook Pro (base model), Python 3.7, on a rather slow Internet connection (10 Mbps on a good day, and the test was not performed on one of them)

Both were runninng Pipenv 2018.7.1, installed from pip.

And with the following cache setups:

• Removed: ~/.cache/pipenv removed

• Partial: rm -rf ~/.cache/pipenv/depcache-py*.json ~/.cache/pipenv/hash-cache/

• Kept: no changes done from previous run

Well, turns out Pipenv likes doing strange things with caching and locking. A look at the Activity Monitor hinted that there is network activity going on when Pipenv displays its Locking [packages] dependencies... line and hangs. Now, the docs don’t tell you that. The most atrocious example was a local Nikola install that was done in two runs: the first pipenv install Nikola run was interrupted [4] right after it was done installing packages, so the cache had all the necessary wheels in it. The install took 10 minutes and 7 seconds, 9:50 of which were taken by locking dependencies and installing the locked dependencies — so, roughly nine and a half minutes were spent staring at a static screen, with the tool doing something in the background — and Pipenv doesn’t tell you what happens in this phase.

(Updated 2018-07-22: In the pipenv measurements: the first entry is the total time of pipenv executon. The second is the long wait for pipenv to do its “main” job: locking dependencies and installing them. The timing starts when pipenv starts locking dependencies and ends when the prompt appears. The third item is pipenv’s reported installation time. So, pipenv install ⊇ locking/installing ⊇ Pipfile.lock install.)

Alternative tools

Python packaging is something with the state of which nobody seems to be satisfied. As such, there are many new contenders for the role of “best new packaging tool”.

Two popular alternatives packaging tools are pip-tools (by Vincent Driessen and Jazzband) and Poetry (by Sébastien Eustace).

Pip is here to stay!

But in all the talk about new tools, we’re forgetting about the old ones, and they do their job well — so well in fact, that the new tools still need them under the covers.

Pip is fast. It does its job well enough. It lacks support for splitting packages between production and development (as Pipenv and Poetry do). This means that pip freeze and pip install are instant, at the cost of (a) needing two separate environments, or (b) installing development dependencies in production (which should only be a waste of HDD space and nothing more in a well-architected system). But at the same time, pip-tools can help keep the environments separate, as long as you take some time to write separate requirements.in files.

The virtualenv management features can be provided by virtualenvwrapper. That tool’s main advantage is the shell script implementation, which means that workon foo activates the foo virtualenv without spawning a new subshell (an issue with Pipenv and Poetry, that I already covered when describing Pipenv’s operation in the Running scripts (badly) chapter.) An argument often raised by Pipenv proponents is that one does not need to concern itself with creating the virtualenv, and doesn’t need to care where it is. Unfortuntately, many tools require this knowledge from their user, or force a specific location, or require it to be different to the home directory.

And for a reasonable project template with release automation — well, I have my own entry in that category, called (rather unoriginally) the Python Project Template (PyPT).

Yes, setup.py files are not ideal, since they use .py code and a function execution, making access to meta information hard (./setup.py egg_info creates tool-accessible text files). Their main advantage is that they are the only format that is widely supported — pip is the de-facto default Python package manager (which is pre-installed on Windows and Mac), and other tools would require installation/bootstrapping first.

The break-neck pace of Pipenv

A good packaging tool is stable. In other words, it doesn’t change often, and it strives to support existing environments. It wouldn’t be fun to re-download everything on your system, because someone decided that /usr is now called /stuff, and all the files in /usr would become forgotten and not removed. Well, this is what Pipenv did:

Over the course of a month, the location of the virtualenv changed twice. If the user didn’t read the changelog and didn’t manually intervene (also of note, the option name was mentioned in the issue and in v3.3.4’s changelog), they would have a stale .venv directory, since the new scheme was adopted for them. And then, after switching to v3.5.0, they would have a stale virtualenv hidden somewhere in their home directory, because pipenv decided to add hashes.

Also, this is not configurable. One cannot disable the hashes in paths, even though users wanted to. It would also help people who want to mix Pipenv and virtualenvwrapper.

Pipenv is a very opinionated tool, and if the dev team changes their mind, the old way is not supported.

Pipenv moves fast and doesn’t care if anything breaks. As an example, between 2018-03-13 13:21 and 2018-03-14 13:44 (a little over 24 hours), Pipenv had 10 releases, ranging from v11.6.2 to v11.7.3. The changelog is rather unhelpful when it comes to informing users what happened in each of the releases.

Extra reading:

• Kenneth Reitz, A Letter to /r/python (with some notes about bipolar disorder) (replaced with Wayback Machine link on 2020-02-07)

• Reddit comment threads for the letter: first and second

Conclusion

• Pipenv, contrary to popular belief and (now removed) propaganda, is not an officially recommended tool of Python.org. It merely has a tutorial written about it on packaging.python.org (page run by the PyPA).

• Pipenv solves one use case reasonably well, but fails at many others, because it forces a particular workflow on its users.

• Pipenv does not handle any parts of packaging (cannot produce sdists and wheels). Users who want to upload to PyPI need to manage a setup.py file manually, alongside and independently of Pipenv.

• Pipenv produces lockfiles, which are useful for reproducibility, at the cost of installation speed. The speed is a noticeable issue with the tool. pip freeze is good enough for this, even if there are no dependency classes (production vs development) and no hashes (which have minor benefits) [2]

• Poetry supports the same niche Pipenv does, while also adding the ability to create packages and improving over many gripes of Pipenv. A notable issue is the use of a custom all-encompassing file format, which makes switching tools more difficult (vendor lock-in).

• Pip, setup.py, and virtualenv — the traditional, tried-and-true tools — are still available, undergoing constant development. Using them can lead to a simpler, better experience. Also of note, tools like virtualenvwrapper can manage virtualenvs better than the aforementioned new Python tools, because it is based on shell scripts (which can modify the enivironment).

• Since 2018, the packaging scene deteriorated even more. See How to improve Python packaging, or why fourteen tools are at least twelve too many (from January 2023) and Python Packaging, One Year Later: A Look Back at 2023 in Python Packaging (from January 2024).

Other discussion threads: r/Python, Hacker News.