Shared GitHub Action to install and set up the Poetry build tool for Python. It is available in the GitHub Marketplace at no cost.

This action is similar to snok/install-poetry, but it takes a slightly different approach. It is also more opinionated, offering access to fewer of Poetry's underlying configuration options in favor of typical defaults. Poetry >= 1.8.0 is installed using pipx, which is now the recommended installation method.

When using this action, the Poetry runtime, cache, and configuration directories as well as the project virtual environment are always created within the GitHub Actions workspace. Poetry is installed and configured under .poetry and the virtualenv is created under .venv. This has implications for some tools; for instance, you may need to configure code formatters like Black to ignore these two directories.

Unlike with the snok action, you are required to specify a version of Poetry to install. The action will never install the latest version of Poetry by default. You may also specify a list of Poetry plugins to install.

You may optionally cache the project virtual environment and/or the Poetry runtime and cache directories. Caching is implemented via actions/cache and provides a huge improvement in build times. Caching has been tested on all of the standard GitHub Actions platforms: Linux, MacOS, and Windows. If you need to reset the cache for some reason, you can force this by changing the cache-suffix input value, which defaults to "000".

To use the action, add a stanza like this to your GitHub Actions workflow:

- name: Setup Poetry
  uses: pronovic/setup-poetry@v2
  with:
    version: "1.8.0"
    plugins: "poetry-dynamic-versioning==1.2.0"
    cache-venv: "true"
    cache-poetry: "true"

The poetry command will be available on the system $PATH, and you can also reference the other environment variables discussed below.

The action accepts a small set of input parameters.

The action exports a set of environment variables to the GitHub Actions environment.