> ## Documentation Index
> Fetch the complete documentation index at: https://siderolabs-fe86397c-1-11-reference.mintlify.site/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_6 = 'v1.6.7';

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

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

## Checkout Talos Source

```bash
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_6 }`}
</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
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>`
* otherwise, patch the `Dockerfile` to account for the new `pkgs` repository reference

## 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
make <target> GOAMD64=v1
```

## Building Kernel and Initramfs

The most basic boot assets can be built with:

```bash
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
make installer PUSH=true IMAGE_REGISTRY=docker.io USERNAME=<username> # ghcr.io/siderolabs/installer
make imager PUSH=true IMAGE_REGISTRY=docker.io USERNAME=<username> # ghcr.io/siderolabs/imager
```

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
make installer PUSH=true 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
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
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
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
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.