Skip to main content

Supported Operating System Images

Equinix Metal™ provides a range of operating systems available for you to deploy on our platform. In general, Equinix Metal OS images are lightly modified versions of the OS cloud images tailored to be compatible with our server hardware and network configurations.

About Our Images

Changes to our OS images are tracked in equinixmetal-images/changelog. Images are kept as close to upstream releases as possible.

The changelog aims to show what packages have changed since the last published image, the kernel used in the image, and what deviations from the upstream cloud image (if any) are in the new published image.

When you provision a server using one of our OS images, you get the most recent image we have published. Once you have provisioned your server, we no longer have access, and keeping the Operating System up-to-date is your responsibility.

If we do not offer an operating system or a version of an operating system that meets your use-case, you can bring your own OS images using Custom iPXE.

Operating Systems Reference

If you would like to check whether an operating system is currently available on a specific standard or legacy server plan, use the Operating System Compatibility page.

AlmaLinux

Operating System Slug
AlmaLinux 9 alma_9
AlmaLinux 8 alma_8

Alpine Linux

Operating System Slug
Alpine 3 alpine_3

CentOS

Red Hat has set the CentOS 7 End of Life date to June 30, 2024.

Operating System Slug
CentOS 7 centos_7

Debian

Operating System Slug
Debian 12 debian_12
Debian 11 debian_11
Debian 10 debian_10

Flatcar Linux

Operating System Slug
Flatcar Linux - Stable flatcar_stable
Flatcar Linux - Beta flatcar_beta
Flatcar Linux - Alpha flatcar_alpha

FreeBSD

Operating System Slug
FreeBSD 13 freebsd_13

NixOS

On November 17, 2023 Equinix Metal is retiring NixOS. We will no longer be maintaining our NixOS images, and NixOS will no longer be an option when provisioning from the console or API. If you are still interested in running NixOS after this date, please use Custom iPXE.

Operating System Slug
NixOS 22.11 nixos_22_11
NixOS 22.05 nixos_22_05

Rocky Linux

Operating System Slug
Rocky Linux 9 rocky_9
Rocky Linux 8 rocky_8

Talos

Operating System Slug
Talos v1 talos_v1

Ubuntu

Operating System Slug
Ubuntu 22.04 LTS ubuntu_22_04
Ubuntu 20.04 LTS ubuntu_20_04
Ubuntu 18.04 LTS ubuntu_18_04

Hardware Compatibility

All of our operating system images go through a validation process in order to be provisionable on our hardware. Not all operating systems are available on every server.

Which operating systems are available on a specific server is listed on its product page and on the OS Compatibility page.

To get a list of which operating systems are available on which servers, use the metal operating-systems get command, and specify the output as JSON.

metal operating-systems get -o json

The response contains a "provisionable_on" object, which is an array of servers that operating system is provisionable on. (The example response is truncated.)

{
    "name": "AlmaLinux OS 8",
    "slug": "alma_8",
    "distro": "alma",
    "version": "8",
    "provisionable_on": [
        "a3.large.x86",
        "c2.medium.x86",
        "c3.large.arm64",
        "c3.medium.x86",
        "c3.small.x86",
        ....    
    ]
},

To get a list of which operating systems are available on which servers, send a GET request to the /operating-systems endpoint.

curl -X GET \
-H 'X-Auth-Token: <API_TOKEN>' \
"https://api.equinix.com/metal/v1/operating-systems"

The response will contain the operating system name, ID, and slug, which is useful if you are provisioning servers through the API or CLI. It will also contain "provisionable_on", which is an array of servers that operating system is provisionable on. (The example response is truncated.)

{
    "name": "AlmaLinux OS 8",
    "slug": "alma_8",
    "distro": "alma",
    "version": "8",
    "provisionable_on": [
        "a3.large.x86",
        "c2.medium.x86",
        "c3.large.arm64",
        "c3.medium.x86",
        "c3.small.x86",
        ....    
    ]
},

Provisioning a Supported Operating System

When you provision a server through the Equinix Metal console, the available operating systems are filtered by the server you choose.

On Demand Operating System Selection in the Console

Your OS options are similarly filtered if you are provisioning from your Reserved Hardware or through the Spot Market.

When provisioning servers in the CLI with the metal device create command, the required --operating-system or -O parameter is how you specify which operating system to install on the server.

metal device create -p $METAL_PROJECT_ID -m <metro> -P <plan_slug> -O <os_slug>

If you attempt to provision a server with an OS that is not compatible with the hardware, you will receive an ... is not a valid operating system error in response.

If you are provisioning servers in the API, the operating_systems field is where you specify which OS to install on your server. It is also a required field.

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Auth-Token: <API_TOKEN>" \
"https://api.equinix.com/metal/v1/projects/{id}/devices" \
-d '{
    "metro": "<metro>",
    "plan": "<plan_slug>",
    "operating_system": "<os_slug>"
}'

If you attempt to provision a server with an OS that is not compatible with the hardware, you will receive an ... is not a valid operating system error in response.

End-of-Life Images

When an operating system image is end-of-life, you will no longer be available to provision it on new servers through the console or the API. Servers currently running end-of-life operating systems will continue to run normally.

Copied code to clipboard