ubuntu-asahi: building an Ubuntu image for Apple silicon

A build pipeline, and a codebase that has deliberately moved away

The repository contains scripts to build native Ubuntu images for Apple silicon hardware such as the Apple M1 and M2, and the first thing the readme says is where the code is not.

Most of our code has moved to packages nowadays which are available under our Ubuntu Asahi launchpad team.

That is a significant and healthy change, and it explains the shape of the repository. The top-level listing is `.gitignore`, `.gitmodules`, `README.md`, `asahi-desktop.yaml`, `asahi-server.yaml`, `build-image.sh`, and then `fs/`, `media`, `scripts/` directories. There is no `src/` directory, no language-specific tree and no library. The primary language is recorded as Shell, and the content is a build configuration plus a set of scripts and filesystem overlay.

The two YAML files at the root are the interesting part. `asahi-desktop.yaml` and `asahi-server.yaml` are the two build configurations, one for the desktop image and one for the server image, and the fact that the server variant is a first-class artefact rather than a stripped-down desktop says something about who this is for. An ARM server image on Apple silicon is a real deployment target, and producing it from the same pipeline is cheaper than maintaining a separate one.

The `fs/` directory is the filesystem overlay that gets applied on top of the base image, `media/` holds the artwork, and `scripts/` holds the build steps. The `.gitmodules` entry indicates at least one component is pulled in from another repository.

The licence is not stated in the project metadata, and the readme itself carries no licence section, which is worth checking before you redistribute anything built from it. The last push was on 2026-07-22 and the default branch is `ubuntu`.

Launchpad livefs builds are the starting point, not a local compilation

The build instructions describe a process that is mostly about orchestration, and that is worth understanding before anyone attempts it.

The scripts in this repository can be used to start Launchpad livefs builds from the Ubuntu Asahi PPA and convert their output into a zip archive suitable for the Asahi Installer. So the heavy lifting, the actual package compilation, happens on Launchpad's build farm, and this repository's job is to kick off that build, collect the artefacts, and repackage them.

The requirements are two packages:

apt install arch-install-scripts icnsutils

`arch-install-scripts` is the Debian and Ubuntu tooling for building installer images for multiple architectures, which is what turns the architecture-specific livefs output into something installable. `icnsutils` is for the macOS icon format, which matters because the installer and the boot entries use Apple icon resources.

The build itself is one command:

sudo ./build.sh $BUILD_ID

where `BUILD_ID` is the ID of a finished launchpad livefs build where the build products are still available.

That last clause is the operational constraint that catches people. The build consumes the artefacts of a build that has already run somewhere else, and Launchpad prunes old build products. So the input is a livefs build that someone, probably the Ubuntu Asahi team, started and that has not yet been cleaned up, and the output is a zip that the Asahi Installer can write to a disk.

The naming is worth noting too, `build-image.sh` next to `build.sh`, and the distinction between the two is that one produces the image and the other produces the installer archive. The `sudo` in the build command suggests it is doing something that needs privileges, most likely the creation of the filesystem image and the Apple resource compilation.

The hosted installer is the path most people take

For a user who wants Ubuntu on an Apple silicon machine, the repository points at a hosted installer rather than at a build.

The instructions are three commands, and the middle one is the point:

curl -sL https://ubuntuasahi.org/install > install.sh	# Download
less install.sh						# Review
sh install.sh						# Run

Or, if you like to live dangerously, `curl -sL https://ubuntuasahi.org/install | sh`.

The three-step form with `less install.sh` in the middle is the recommended one, and the reason is obvious once you know what the script does. The installer is interactive and offers a choice of different Ubuntu releases and build configurations, and it partitions your disk and writes a bootable image. Piping a script straight into a shell that repartitions your machine is a bad habit, and the project is implicitly telling you that by showing the reviewed version first.

The supported releases are Ubuntu Desktop and Server 26.04, and Ubuntu Desktop and Server 25.10. Having both a desktop and a server image for each release, and offering the choice interactively, matches the build configuration files in the repository.

