Poetry is the current best choice for Python application dependency and environment management. It uses two files

  • pyproject.toml
  • poetry.lock

to manage dependencies instead of

  • setup.py
  • requirements.txt

Set up a project

Prerequisite: pyenv

Make sure you properly setup pyenv first. Add the following to ~/.zshrc,

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
if command -v pyenv 1>/dev/null 2>&1; then
  eval "$(pyenv init -)"

and do

$ pyenv global 3.7.4

to set the global default Python version to 3.7.4.

Install poetry

Run the following command to install

$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python

Now, to make sure poetry use the right Python version, add an alias to ~/.zshrc

alias poetry="python3 $HOME/.poetry/bin/poetry"

Create a new project


$ poetry new <new_project_name>

It will create a directory <new_project_name> in the current directory.

Go inside and type tree (assuming you have tree installed, on MacOS run brew install tree) you will see

├── README.rst
├── <new_project_name>
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_<new_project_name>.py

with a prefilled pyproject.toml file:

name = "<new_project_name>"
version = "0.1.0"
description = ""
authors = ["Your name <your email>"]

python = "^3.7"

pytest = "^5.2"

requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

Note that poetry gets "Your name <your email>" from your git setting.


$ git config --global user.email <email>

to change the git email address if you need to.

Now, we can add a package, for example, flask,

$ poetry add flask

And a virtual environment will be created automatically at /Users/<username>/Library/Caches/pypoetry/virtualenvs/ by default, and flask will be installed there.

Check the lock file for detailed subdependencies.

Activate that virtual environment in shell

Run the following command to activate the virtual environment.

$ poetry shell

Set the interpreter in VSCode

As of June 2020, the Python extension in VSCode doesn’t support automatic discovery of poetry environments. Refer to this issue.

The current workaround is to add the path into VSCode setting python.venvPath,

"python.venvPath": "/Users/<username>/Library/Caches/pypoetry/virtualenvs"

Now we can see the virtual environments created by poetry in the list in VSCode.


Check the official docs for poetry commands.