4 min readAug 10, 2019

I previously posted an article on how to install Python 3 and set up virtual environments on a Mac.

An even easier way is to use Pipenv. This is particularly useful when sharing project code with non-developers who find the whole concept of virtual environments rather strange.

This post outlines how to add Pipenv to your python project so that it can be shared easily with people who may not understand virtual environments well.

Installing Pipenv

If Pipenv is not installed, it needs to be installed first. The documentation covers this.

For Mac users, the easiest installation is either Homebrew:

brew install pipenv

Or via pip, using:

pip install pipenv

Using Pipenv in your project

The main principle is that you will use the pipenv command whereever you would have used pip in the past.

Important note — always run the pipenv commands from your project root directory. That is how pipenv knows which virtual environment to use. If you run it from another directory or sub-directory, it will set up a brand new environment there!

1. Create the virtual environment

From the root of your project root folder simply type:

pipenv --three

This will create a new virtual environment for you using your version of Python 3.

This will also create a Pipfile in your project directory that holds the requirements.

If you ever need the location of the virtual environment, it can be found with the pipenv --venv command.

2. Install packages

To install packages (e.g. pandas and matplotlib) use pipenv like you would use pip:

pipenv install pandas matplotlib

This will install the packages in the virtual environment, and also add them to the Pipfile in the project directory that you can share and edit. The Pipfile will now look something like this:

[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true[dev-packages][packages]
pandas = "*"
matplotlib = "*"[requires]
python_version = "3.7"

To install packages you only need in a development environment such as testing tools or formatting tools (e.g. pytest and black) use the --dev option:

pipenv install --dev pytest pylint

The Pipfile will separate these out so that when you deploy your project in production, the development and testing packages do not need to be installed and clog up your server. The Pipfile will have added these to the dev-packages area:

...[dev-packages]
pytest = "*"
pylint = "*"...

Uninstalling packages can be done with either …

pipenv uninstall package_name

… Or you can manually delete the package from the Pipfile and then uninstall it from your virtual environment using pipenv clean

3. Running code

To run your code or tests, you to activate the virtual environment first.

From the project root directory run:

pipenv shell

This will activate the virtual environment. You can now run code or tests.

Deactivate the virtual environment using exit and not the deactivate that virtualenv users will be more familiar with.

4. Sharing the project

Assuming you are using GIT to manage your project and are sharing it, commit the Pipfile to GIT so that other users can use it easily when they receive the project.

The lock file Pipfile.lock can be committed to GIT or added into your .gitignore file as you wish. I tend to exclude it by adding to .gitignore except where it is important to lock down the packages to specific versions.

I add a README.md file in markdown text in the project root that says how to get started when you are given this project. This renders nicely on GitHub or Bitbucket, wherever your code is hosted. It also makes it easier for other users to get started with your code. Here is a snippet of markdown that you can drop into that file:

README.md
...# DevelopersInstructions for installing this project on your local machine and getting it running in its own virtual environment.1.  Clone this project into a new directory - click the clone button above on GitHub to get the link and command to use2.  Ensure you have `pipenv` installed on your machine - installation documentation can be found here - https://docs.pipenv.org/en/latest/install/3.  From the project root directory run `pipenv install --dev --pre` to create your virtual environment and install all the packages4.  Activate your virtual environment at any time using `pipenv shell` - note only do this from the project directory root5.  You can now run the program using `python main.py` or the tests using `python -m pytest`6.  Deactivate your virtual environment at any time using `exit`...

Pipenv is not perfect but it is a lot easier for most non-devs to get their head around than the alternative using pip and manual virtual environments …

Annoying issues to be aware of

Pipenv is slow when you install packages. The lock file takes a long time to process. However this extra few seconds is more than saved by not having to set up a new virtual environment manually and look up how to do that each time.
Failing to install when the package’s latest version is in preview. Some packages (e.g. installing the Python formatter ‘black’ as at August 2019) do not install cleanly. The error trace is not very helpful, so if you are having problems try adding the --pre parameter to allow it to install preview versions. For example: pipenv install --dev --pre black
Sometimes the virtual environment gets in a mess or you want to refresh everything. The easiest solution is to clean up completely and reinstall the packages in a fresh environment. Use pipenv --rm to remove the current virtual environment. Then use pipenv install --dev --pre to reinstall it fresh. This takes about 2 minutes.

Dive deeper

Useful resources on Pipenv:

Official Pipenv documentation — https://docs.pipenv.org/en/latest/
Pipenv RealPython tutorial — https://realpython.com/pipenv-guide/