Python virtualenv management with pyenv and Poetry

This is a summary of the workflow for managing Python virtual environments using more-modern tools than my usual combo of virtualenv and pip.



Use pyenv to install different versions of Python on a host easily, and enable easy switching between them. Install pyenv:

curl | bash

Add the following lines to .bashrc:

export PATH="~/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Use pyenv to install different Python versions:

pyenv install 3.7.7
pyenv install 3.8.2

Set a 'default' Python version to be used upon changing to a project directory:

pyenv local 3.7.7

Don't add the .python-version file to the repository (this is a local setting); add it to .gitignore if necessary. If pyenv is configured properly, the presence of .python-version will cause it to activate the virtualenv automatically when you change into that directory.


pyenv comes with virtualenv but instead of that, use Poetry to manage virtual environments and dependencies. Install Poetry:

curl -sSL | python

Add the following line to .bashrc:

source ~/.poetry/env

Inside the project directory, initialise the project dependencies:

poetry init

Add the pyproject.toml file to the project repository. Use poetry new instead to initialise a brand new project repository instead of poetry init.

Set up a new virtual environment for the project:

poetry install

Add the poetry.lock file the the project repository, as this keeps track of installed library versions. Add new project dependencies (this will automatically update pyproject.toml and poetry.lock):

poetry add requests
poetry add Django==3.0.5
postry add --dev ipython ipdb

List the Poetry-managed virtual environments available to the project:

poetry env list
poetry env info

Run python scripts in the virtual environment by preceding them with poetry run:

poetry run python