Skip to content

Poetry⚓︎

Install Poetry⚓︎

First, install Poetry. This can be done through

See https://python-poetry.org/docs/#installation

brew install poetry

pip install poetry

To ensure Poetry is up-to-date, run

poetry self update

Then, navigate to the project's root directory, and create the virtualenv environment with

poetry env use 3.10  # (1)
  1. This project also supports 3.11 - 3.13 if you want to use those instead.

In future sessions (on the CLI), you can enter the environment by navigating to the project's root directory and running

poetry shell

Decoupling Python and Poetry installs⚓︎

When installing Poetry, it will usually bundle a Python install. But when using Homebrew, it tends to automatically update Poetry and the Python dependency. If it upgrades the minor Python version - like 3.10 -> 3.11 - it can break an existing environment.

As such, it is best practice to decouple the Python install from Poetry. pyenv is a great, simple tool to manage Python installations.

brew install pyenv

See https://github.com/pyenv/pyenv#installation.

Then install a specific Python version. The executable path can be found with

pyenv which python

which can be used as the interpreter for the Poetry environment with

poetry env use "$(pyenv which python)"

Now you should have a static path to a specific Python install.

Tip

Run poetry config virtualenvs.in-project true to store the virtualenv in the project directory. This is useful if you want full visibility of the environment, instead of it being hidden elsewhere on your filesystem.

Install the project⚓︎

To install everything from this project's Poetry configuration, run

poetry install

To only install the core dependencies, instead run

poetry install --without dev,test,docs

Since it will create a virtualenv environment for you, you don't need to run it in conjunction with another environment manager, such as conda.

  1. Open the project
  2. Click Add New Interpreter -> Add Local Interpreter... -> Poetry Environment
  3. Check Existing environment. The environment you just created should appear in the dropdown menu

Creating your own configuration⚓︎

To create your own Poetry configuration in pyproject.toml, run

poetry init

and follow the instructions. Then to port any dependencies from requirements.txt and requirements-dev.txt, run

cat requirements.txt | grep -E '^[^# ]' | cut -d= -f1 | xargs -n 1 poetry add
cat requirements-dev.txt | grep -E '^[^# ]' | cut -d= -f1 | xargs -n 1 poetry add --group dev

Dependencies can be segmented into different groups. See pyproject.toml.

It is recommended to maintain dependencies with Poetry, and export them (1) to requirements.txt and requirements-dev.txt if needed (2), e.g.,

  1. Exporting dependencies may require the plugin poetry-plugin-export. Install it with poetry self add poetry-plugin-export
  2. Check out quality#pre-commit for a pre-commit hook to do this automatically.
poetry export --without-hashes -f requirements.txt -o requirements.txt
poetry export --without-hashes --only dev -f requirements.txt -o requirements-dev.txt

This repo separates development dependencies into dev, tests, and docs groups. To export these, run

poetry export --without-hashes --only dev,test,docs -f requirements.txt -o requirements-dev.txt