poetry command not found right after installing it in a GitHub Actions step
poetry: command not foundShort 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.
Fix it fast
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"2Match what you see, then jump to its fix
- 1
ls shows poetry in $HOME/.local/bin, but poetry --version failsThe install directory is not on PATHFix - 2
export 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
The install step sets POETRY_HOME, and $HOME/.local/bin has no poetryPOETRY_HOME moved the wrapper to another folderFix
- 1
What does the error look like?
poetry: command not foundPoetry 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 --version3Verify
The step after the install prints a Poetry version.
poetry --versionConfirmed by python-poetry.org
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/*.yml2Fix
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 install3Verify
Both the full-path call and the later plain poetry call succeed.
poetry --versionConfirmed by docs.github.com
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 --versionConfirmed by python-poetry.org
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 local composite action in GitHub Actions cannot be found
The action folder is in the repository but the runner reports that its action.yml cannot be found
A local action is read from the checked-out repository.
3 causes, each with a fixServers
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 fixServers
A GitHub Actions step with shell: pwsh or powershell fails on Linux
shell: powershell on a Linux runner
GitHub starts a step with the shell name you give.
3 causes, each with a fixServers
Make a GitHub Actions step run after a failure, and keep the job failed
The job is green even though a step failed (continue-on-error)
A step with no if: condition gets success() by default, so it is skipped once any earlier step fails.
3 causes, each with a fixServers
A self-hosted GitHub Actions runner goes offline or stops by itself
Runner status in Settings > Actions > Runners shows Offline
GitHub marks a runner Offline when the machine is down, the runner application is not running, or it cannot reach GitHub.
3 causes, each with a fixServers
GitHub Actions step fails writing to GITHUB_OUTPUT
Error: Invalid format '...'
The runner reads GITHUB_OUTPUT line by line, and every entry must be name=value or a name<<DELIMITER block.
3 causes, each with a fix