GitHub Actions "pwsh: command not found" on an Ubuntu runner
A step declared "shell: pwsh" but the chosen runner image does not have PowerShell Core on PATH. GitHub-hosted Ubuntu images bundle pwsh, but custom or self-hosted runners may not.
What this error means
A step with "shell: pwsh" fails to start, reporting that pwsh cannot be found, even though "bash" steps run fine.
/usr/bin/env: 'pwsh': No such file or directory
##[error]Process completed with exit code 127.Diagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Common causes
Self-hosted or custom image without pwsh
PowerShell Core is not part of the base OS. A runner image that was not provisioned with pwsh cannot run "shell: pwsh" steps.
Step assumes Windows shell semantics
A workflow copied from a Windows job kept "shell: pwsh" even though it now runs on ubuntu-latest, where bash is the natural default.
How to fix it
Use bash on Linux runners
- Drop "shell: pwsh" and rely on the default bash shell, or set "shell: bash" explicitly.
- Translate any PowerShell cmdlets to their POSIX equivalents.
- Re-run on ubuntu-latest.
- name: Print version
shell: bash
run: cat package.json | grep '"version"'Install PowerShell if pwsh is required
- Add a step that installs PowerShell Core on the custom runner before the pwsh step.
- Confirm "pwsh --version" succeeds.
- Re-run the pwsh step.
- run: |
sudo apt-get update
sudo apt-get install -y powershell
- shell: pwsh
run: $PSVersionTable.PSVersionCatch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow to prevent it
- Match the "shell:" value to what the runner image actually ships.
- Provision pwsh in your custom runner image if workflows rely on it.