Maaz Zindani

Loading the index…

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

A GitHub Actions step with shell: pwsh or powershell fails on Linux

Errorpwsh: command not found

Short 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.

  • Applies to GitHub Actions, ubuntu-24.04 runner, PowerShell 7.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/*.yml
  2. 2Match what you see, then jump to its fix

    1. 1pwsh: 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. 2The step names powershell, not pwsh, and the runner is not WindowsThe step uses shell: powershell on a Linux or macOS runnerFix
    3. 3pwsh is missing only on some runs of the same jobA self-hosted runner label sends the job to a machine you did not expectFix

What does the error look like?

  • pwsh: command not found
  • shell: 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 powershell

3Verify

Run a step that uses pwsh and prints its version.

- name: PowerShell works
  shell: pwsh
  run: $PSVersionTable.PSVersion

Confirmed by learn.microsoft.com

Did this fix it?

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/*.yml

2Fix

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.ps1

3Verify

Re-run the job and confirm the step now starts.

gh run rerun --failed

Confirmed by docs.github.com

Did this fix it?

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/*.yml

2Fix

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 5

Confirmed by docs.github.com

Did this fix it?

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 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.