A GitHub Actions step with shell: pwsh or powershell fails on Linux
pwsh: command not foundShort answer
GitHub starts a step with the shell name you give. On a hosted Ubuntu runner pwsh is preinstalled, so the error means the job runs somewhere else (a container or a self-hosted runner without PowerShell), or the step asks for powershell, which exists only on Windows. Install PowerShell 7 there, or change the shell to pwsh or bash.
Fix it fast
1Find out which cause you have
Find where the job runs and which shell the step asks for. The runs-on, container and shell lines in the workflow decide everything.
grep -n -E 'runs-on|container:|image:|shell:' .github/workflows/*.yml2Match what you see, then jump to its fix
- 1
pwsh: command not found, while the same step works on a plain ubuntu-24.04 jobThe job runs in a container or on a self-hosted runner that has no PowerShellFix - 2
The step names powershell, not pwsh, and the runner is not WindowsThe step uses shell: powershell on a Linux or macOS runnerFix - 3
pwsh is missing only on some runs of the same jobA self-hosted runner label sends the job to a machine you did not expectFix
- 1
What does the error look like?
pwsh: command not foundshell: powershell on a Linux runner
Cause 1 of 3
The job runs in a container or on a self-hosted runner that has no PowerShell
1Check
The hosted Ubuntu 24.04 image lists PowerShell among its tools, but a container image or your own runner machine is a different system. Run the check inside that environment.
- name: Is pwsh here?
run: command -v pwsh || echo "pwsh is missing"2Fix
Install PowerShell 7 from the Microsoft package repository in an earlier step (or bake it into your image). For a one-off, a bash step is simpler.
- name: Install PowerShell
run: |
sudo apt-get update
sudo apt-get install -y wget apt-transport-https software-properties-common
source /etc/os-release
wget -q https://packages.microsoft.com/config/ubuntu/$VERSION_ID/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y powershell3Verify
Run a step that uses pwsh and prints its version.
- name: PowerShell works
shell: pwsh
run: $PSVersionTable.PSVersionConfirmed by learn.microsoft.com
Cause 2 of 3
The step uses shell: powershell on a Linux or macOS runner
1Check
The workflow syntax reference lists powershell as Windows only. pwsh is the cross-platform PowerShell Core.
grep -n -B2 -A2 'shell: powershell' .github/workflows/*.yml2Fix
Change the shell to pwsh. If the script uses Windows PowerShell 5.1 only features, run that job on a Windows runner instead.
- name: Run script
shell: pwsh
run: ./scripts/build.ps13Verify
Re-run the job and confirm the step now starts.
gh run rerun --failedConfirmed by docs.github.com
Cause 3 of 3
A self-hosted runner label sends the job to a machine you did not expect
1Check
Self-hosted runners must match every label in runs-on, and GitHub makes no promise about the software on them. A second runner with the same labels may lack PowerShell.
grep -n 'runs-on' .github/workflows/*.yml2Fix
Give the PowerShell-ready machine a custom label and target it in runs-on, or install PowerShell on every runner that carries the label.
jobs:
build:
runs-on: [self-hosted, linux, x64, has-pwsh]3Verify
Run the job several times and confirm all runs land on a machine with pwsh.
gh run list --workflow build.yml --limit 5Confirmed by docs.github.com
How do I stop it coming back?
- Use pwsh, not powershell, in cross-platform workflows.
- Put required tools in your container image or runner image instead of installing them in every run.
- Add a command -v check as the first step of jobs that run on your own machines.
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
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 fixServers
poetry command not found right after installing it in a GitHub Actions step
Poetry installs without error in one step, and the next step cannot find it
The official installer puts the poetry command in $HOME/.local/bin, which is not always on PATH.
3 causes, each with a fix