Skip to content
Get packs

Guide · Open source

How to use runner-images: pick the right GitHub Actions runner label

Updated · written with AI from the project's own documentation and checked against our catalogue data

actions/runner-images is the MIT-licensed PowerShell source repository that builds the virtual machine images behind GitHub-hosted runners for Actions, and the Microsoft-hosted agents used in Azure Pipelines. This guide is for maintainers and teams who want to know exactly what software a hosted runner includes, and which label to request for a macOS, Ubuntu or Windows job. By the end you will know how to read the image list, choose a label, and find where to clone the repo if you want to work on the images themselves.

GitHub Actions runner imagesactions/runner-images · ★ 13.6k · MIT

Quick start

  1. 1Decide what you need. List the software your job requires, such as specific tools or an OS version.
  2. 2Open the Available Images table. Find the row that matches your OS and architecture in the README.
  3. 3Check the included software. Follow the link in the Included Software column to see the preinstalled tools for that image.
  4. 4Choose a label. Copy a YAML label from the table, preferring a versioned label if you need a stable image.
  5. 5Set runs-on in your workflow. Put the chosen label in the runs-on field of your GitHub Actions job.
  6. 6Clone the repo if you want to contribute. Run git clone https://github.com/actions/runner-images to get the source and its build instructions.

Understand what this repository is for

This repository contains the source code used to create the VM images for GitHub-hosted runners used for Actions. It also covers the images used for Microsoft-hosted agents in Azure Pipelines.

You do not install this repo to run a CI job. You use the images it builds by choosing a runner label in your workflow.

  • Use it to see what software is preinstalled on a GitHub-hosted runner.
  • Use it to find the right label for a macOS, Ubuntu or Windows job.
  • Use it to propose or track changes to the software included in the images.

Find the right runner label for your job

The README has an Available Images table. Each row lists an image, its architecture, its YAML label and a link to the list of included software. Find the OS and architecture you need, then copy one of the labels from the YAML Label column into the runs-on field of your workflow.

Some images have more than one label. For example, the Ubuntu 24.04 x64 image can be requested as ubuntu-latest or ubuntu-24.04.

  • Ubuntu x64 images use labels such as ubuntu-24.04 and ubuntu-22.04; Arm64 images use labels ending in -arm, such as ubuntu-24.04-arm.
  • macOS arm64 images use labels such as macos-latest, macos-26 or macos-26-xlarge.
  • Windows images use labels such as windows-latest, windows-2025 or windows-2022.
  • The -xlarge and -large suffixes are unique to macOS images and are only available for GitHub Actions.
runs-on: ubuntu-24.04

Check which software an image includes

Each image row links to a Readme file in the images folder of the repo. These files list the software included in that image. Open the link for the image you plan to use before you rely on a tool being present.

The README also notes that the -latest label points to the latest OS image version that is generally available. Before the label moves to a new OS version, the change is announced so you have time to update workflows.

Clone the repository

To work with the source, clone the repository. The README lists no separate prerequisites for this step. To build a VM image from the source, the README points to a separate instructions file, docs/create-image-and-azure-resources.md.

git clone https://github.com/actions/runner-images

Track changes and announcements

Notable upcoming changes are posted as issues with the Announcement label. Image previews and deprecations are also tracked as issues, and the table marks preview and deprecated images with badges that link to those issues.

If you want to propose a change to the software in an image, the repository is where that discussion happens.

What people use it for

  • Confirming that a macOS image includes the Xcode version your iOS build needs before you pick a label.
  • Choosing ubuntu-24.04-arm for a job that must run on Arm64 Linux.
  • Tracking deprecations of macOS 14 images before a workflow breaks.
  • Proposing a change to the software included in an Ubuntu or Windows image.

Frequently asked questions

Do I need to install runner-images to use GitHub Actions runners?

No. The repository holds the source used to build the images. You use them by setting a runner label such as ubuntu-latest or macos-26 in your workflow's runs-on field.

Is runner-images free to use?

The repository is licensed under the MIT licence, as stated in its metadata. Check the LICENSE file in the repo for the full terms.

What is the difference between a runner label and an image?

An image is the virtual machine built from this repo's source. A label is the name you put in your workflow to request that image. Several labels can point to the same image.

Which label should I use for macOS?

Use macos-latest for the latest generally available Arm64 macOS image, or a versioned label such as macos-26 if you need a fixed version. Intel x64 images use labels such as macos-26-intel or macos-15-intel.

Can I use runner-images to run self-hosted runners?

No, this repo is not the way to set up self-hosted runners. The README only links to separate self-hosted runner documentation.

Are there alternatives to runner-images?

The source does not name alternatives, so this guide does not list any. To see what a hosted runner includes, read the Readme file linked for each image in the table.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this repository if you need to know exactly what is preinstalled on a GitHub-hosted macOS, Ubuntu or Windows runner, or you want to propose changes to those images. If you only want to run a CI job, you do not need to clone it: pick a runner label in your workflow and use the image directly.

Install options & downloads