> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Custom Talos Images

> How to build a custom Talos image from source.

export const release_v1_13 = 'v1.13.1';

export const VersionWarningBanner = () => {
  const latestVersion = "v1.13";
  const [latestUrl, setLatestUrl] = useState(null);
  const [currentVersion, setCurrentVersion] = useState(null);
  const [isBeta, setIsBeta] = useState(false);
  const parseVersion = v => v.replace("v", "").split(".").map(Number);
  const isGreaterVersion = (a, b) => {
    const [aMajor, aMinor] = parseVersion(a);
    const [bMajor, bMinor] = parseVersion(b);
    if (aMajor > bMajor) return true;
    if (aMajor === bMajor && aMinor > bMinor) return true;
    return false;
  };
  useEffect(() => {
    if (typeof window === "undefined") return;
    const {pathname, hash, search} = window.location;
    const match = pathname.match(/\/talos\/(v\d+\.\d+)\//);
    if (!match) return;
    const detectedVersion = match[1];
    if (detectedVersion === latestVersion) return;
    setCurrentVersion(detectedVersion);
    if (isGreaterVersion(detectedVersion, latestVersion)) {
      setIsBeta(true);
    }
    const newPath = pathname.replace(`/talos/${detectedVersion}/`, `/talos/${latestVersion}/`);
    setLatestUrl(`${newPath}${search}${hash}`);
  }, []);
  if (!latestUrl || !currentVersion) return null;
  return <div className="not-prose sticky top-6 z-50 my-6">
      <div className="border border-yellow-500/30 bg-yellow-500/10 px-4 py-3 rounded-xl">
        <div className="text-sm">
          {isBeta ? <>
              ⚠️ You are viewing a <strong>beta version</strong> of Talos ({currentVersion}).
              This version may be unstable.
              <a href={latestUrl} className="ml-2 underline text-yellow-400 hover:text-yellow-300 font-medium">
                View latest stable version {latestVersion} →
              </a>
            </> : <>
              ⚠️ You are viewing an older version of Talos ({currentVersion}).
              <a href={latestUrl} className="ml-2 underline text-yellow-400 hover:text-yellow-300 font-medium">
                View the latest version {latestVersion} →
              </a>
            </>}
        </div>
      </div>
    </div>;
};

<VersionWarningBanner />

There might be several reasons to build Talos images from source:

* verifying the [image integrity](../../security/source-talos-images)
* building an image with custom configuration

## Checkout Talos source

```bash theme={null}
git clone https://github.com/siderolabs/talos.git
```

If building for a specific release, checkout the corresponding tag:

<CodeBlock lang="sh">
  {`git checkout ${release_v1_13}`}
</CodeBlock>

## Set up the build environment

See [Developing Talos](./developing-talos) for details on setting up the buildkit builder.

## Architectures

By default, Talos builds for `linux/amd64`, but you can customize that by passing `PLATFORM` variable to `make`:

```bash theme={null}
make <target> PLATFORM=linux/arm64 # build for arm64 only
make <target> PLATFORM=linux/arm64,linux/amd64 # build for arm64 and amd64, container images will be multi-arch
```

## Custom `PKGS`

When [customizing Linux kernel](./customizing-the-kernel), the source for the [`siderolabs/pkgs`](https://github.com/siderolabs/pkgs) repository can
be overridden with:

* if you built and pushed only a custom `kernel` package, the reference can be overridden with `PKG_KERNEL` variable: `make <target> PKG_KERNEL=<registry>/<username>/kernel:<tag>`
* if any other single package was customized, the reference can be overridden with `PKG_<pkg>` (e.g. `PKG_IPTABLES`) variable: `make <target> PKG_<pkg>=<registry>/<username>/<pkg>:<tag>`
* if the full `pkgs` repository was built and pushed, the references can be overridden with `PKGS_PREFIX` and `PKGS` variables: `make <target> PKGS_PREFIX=<registry>/<username> PKGS=<tag>`

## Customizations

Some of the build parameters can be customized by passing environment variables to `make`, e.g. `GOAMD64=v1` can be used to build
Talos images compatible with old AMD64 CPUs:

```bash theme={null}
make <target> GOAMD64=v1
```

## Building kernel and initramfs

The most basic boot assets can be built with:

```bash theme={null}
make kernel initramfs
```

Build result will be stored as `_out/vmlinuz-<arch>` and `_out/initramfs-<arch>.xz`.

## Building container images

Talos container images should be pushed to the registry as the result of the build process.

The default settings are:

* `IMAGE_REGISTRY` is set to `ghcr.io`
* `USERNAME` is set to the `siderolabs` (or value of environment variable `USERNAME` if it is set)

The image can be pushed to any registry you have access to, but the access credentials should be stored in `~/.docker/config.json` file (e.g. with `docker login`).

Building and pushing the image can be done with:

```bash theme={null}
make installer-base PUSH=true IMAGE_REGISTRY=docker.io USERNAME=<username> # ghcr.io/siderolabs/installer-base
make imager PUSH=true IMAGE_REGISTRY=docker.io USERNAME=<username> # ghcr.io/siderolabs/imager
make installer IMAGE_REGISTRY=docker.io USERNAME=<username> # ghcr.io/siderolabs/installer
```

The [local registry](./developing-talos) running on `127.0.0.1:5005` can be used as well to avoid pushing/pulling over the network:

```bash theme={null}
make installer REGISTRY=127.0.0.1:5005
```

When building `imager` container, by default Talos will include the boot assets for both `amd64` and `arm64` architectures, if building only for single architecture, specify `INSTALLER_ARCH` variable:

```bash theme={null}
make imager INSTALLER_ARCH=targetarch PLATFORM=linux/amd64
```

## Building ISO

The [ISO image](../../platform-specific-installations/boot-assets) is built with the help of `imager` container image, by default `ghcr.io/siderolabs/imager` will be used with the matching tag:

```bash theme={null}
make iso
```

The ISO image will be stored as `_out/talos-<arch>.iso`.

If ISO image should be built with the custom `imager` image, it can be specified with `IMAGE_REGISTRY`/`USERNAME` variables:

```bash theme={null}
make iso IMAGE_REGISTRY=docker.io USERNAME=<username>
```

## Building disk images

The disk image is built with the help of `imager` container image, by default `ghcr.io/siderolabs/imager` will be used with the matching tag:

```bash theme={null}
make image-metal
```

Available disk images are encoded in the `image-%` target, e.g. `make image-aws`.
Same as with ISO image, the custom `imager` image can be specified with `IMAGE_REGISTRY`/`USERNAME` variables.