The installer itself is a separate project, the Asahi Installer, and the site is ubuntuasahi.org. The split between the two is a sensible one: this repository builds the image, the installer writes it to a disk and sets up the boot configuration.

Dual boot works, removing macOS does not, and that is a firmware constraint

The FAQ answers the questions that decide whether somebody should install this at all, and one of them has a hard limit in it.

On dual booting, the installer can automatically resize your macos partition according to your liking and install Ubuntu in the freed up space. Removing macos is not even supported at the moment since it is required to update the system firmware.

That is the key operational fact about Ubuntu Asahi. The reason is that Apple's update mechanism for the system firmware on Apple silicon runs as part of macOS, and without macOS present the firmware cannot be updated. So a machine with Ubuntu Asahi and no macOS has a firmware that can never be updated again, which for a platform whose hardware support is still catching up is a significant risk. The answer to the question is therefore not a policy choice by the project but a consequence of how Apple built the platform.

The removal answer follows from the same constraint. There is no automated uninstaller, but you can uninstall Ubuntu Asahi by booting into macos, removing all Ubuntu partitions and then resizing the macos APFS container to the full size, with a detailed guide in the Asahi Linux Wiki partitioning cheatsheet.

Booting is handled by the platform rather than the installer. Hold the power button on boot until you see Loading startup options, and you can choose which system you want to boot. To change the default boot entry you hold the Option key and select Always Use.

The rest of the FAQ is about feature parity with the reference distribution. Does Ubuntu Asahi support the same features and hardware as Fedora Asahi? The answer is that they try to quickly adapt features added by the reference Asahi distribution, and since they always wait for an official release first, it might take a few weeks longer to roll out support for new hardware, but they generally aim for feature parity. Graphics acceleration, sound and the webcam need no additional steps, it should all work out of the box, and in the past there was a linux-asahi-edge kernel providing additional features, nowadays everything is included by default.

Where ubuntu-asahi is the wrong thing to work with

The first case is a developer looking for the driver or kernel work. That has moved into packages under the Ubuntu Asahi Launchpad team, and this repository is the build glue around them. If your interest is in kernel or driver work, the code is elsewhere and this repository will send you to the right place.

The second case is a user who wants to keep macOS and does not need Linux. The installer resizes a partition and changes the boot configuration, which is a real operation on the system disk, and the risk is not symmetric. If you need macOS for work and are only curious about Linux, a virtual machine on an Apple silicon Mac is the low-risk way to find out.

The third is a build that needs to be reproducible from a known source. The pipeline depends on a finished Launchpad livefs build whose products are still available, which means the input is a moving target controlled by someone else's build schedule. To reproduce an image exactly you need the specific build ID and the same PPA state, and even then the result is tied to whatever Launchpad had built at that moment.

There is also a support asymmetry worth understanding. The project says it always waits for an official release before rolling out support for new hardware, which means a few weeks of delay after Fedora Asahi supports a new device. For a project whose user base is early adopters with the newest hardware, that delay is the difference between running the platform and waiting for it.

The last point is the project itself rather than the software. Ubuntu Asahi is a downstream of the Asahi Linux project, with Fedora Asahi Remix and the Debian Bananas Team listed as related projects, and the site is ubuntuasahi.org with IRC on OFTC and Matrix. The community is on Matrix and Mastodon, and the project describes itself as a native Ubuntu installation for Apple silicon hardware, which is a distribution of a distribution rather than a new operating system.

Editorial conclusion

This repository fits someone who wants to produce an Ubuntu Asahi image themselves, either for their own machine or to reproduce a build, and it fits a user who simply wants the pre-built image and can run the hosted installer. It does not fit a developer looking for the driver or kernel work, since that has moved into packages under the Ubuntu Asahi Launchpad team. Before you build, note that the build needs a finished Launchpad livefs build whose products are still available, so a build ID from an old cycle will fail, and read the partition instructions before installing because macOS cannot be removed while the firmware still needs it.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. UbuntuAsahi/ubuntu-asahi on GitHub