Skip to content
code

GitHub Action

Setup and Install Poetry

v2.0.2 Latest version

Setup and Install Poetry

code

Setup and Install Poetry

Install and set up the Poetry build tool

Installation

Copy and paste the following snippet into your .yml file.

              

- name: Setup and Install Poetry

uses: pronovic/setup-poetry@v2.0.2

Learn more about this action in pronovic/setup-poetry

Choose a version

setup-poetry

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

Design

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".

Usage

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.

Configuration

The action accepts a small set of input parameters.

Input Required? Default Description
version Yes The version of Poetry to install; supports v1.8.0 or newer.
plugins No empty A comma-separated list of Poetry plugins to install; each comma-separated value must be valid input for pipx inject poetry
cache-venv No "false" Whether to cache the project virtual environment under .venv; a string "true" or "false"
cache-poetry No "false" Whether to cache the Poetry runtime & cache directories under .poetry; a string "true" or "false"
cache-suffix No "000" Suffix to use for the cache keys, which can be used to reset the caches if necessary
max-workers No unset The maximum number of Poetry workers, if the default of 4x cores is too large for your GHA runners; ignored if unset
disable-keyring No "true" Whether to globally disable the Python keyring via Poetry configuration; a string "true" or "false"

Environment

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

Variable Description
PYTHON_VERSION The full version of the Python interpreter on the path as python, like 3.10.7
POETRY_VERSION The version of Poetry that was installed, like 1.8.0
POETRY_CONFIG_DIR Path to the Poetry configuration directory, within the GitHub Actions workspace
POETRY_HOME Path to the Poetry runtime install directory, within the GitHub Actions workspace
POETRY_CACHE Path to the Poetry cache directory, within the GitHub Actions workspace