Pipenv

Note: I do not use pipenv. There are too many problems (a quick Internet search will give you a good sampling).

Pipenv docs

From the docs:

It automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your Pipfile as you install/uninstall packages. It also generates the ever-important Pipfile.lock, which is used to produce deterministic builds.

Pipenv documentation

There’s a lot of information on the pipenv web site. Unfortunately, as I remarked to a friend once, it’s as if someone wrote all the thoughts they had about pipenv on note cards, threw them up in the air, and added them to the site in the order they fell. In other words, it’s difficult to navigate or find the information you want.

Here’s an attempt at a useful table of contents.

• Installation and configuration

  • Installation

  • Shell configuration

  • Configuration with environment variables

  • Configuring where virtualenvs are created

  • Shell completion

  • Changing cache location

  • Changing default Python versions

  • Show venv name in shell prompt

• Converting an existing project

  • Importing from requirements.txt

• General day-to-day usage

  • Install, uninstall, and lock

  • What to keep in version control

  • Deployment

  • Pipfile v. setup.py

• Reference

  • Pipenv command reference

    • Most of these “options” are basically additional commands, except there’s no documentation other than the one-liners included here, so I haven’t bothered giving links for these:

      • --where - output project home information

      • --venv - output virtualenv information

      • --py - output Python interpreter information

      • --envs - Output Environment Variable options.

      • --rm - remove the virtualenv

      • --bare - minimal output

      • --completion - output completion (to be executed by the shell)

      • --man - display manpage

      • --support - Output diagnostic information for use in GitHub issues.

      • --site-packages, --no-site-packages - Enable or disable site-packages for the virtualenv.

      • --python <python> - Specify which version of Python virtualenv should use.

      • --three, --two - Use Python 3/2 when creating virtualenv.

      • --clear - Clears caches (pipenv, pip, and pip-tools).

      • -v, --verbose - verbose mode

      • --pypi-mirror <pypi-mirror>

      • --version - show the version and exit

    • check - Checks for PyUp Safety security vulnerabilities and against PEP 508 markers provided in Pipfile.

    • clean - Uninstalls all packages not specified in Pipfile.lock.

    • graph - Displays currently-installed dependency graph information.

    • install - Installs provided packages and adds them to Pipfile, or (if no packages are given), installs all packages from Pipfile.

    • lock - Generates Pipfile.lock

    • open - View a given module in your editor.

    • run - Spawns a command installed into the virtualenv.

    • scripts - Lists scripts in current environment config.

    • shell - Spawns a shell within the virtualenv.

    • sync - Installs all packages specified in Pipfile.lock.

    • uninstall - Uninstalls a provided package and removes it from Pipfile.

    • update - Runs lock, then sync.

  • Specifying package versions

  • Specifying python versions

  • Specifying exactly which python to use

  • Making system-installed packages accessible in virtualenv

  • Fine-tune which systems packages are installed on

  • Editable dependencies

  • VCS dependencies

  • Package sources

    • Specifying package indexes

    • Mirrors

    • Credentials

  • Integrations with IDEs and editors

  • Custom script shortcuts in Pipfile

• Troubleshooting

• Examples

  • Example Pipfile and Pipfile.lock

  • Example workflow

  • Example upgrade workflow

  • Example generating requirements.txt

  • Detecting security vulnerabilities

  • Automatically installing Python versions with pyenv

  • Automatic loading of .env files

  • Testing projects

  • Using pipenv to run programs under supervisor

Installing pipenv

You need to install pipenv OUTSIDE your project’s virtual environment AND if at all possible, not as part of your system packages.

I like to use pipx.

More instructions for installing pipenv.

Virtualenvs

There’s no command to create a virtualenv. Pipenv just creates one as soon as one is needed.

EXCEPT, if pipenv detects that it is running inside a virtualenv, it uses that one. So there’s a kind of escape hatch: create a virtualenv anyway/anywhere you want, install pipenv into it, then activate it, and pipenv will use it. (Set PIPENV_IGNORE_VIRTUALENVS to disable that behavior.)

Pipenv generates a name for each virtualenv based on the project directory path and a hash. So if you move your project, pipenv will no longer find that virtualenv and will have to create a new one.

If PIPENV_VENV_IN_PROJECT=1 is set, pipenv creates your virtualenv under your project directory, in a directory name .venv.

Otherwise, if WORKON_HOME is set, pipenv creates virtualenvs under that directory.

WORKON_HOME can be set to a relative directory. For example, if I set it to .., it generates a virtualenv name as usual and creates it under the parent directory, beside my project directory.

If neither PIPENV_VENV_IN_PROJECT nor was set, it created them for me under ~/.local/share/virtualenvs. Since I have pipenv installed under ~/.local/bin, I wonder if that path is connected to where pipenv is installed, or is always that path?

Note

is there a way to tell pipenv to use some other algorithm to generate the path to the virtualenv?

You can delete a virtualenv with pipenv --rm.

There’s no command (that I’ve found) to prune old ones. That’s on you.

Converting from a requirements file

Just run “pipenv install [-r requirementsfile]” and it’ll see that there’s no Pipfile but a requirements file, and will generate a new Pipfile and .lock file for you. Then edit the Pipfile to clean it up.

Starting a new project

Just change to the project directory and start using pipenv install <packagespec> [<packagespec>...] to install packages. Pipenv will create a Pipfile and Pipfile.lock the first time, and update it as you install more packages.

Creating a requirements file

Do this:

pipenv lock --requirements >non-dev-requirements.txt
pipenv lock --requirements --dev >only-dev-requirements.txt

Keeping dev-only packages out of production

1. Add dev-only packages using pipenv install --dev <packages>

2. For development, install using pipenv install --dev

3. In production, leave off the --dev