While recently deploying a new Python Django app to Heroku, I noticed the documentation mentioned a tool I hadn’t known before: pipenv. I thought to myself, “Great, now I need to learn a new tool. What was so bad about pip and virtualenv?” So, I did my research, and BOOM! Yes. Mind blown. Life changed. This.

What It Is

Pipenv is the Python packaging and environments tool for champions.

• It unites pip, Pipfile, and virtualenv into a sophisticated workflow with simple commands.
• It automatically creates virtual environments for projects.
• It automatically updates package dependencies (and their dependencies).
• It locks versions for deterministic builds.

Despite some controversy and limitations, I strongly recommend using pipenv for most new Python projects. The Python Packaging Authority recommends it, too.

What It’s About

Packages and environments (“packagement”) are essential to Python development. Typically, Pythoneers create a virtual environment for each project and install dependent packages into it locally using pip. They then “freeze” the dependencies into a requirements.txt file so that others can easily recreate the environment. Virtual environments thus enable different projects to use different package versions without global conflict.

Unfortunately, this traditional workflow has some problems:

• It uses multiple tools instead of one and requires many commands.
• Different projects can do the workflow differently, which can be confusing.
• The requirements.txt file must be manually generated and can easily fall out of date.
• Dev-only dependencies are a hassle to separate.
• Uninstalling packages will not remove sub-packages.
• Dependencies with version ranges instead of fixed versions cause nondeterministic builds.

Pipenv solves these problems by combining pip, Pipfile, and virtualenv into a standard workflow that automatically handles and locks package updates.

How to Use It

See how simple it is to use pipenv with a Python project:

# Install pipenv
pip install pipenv

# Create a new project directory
mkdir panda_project
cd panda_project
echo "print('hello')" > main.py

# Init pipenv:
# Creates a virtual environment
# Then creates Pipfile and Pipfile.lock files
pipenv install

# Install a package:
# Updates the Pipfiles
pipenv install requests

# Install a dev-only package:
# Updates the Pipfiles
pipenv install --dev pytest

# Run commands in the environment
pipenv run python --version
pipenv run python main.py

More Info

There’s no need for me to repeat what other people have already said:

• Official Docs
  • Pipenv: Python Dev Workflow for Humans
  • Pipenv: The Future of Python Dependency Management (PyCon 2018 talk)
  • The pypa/pipenv project on GitHub
  • Managing Application Dependencies from PyPA
  • Pipenv & Virtual Environments from The Hitchhiker’s Guide to Python
• Secondary Articles
  • Announcing Pipenv! from Kenneth Reitz, the primary author
  • How to manage your Python projects with Pipenv
  • Why Python devs should use Pipenv
  • Stop everything! Start using Pipenv!
• Comparisons
  • Pipfile vs. setup.py
  • Reddit: pyvenv vs. virtualenv
  • Stack Overflow: What is the difference between pyenv, virtualenv, anaconda?
  • Stack Overflow: What is the difference between venv, pyvenv, pyenv, virtualenv, virtualenvwrapper, pipenv, etc?
• Limitations
  • Reddit: Why is pipenv the recommended packaging tool?
  • Pipenv: promises a lot, delivers very little

 

 

 

[8/24/2018 Update: Mentioned some of the controversy and limitations of pipenv.]