Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

poetry command not found right after installing it in a GitHub Actions step

Errorpoetry: command not found

Short answer

The official installer puts the poetry command in $HOME/.local/bin, which is not always on PATH. Adding it with export works only inside one step. Write the directory to $GITHUB_PATH so later steps see it, or call poetry by its full path.

  • Applies to GitHub Actions ubuntu runner, Poetry 2 installer
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    In the failing job, print whether the install directory is on PATH and where Poetry really is.

    - run: |
        echo "$PATH"
        ls -la "$HOME/.local/bin"
  2. 2Match what you see, then jump to its fix

    1. 1ls shows poetry in $HOME/.local/bin, but poetry --version failsThe install directory is not on PATHFix
    2. 2export PATH worked in the install step but not in the next one, or GITHUB_PATH was written and poetry is called in that same stepPATH is changed and used in the same stepFix
    3. 3The install step sets POETRY_HOME, and $HOME/.local/bin has no poetryPOETRY_HOME moved the wrapper to another folderFix

What does the error look like?

  • poetry: command not found
  • Poetry installs without error in one step, and the next step cannot find it

Cause 1 of 3

The install directory is not on PATH

1Check

The installer's wrapper lives in $HOME/.local/bin on Unix, and Poetry's docs tell you to add that folder to PATH if it is missing.

- run: |
    curl -sSL https://install.python-poetry.org | python3 -
    ls -la "$HOME/.local/bin/poetry"

2Fix

Append the directory to the file named by GITHUB_PATH. It prepends the folder to PATH for the following steps of the job.

- name: Install Poetry
  run: |
    curl -sSL https://install.python-poetry.org | python3 -
    echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Check
  run: poetry --version

3Verify

The step after the install prints a Poetry version.

poetry --version

Confirmed by python-poetry.org

Did this fix it?

Cause 2 of 3

PATH is changed and used in the same step

1Check

A change written to GITHUB_PATH is available only to later steps. The step that writes it cannot use it, and a plain export lives only until that step ends.

grep -n -E 'GITHUB_PATH|export PATH|poetry ' .github/workflows/*.yml

2Fix

Put the PATH line in its own step, or the install step, and run poetry commands in later steps. In the install step itself, use the full path.

- run: |
    curl -sSL https://install.python-poetry.org | python3 -
    echo "$HOME/.local/bin" >> "$GITHUB_PATH"
    "$HOME/.local/bin/poetry" --version
- run: poetry install

3Verify

Both the full-path call and the later plain poetry call succeed.

poetry --version

Confirmed by docs.github.com

Did this fix it?

Cause 3 of 3

POETRY_HOME moved the wrapper to another folder

1Check

With POETRY_HOME set, the wrapper goes into $POETRY_HOME/bin instead. Poetry itself is installed under ~/.local/share/pypoetry by default.

- run: echo "POETRY_HOME=$POETRY_HOME"; ls "$POETRY_HOME/bin"

2Fix

Add $POETRY_HOME/bin to GITHUB_PATH instead of $HOME/.local/bin.

- run: |
    curl -sSL https://install.python-poetry.org | POETRY_HOME=$HOME/poetry-home python3 -
    echo "$HOME/poetry-home/bin" >> "$GITHUB_PATH"

3Verify

poetry --version works in the next step.

poetry --version

Confirmed by python-poetry.org

Did this fix it?

How do I stop it coming back?

  • Add the PATH entry in the same step that installs the tool, using GITHUB_PATH.
  • Call poetry --version in the next step as a quick check.
  • Pin the Poetry version the installer fetches so the layout does not change under you.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

A GitHub Actions workflow builds the Docker image but cannot push it

The push step fails right after the login step

Four things stop a push from GitHub Actions: build-push-action does not push unless push is true, the Docker Hub login used a password instead of an access token, the workflow token lacks packages write for ghcr.io, or the run comes from a fork, where the token is read-only.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.