Skip to main content
  1. Blog/

blendOS v4 Install Guide

··1288 words·7 mins·
BlendOS Linux Guide
Canadian Linux nerd and game enthusiast
Table of Contents

The blendOS v4 alpha is now out! Here’s how you can install and try it out.

I’m not going to go over the release details. For those, go to the release blog post.

Installing v4

blendOS v4 is a lot more declarative than v3. The current beta must be installed on top of Arch.

What you’ll need

Do not install this on top of blendOS v3!

There is no upgrade procedure yet, this will ruin your v3 install if you try to update from it.

  • An Arch Linux VM (or real PC, if you dare) using mkinitcpio for the kernel image, GRUB as the bootloader, and no disk encryption1.
  • An internet connection
  • Time
  • Basic YAML knowledge


I’m assuming your Arch Linux system is already up and running. If it isn’t, there’s plenty of guides, and you can just use archinstall. If you’re on a T2 Intel mac (2017 iMac Pro or an Intel Mac from 2018 and later), instructions are here.

Add the breakfast repo

At the end of your /etc/pacman.conf add the following lines:

 SigLevel = Never
 Server =

* Yes, I am aware this has a SigLevel of never, this is very insecure. I’m assuming this is just a testing thing and will be fixed.

If you’d like to browse our small repo, feel free to do so.

Create your system config

Create a file in / named system.yaml.

Avalible tracks on the standard repo:

  • plasma
  • gnome
  • xfce
  • mate
  • lxqt
  • blendos-base * Kinda bloated for a base, if you want something stripped down, see below. This track allows for custom desktops and more.

This is YAML so indentation is important. All indents are 2 spaces (no tabs).

Add the following to it (or something similar, THIS IS JUST AN EXAMPLE!):

 # /system.yaml

 repo: ''

 impl: '' # or an alternate track repo

 track: 'plasma' # or 'xfce' or 'mate'

                 # GNOME isn't recommended
                 # at the moment as it is
                 # known to be be buggy.

     - 'firefox' # stuff to install using pacman
 #   - 'nvidia-dkms' if you're using an NVIDIA GPU

You can add repos and things to this file, as documented here (Again, just an example):

repo: ''

impl: ''

track: 'gnome'

    - 'micro'
    - 'caddy'

    - 'caddy' # what services to start

    - name: 'chaotic-aur' # the name as it would appear in pacman.conf
      repo-url: '$repo/$arch' # the Server

Configuration customization

Scroll to the next section if you do not wish to customize your config further.

Track repo

Want to add to this list? Just make a comment! I’ll look at your repo if you comment it.

Currently there are also alternate track repos:

T2Linux track repo:

For T2Linux users.

Avalible tracks:

  • All tracks from the standard repo. modified for T2Linux
  • blendos-base renamed to blendos-base-t2
impl: ''

ico277 stripped base track repo:

This repo modifies blendos-base to be more stripped down, and creates a blendos-dekstop track.

Avalible tracks:

  • All standard tracks are unmodified, except for blendos-base
  • blendos-desktop added
impl: ''

track: 'blendos-base' # one of two tracks that differ from the standard repo

* you can also use ico277’s blendos-desktop track with this repo, which adds a very minimal (like just pipewire and xorg) desktop setup to blendos-base.

Always run sudo akshara update after editing your system.yaml.

Adding custom track repos

Your repo must have a series of YAML files, look at the main track repo for examples.

Your base track must have a track: of custom, as shown here. Desktop tracks must have their track set to your base track.

Tracks are like mini system.yaml files, and have the same structure.

The easiest way to get started is to just fork the main repo, but impl URL structures for common Git forges are shown below:

Common git forges:

Replace everything in caps with what it represents.



Gitea/Forgejo (i.e. Codeberg): https://GITEA-SERVER/USER/REPO/raw/branch/BRANCH

BitBucket Cloud (Not Recommended):

For BitBucket, you must add all the track files in ONE COMMIT, and use that commit's full hash.

Steps (cont.d)

Wifi firmware (T2 ONLY!)

If you are on a T2 Mac, please follow this guide to copy your wifi firmware over from MacOS BEFORE continuing with the rest of this guide.

Installing akshara

Run sudo pacman -Sy akshara.

Adding akshara into mkinitcpio

Edit /etc/mkinitcpio.conf and add akshara after the base udev bit in the HOOKS part of the file.

Run sudo mkinitcpio -P; sudo akshara update.

Reboot your system.

blendOS v4 is now installed!

To update your Arch packages, just run sudo akshara update.


Adding repos

Add a line to the end of system.yaml like so (using the chaotic-aur as an example):

    - name: 'chaotic-aur' # repo name as it would appear in pacman.conf
      repo-url: '$repo/$arch' # Repo URL as it would appear in pacman.conf

(the Chaotic AUR’s package list can be found here, and packages can be manually downloaded from here)

If you add repos, run sudo akshara update and reboot afterwards.

Adding AUR packages

Add stuff under the aur-packages tag. They will be installed via paru automatically (paru is in our repo, don’t add it as a package here). You will need to run sudo akshara update a lot more often.

  - '1'
  - '2'



system.yaml structure (preserve all single quotes and the order of items):

repo: '' # Do not change this.

# the track repo
impl: ''

track: 'plasma' # The track you want

packages:       # Packages to install using pacman
  - 'package_1'
  - 'package_2'

aur-packages:   # AUR packages, installed via paru
  - 'package_1-git'
  - 'package_2-bin'

services:       # Enable these systemd services
  - 'service_1'

  - name: 'REPO_NAME' # as it appears in pacman.conf
    repo-url: 'REPO_URL' # the Server variable in pacman.conf for this repo

commands:       # List of commands to run at system build, will execute with root permissions, more file-related stuff like git is tricky
  - 'echo command_1'
  - 'echo command_2'


This option must be set.

Type: string value

Don’t change this. Repo where the core blendOS packages (and akshara) are stored.


This option must be set.

Type: string value

The repo where the tracks are.


Default: blendos-base

This option must be set.

Type: string value

The track yaml file, without the extension (i.e. blendos-base.yaml -> track: blendos-base).


Default: none, can be provided by track.

Type: array

Add packages to install from the repos (including set custom ones) via pacman, one per-line.

  - '1'
  - '2'


Default: none, can be provided by track.

Type: array

Same as packages, but for packages from the AUR.

  - '1-bin'
  - '2-git'


Default: none, can be provided by track.

Type: array

Services to start via systemd.

  - 'service-1'
  - 'socket-2.socket'


Default: none, can be provided by track.

Type: object array

Custom repos to add. Consists of their name and URL as they would appear in pacman.conf.

  - name: 'NAME'
    url: 'MAIN_REPO_URL'

Support for mirrorlists is coming in the future. For now, you can just pick a mirror or use a geolocator URL if applicable.


Default: none, can be provided by track.

Type: array

Commands to be run at system build, run as root.

  - 'echo 1'
  - 'echo 2'


Update system (new arch packages, edited config)

sudo akshara update

* You will need to reboot after this.

Help menu

akshara help


akshara version

  1. You can use encryption by moving the akshara hook after the encrypt one in your mkinitcpio.conf, but this has not been tested, and is not officially supported. ↩︎