Features

---

Easy configuration

The build process can be configured entirely in a straightforward YAML format called a recipe. When building, the recipe is transformed into a Containerfile by the BlueBuild cli tool.

Totally extensible

The modular build system can easily be extended by just writing a shell script. Modules you create can be added into the official BlueBuild repository, or your own, for the community to take advantage of.

Based on well-known standards

The format of your OS images is the familiar OCI image format, famously used by Docker & Podman. With Fedora’s Native Container support and bootc, it becomes possible to boot natively into a OCI compatible image.

Free & open-source

BlueBuild is an open-source project built by the community for the community. Feel free to peek at & tinker with the source code! GitHub also provides CI/CD & a container registry for free, though other providers are supported as well.

Effortless reliability

With your custom images being based on reliable atomic distributions, your setup will be rock solid. As all errors related to customizing your environment happen during the build process in the cloud, it’s way harder to end up with a bricked system.

Build on the best

Build your custom images on Universal Blue’s awesome base images, with the option to build on atomic Fedora desktops, our base images and more options being supported soon.

FAQ

What’s a custom image? Can I use this to make my own distro?

A custom image in this context is a customized version of an image-based Linux distribution that can be switched to by the user of such a distribution without reinstalling. So about making your own distro, maybe, but not really. When making custom images, you’re building on top of an existing distribution. You’re most likely using its package manager and repositories and just adding your own flair with package set changes and configuration files. It’s more like a more reliable version of maintaining/sharing your dotfiles, but from the perspective of the operating system.

So is this the type of workaround necessary to make ‘immutable’ distributions customizable?

Someone might get turned off from so-called ‘immutable’ Linux distributions due to fears of the taking away them ability to tinker and change the system as you please. The term comes from the usage of immutable root filesystems in these distributions, but in reality most ‘immutable’ Linux distributions are still pretty change-able. So while BlueBuild is a tool that helps you tinker with these sorts of distributions, it’s not giving you back some freedom that was taken away.

Here’s some terms that can be used to better describe these sorts of distributions:

Atomic: instead of new and updated packages being swapped on the running system live, they’re queued up to be used after the next boot.
Image-based: instead of each computer updating each of its system packages individually, the system updates are bundled (usually daily) as images that are pulled onto the user computers and queued up to be used after the next boot.

Read more here.

What’s the difference between BlueBuild and VanillaOS’ Vib?

BlueBuild and Vib seem very similar and both use similar concepts: recipes and modules. While Vib technically does the same thing as BlueBuild, it is positioned more as a generalized tool to build any OCI container image that just happens to be what is used by Vanilla to build their desktop. BlueBuild focuses on image-based desktop Linux more than containers, using container images as just a distribution mechanism. As such, BlueBuild supports more features specifically useful on desktop by default, such as the fonts module to fetch a selection of fonts.

BlueBuild also aims to support building custom images of VanillaOS in the near future.

And in the FAQ writer’s opinion, BlueBuild’s documentation is better and the recipe format is slightly cleaner.

What’s the difference between BlueBuild and Universal Blue?

Universal Blue is an open source project started by cloud developers that builds amazing custom images based on atomic Fedora along with related experiments, while BlueBuild only builds tools for custom image creation. The project now known as BlueBuild started out as just a part of Universal Blue, but was eventually split from it due to diverging from the scope and being mostly unrelated to the project’s main maintainers.

Can I make other custom images with BlueBuild that are not Fedora-based?

As of writing this (2026.06.05), yes. But it is not the stable and straight-forward process like with Fedora. It is rather experimental. For a long time, rpm-ostree was used as the only available tooling to make OCI custom image making and BlueBuild possible in Fedora land only. However, during the time of progression, bootc tool was made, and it got more stable and reliable for use. bootc is used as a generalized distro-agnostic tool for making OCI container images, which allows users to have custom images with Arch, Debian, OpenSuse and others as a base image. Check out this cool bootcrew mono project, which is a great template for distro-agnostic base bootc images. Also check this custom image example based on Arch that utilizes BlueBuild as an inspiration (totally unbiased, made by this FAQ author). Note that those provided base images are very minimal compared to Fedora base images, so you have to add more stuff that you want or need.

Current caveats with images other than Fedora that I am aware of are:

• No working ISO tooling - custom image installation is done by rebasing from Fedora image instead
• Rebasing from one distro to another (requires a downstream dracut script patch and initramfs rebuild afterwards to make it working)
• No secure boot support
• Bootloader updater not working (bootupd - related to “No working ISO tooling”)
• Bootloader (grub) is inherited from previous Fedora image (related to “No working ISO tooling”)

Why build an abstraction on top of Containerfiles? (recipe.yml)

• It is more accessible and helps onboard new users.
  • Editing a configuration file is something most people are likely familiar with, but editing a Containerfile, bespoke build scripts, and a GitHub Action file is something most probably have no prior experience with.
• It allows us to make harder things easier.
  • For just installing packages the system might be less useful, but for more complex customizations it becomes way easier to use a commonly maintained module instead.
• It allows for parts of the build system be shared.
  • Less moving parts for everyone to maintain on their own.
  • Discuss and keep useful patterns up-to-date as community.
• It allows for tooling to be created that programmatically configures custom images for users.
  • This is what BlueBuild Workshop is planned to be.

Is this project for me?

If you want an easy way to package your customization for use on multiple computers, or maybe even have a lab of full-fledged Linux computers that you want on the same centrally updatable base, BlueBuild might just be what you’re looking for! Or maybe you’re a tinkerer looking for a new and exciting space in Linux to dabble with, then this and related projects are definitely something to put on your radar.

But if you’re a total Linux and cloud nerd, you know Containerfiles by heart and are comfortable building CI/CD, our abstractions might feel limiting to you. You should still come hang around if you’re interested in building custom images!

If you’re just looking to build a simple container image to run on the cloud or locally, a Containerfile might still be the easiest way to get the result you want. If you want to learn how to build OCI container images with Containerfiles by making a custom image of atomic Fedora, the ublue-os/image-template is a good minimal place to start.

If you want to leverage BlueBuild’s modules for making more complex customizations to your image, while using a Containerfile directly, check out our guide for a minimal BlueBuild module setup in a Containerfile. Keep in mind that this approach is not guaranteed to be as seamless as using a recipe and to not have breaking changes. When not using a recipe, you’re also losing out on a lot of the magic of the BlueBuild CLI, such as being able to switch to the image built from a recipe locally with just one command.

Are you stable?

Generally yes. We made some breaking changes and refactorings in the starting phases of the project, but we are stable for a long time as of writing this (2026.06.05). We made a well thought-out system that allows us to gain new features while retaining backwards compatibility with older configurations, which is our goal. However, note that in some cases you may need to update the versioned module manually if version increased to get the latest features (that is when module is significantly refactored in functionality and features). Changes in the CLI tooling itself should not affect the stability of your actual operating system.

What’s up with the logo?

It’s our mascot, a blue-billed duck with a wrench! A good pun, and cute too! The writer of this FAQ is definitely not at all biased!

The logo (along with all the other BlueBuild branding) was designed by @xynydev and is licensed under CC BY-NC-SA 4.0.