A Helpful Guide to Solving Common Poetry Issues

We don't often use Poetry, the Python packaging and dependency management tool, but when we do, we usually look up and re-learn the same things repeatedly. This post is a quick reference for some of the recent issues we encountered when using Poetry.

Installing Poetry with pipx

If you don't already have Poetry installed, you can install it with pipx:

brew install pipx
pipx install poetry
pipx ensurepath

You can also install Poetry with pip instead of pipx, but we prefer pipx, since it installs and manages packages in isolated environments.

Don't set virtualenvs.create=false

Currently, we use direnv for most projects to automatically activate virtual environments when we cd into the project directory. We used to set virtualenvs.create to false in my pyproject.toml file to prevent Poetry from creating a virtual environment for each project and to use the environment managed by direnv instead. This works sometimes, but we've found it can cause problems with some Poetry commands.

By default, Poetry creates a virtual environment for each project. This is usually what you want. Just set poetry config virtualenvs.create true.

Choosing a Python version

You can specify the Python version for your project in the pyproject.toml file. Here's an example:

[tool.poetry.dependencies]
python = "^3.8"

This tells Poetry to use Python 3.8 or later for the project.

But what if you want to use a different version of Python for development? You can use the poetry env use command to set the Python version for the project's virtual environment. For example, to use Python 3.10, you can run:

poetry env use 3.10

Updating a package not listed in pyproject.toml

We were encountering an issue with a package that was not listed in the pyproject.toml file:

TypeError: canonicalize_version() got an unexpected keyword argument 'strip_trailing_zero'

Turns out this was related to a setuptools/packaging (pypa/setuptools#4483) issue. The solution was to update the packaging package to a version that included the fix. We were able to do this with the following command:

poetry update packaging

We weren't sure how to do this at first since the package wasn't listed in the pyproject.toml file, but this command worked, and will update the lock file and the package in the virtual environment.

Upgrading packages selectively

Sometimes you want to upgrade several packages, not all of them. You can do this with the poetry add command. For example:

poetry add --group dev "kubernetes-validate<1.31"

You can also use the poetry add command to upgrade several packages to the latest versions:

poetry add "boto3@latest" "awscli@latest" "botocore@latest"

Conclusion

Poetry is a powerful tool for managing Python projects. Hopefully, this post helps you past some of the common issues you might encounter when using Poetry. If you have any tips or tricks for using Poetry, please share them in the comments below.