# install-poetry: a GitHub action that sets up Poetry properly

> The install-poetry action is a small piece of shell and YAML that installs Poetry on a GitHub runner, puts its executables on the system path and applies the config settings a CI job usually wants, including a virtualenv layout you can cache between runs.

**snok/install-poetry** — Github action for installing and configuring Poetry

- Repository: https://github.com/snok/install-poetry
- Stars: 624 · Forks: 56
- Language: Shell
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/snok-install-poetry

## What the action actually does

install-poetry is a GitHub action for installing and configuring Poetry, and the overview states its three jobs in one sentence. It installs Poetry, it adds the executables to the runner system path, and it sets the relevant Poetry config settings. That last part is the one that matters in practice, because installing Poetry on a runner is easy and having it configured correctly for a project is where the friction usually is. A job that installs Poetry by hand ends up with a virtualenv in whatever place the Poetry version of the day decides, and a cache step that assumes a particular path quietly stops working. The action exists to make that path explicit. The implementation is a shell script, main.sh, with an action.yml describing the inputs, and the project is MIT licensed with the last push to the repository on 2026-07-20 and a release line that reached v1.4.2 on 2026-05-30.

## The shortest possible usage

If you want default Poetry and nothing else, the declaration is two lines in your workflow.

```yaml
- name: Install Poetry
  uses: snok/install-poetry@v1
```

That is the whole integration. There is no separate setup step, no pip invocation and no requirement to know where the installer puts things, because the action handles the path itself. The version tag is v1, so the action follows the v1 line, and the repository's own workflow examples use the same form. The project is tested for macOS and Ubuntu runners on Poetry versions of 1.8 or newer, and for Windows it points at a separate section of the documentation rather than claiming the same coverage.

## The inputs, and what the defaults actually are

When you need config settings or a specific Poetry version, the inputs are declared under with.

```yaml
- name: Install and configure Poetry
  uses: snok/install-poetry@v1
  with:
    version: 2.4.1
    virtualenvs-create: true
    virtualenvs-in-project: false
    virtualenvs-path: ~/my-custom-path
    installer-parallel: true
```

The defaults are worth reading before you write any of them, because two of them are already on and one is already off.

```yaml
version: latest
virtualenvs-create: true
virtualenvs-in-project: false
virtualenvs-path: {cache-dir}/virtualenvs
installer-parallel: true
```

So a virtualenv is created by default, it is not created inside the project by default, it lives under the Poetry cache directory by default, and the installer runs in parallel by default. The version input defaults to latest, which is the input you should think hardest about pinning, since a Poetry release that changes behaviour will otherwise land in your CI on a day you did not choose. The two virtualenv inputs are the ones that decide where a cache step will look.

## Pointing the installer at a specific commit

If you need extra arguments passed to the installer script, there is an input for it, and the documented example uses it to install from a git URL at a pinned commit.

```yaml
- name: Install and configure Poetry
  uses: snok/install-poetry@v1
  with:
    installation-arguments: --git https://github.com/python-poetry/poetry.git@19a2f7bddb9bdf931a229ea0913a84021f3f9b93
```

This is the escape hatch for teams that need a specific Poetry build, for instance a fork with a patch, and it is also the only documented way to control the installer's own flags. Anything that the config inputs do not cover can be set after the fact instead, in a later step, and the documentation shows that pattern for the experimental config settings and for changes that have to happen after the action has run.

```yaml
- uses: snok/install-poetry@v1
- run: poetry config virtualenvs.prefer-active-python true
```

The order of those two steps is the point. The action has to have run before the config command, and putting the config in a separate step rather than fighting the inputs is the intended way to do it.

## The caching pattern, which is the real reason to use it

The workflow examples section is where the action earns its place, and the first example is a test job that checks out the repository, sets up Python, installs Poetry with the virtualenv placed in the project directory, then caches that .venv against a key built from the operating system, the Python version and a hash of the poetry.lock file. The install step is then conditional on whether the cache hit, and the project is installed separately from the dependencies with poetry install --no-interaction --no-root followed by poetry install --no-interaction for the root project. That ordering has a purpose, and it is the one piece of configuration people usually get wrong. The path in the cache step and the virtualenvs-path you pass to the action have to be the same path, which is why the example sets virtualenvs-path to .venv while the cache action uses path: .venv. The cache key hashes poetry.lock, so a dependency change invalidates the environment and a lock file that has not changed restores it.

## Matrix builds, plugins and Windows

The documentation also covers a matrix workflow that runs the test suite across combinations of operating system, Python version and package version, with a separate linting job that has nothing to do with the matrix and is included for inspiration. There are further sections on uploading coverage, on caching the Poetry installation itself, on installing Poetry plugins, and on the variations of virtualenv setup, including a section for caching on Windows runners. That last one is the gap to know about. The action is fully tested for macOS and Ubuntu runners on Poetry 1.8 and later, and Windows is handled by a section of its own, so a Windows matrix entry will need the extra steps described there rather than the same declaration working unchanged. The project also ships a poetry.lock and a pyproject.toml for its own tests, with pytest as the test dependency and a build backend of poetry-core, which means the action tests itself with the tool it installs.

## Conclusion

install-poetry fits a GitHub Actions workflow that runs Python tests with Poetry and wants the same setup on every runner, since the action handles the path, the config and the virtualenv location in one declaration, and it fits teams that cache their virtualenv between runs, which the action is built to make possible. It does not fit a Windows job that wants the same treatment without extra work, because the action is fully tested for macOS and Ubuntu runners and the documentation has a separate section for Windows, including how to cache on Windows runners. It also does not fit a workflow that wants Poetry from a fork or a specific commit, unless you use the installation-arguments input to point the installer at a git URL. Before you adopt it, read the defaults, because virtualenvs-create and installer-parallel are on by default while virtualenvs-in-project is off, and if you cache a virtualenv you need the path to match the cache path, as the example workflow shows.

## FAQ

### How do I install Poetry in a GitHub Actions workflow?

Add a step that uses snok/install-poetry@v1. The action installs Poetry, adds the executables to the runner system path and sets the relevant Poetry config settings, and it is fully tested for macOS and Ubuntu runners on Poetry versions of 1.8 and newer.

### What are the default settings of the install-poetry action?

The version defaults to latest, virtualenvs-create is true, virtualenvs-in-project is false, virtualenvs-path is the virtualenvs directory under the cache directory, and installer-parallel is true. Each of these can be overridden through the with inputs.

### How do I cache the virtualenv between runs?

Set virtualenvs-in-project to true and virtualenvs-path to the same directory the cache action uses, then key the cache on the operating system, the Python version and a hash of poetry.lock. The documented example uses .venv as the path and installs dependencies only when the cache misses.

### Does install-poetry work on Windows runners?

The action is fully tested for macOS and Ubuntu runners, and the documentation has a separate Running on Windows section, including a subsection on caching on Windows runners, so a Windows job needs the steps described there rather than the same declaration.

## Sources

- [Issues](https://github.com/snok/install-poetry/issues)
- [License: MIT](https://github.com/snok/install-poetry/blob/main/LICENSE)
- [README](https://github.com/snok/install-poetry/blob/main/README.md)
- [Releases](https://github.com/snok/install-poetry/releases)
- [snok/install-poetry on GitHub](https://github.com/snok/install-poetry)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/snok-install-poetry