omarchy-mac README

The project's README from github.com/omacom/omarchy-mac. As one markdown file: README.md.

Omarchy 4 on an Apple Silicon MacBook: the top bar flowing around the display notch on a fresh install

Omarchy Mac

Omarchy 4 on Apple Silicon, alongside macOS: Asahi Alarm + Omarchy, installed in one command, full-disk encryption included.

License Stars

Already running Omarchy 3.x? This page is the fresh install — to upgrade in place, see docs/upgrade-to-quattro.md.

Before you begin

Install

1. Run the Asahi Alarm installer, from macOS Terminal

curl https://asahi-alarm.org/installer-bootstrap.sh | sh

Choose Asahi Alarm Minimal (BTRFS) and allocate at least 50 GB for Linux. The plain Asahi Alarm Minimal (ext4) works too — the setup below converts it — but the BTRFS image already has the right shape.

2. Boot into Arch and get online

Log in as root (username: root, password: root) and connect first — everything from here starts with a download:

nmtui

Choose Activate a connection and connect to a WiFi network. Optionally Set a system hostname or set it during install below. Choose Quit when done to return to the prompt.

If nmtui shows an error right after activating the connection, reboot and try again.

3. One command

Still as root:

curl -fsSL https://raw.githubusercontent.com/omarchy-mac/omarchy-mac/quattro/bin/omarchy-mac-setup | bash

There is nothing to prepare beyond the network: no pacman update, no locale setup, no user creation. The script installs what it needs, creates your user and sets up sudo itself. To read it before running it, or to pass options:

curl -LO https://raw.githubusercontent.com/omarchy-mac/omarchy-mac/quattro/bin/omarchy-mac-setup
bash omarchy-mac-setup --no-encrypt

(--repo <owner/repo> installs from a fork the same way. quattro is the repository's default branch and the script installs from it by default; it checks the version it is about to install and stops rather than giving you Omarchy 3 by accident.)

It asks whether to encrypt (yes by default), then for a hostname, username and password, then carries the machine the rest of the way on its own — moving /boot onto the EFI partition, encrypting the root, installing Omarchy — rebooting between steps and resuming itself each time on tty1.

Expect about fifteen minutes, three reboots, and two questions along the way:

Encrypted machines log straight into the desktop afterwards: the passphrase at boot is the authentication, and a second password immediately after it protects nothing the first one did not.

Other flags: --no-encrypt skips the encryption and the boot-layout move it needs, --status reports where a machine has got to, --step <name> re-runs one step, --abort stops the guided run without undoing anything, and --keep-root-password leaves root's password as Asahi Alarm shipped it instead of locking it once your user has sudo.

By hand

Every step the script drives can be run separately. The boot-layout move, btrfs conversion, snapper snapshots and encryption are covered in docs/btrfs.md. Once a regular user with sudo exists — the minimal image ships without git or sudo, so as root first: pacman -S --needed sudo git — installing Omarchy itself is:

git clone https://github.com/omarchy-mac/omarchy-mac.git ~/.local/share/omarchy
cd ~/.local/share/omarchy
cat version    # 4.x — if this says 3.x you are on the wrong branch
bash install.sh

Mind the branch. A plain clone gets quattro, the default branch and the Omarchy 4 line. main still carries Omarchy 3.x, and its install.sh installs Omarchy 3 without saying which generation it is putting on the machine — an easy hour to lose. cat version is how you check before committing to it.

The install takes under ten minutes on a good connection — most of the default set comes prebuilt from the aarch64 package repo rather than being compiled here. A few packages have no ARM build at all and are reported at the end rather than failing the install; where building one would take hours and still fail, the installer asks before trying, and OMARCHY_TRY_UNAVAILABLE=1 bash install.sh forces the attempt.

Troubleshooting

SSH stopped working after the install

Asahi Alarm ships openssh enabled — the images are built for headless boards — and Omarchy's install turns on a default-deny firewall that never opens port 22. Nothing is uninstalled; the machine simply stops answering, which looks exactly like sshd having been removed. Turn it back on deliberately:

omarchy-setup-security-sshd

It enables sshd, adds ufw limit 22/tcp, and offers to fetch your public keys from https://github.com/<user>.keys. The same thing lives in the menu under Setup → Security → SSH.

The machine boots to grub rescue>

GRUB kept its modules and kernel on the root filesystem, and the root was encrypted underneath it. See docs/btrfs.md — /boot has to be the EFI partition before encrypting, which omarchy-system-boot-to-esp arranges and omarchy-system-btrfs-migrate refuses to proceed without.

Rolling back after a bad update

omarchy snapshot restore works on Apple Silicon. It offers snapper's snapshots alongside @fresh — the system before Omarchy was installed — and @factory, the installed system before it was yours, and says what you are about to restore before doing anything. /boot is the EFI partition and sits outside every snapshot; the tool warns when the restored root has no modules for the running kernel.

Mirrors are slow or failing

Run bash fix-mirrors.sh from the repository root and retry.

The update stops on libaquamarine.so and cannot be repeated past it

An install made before the ARM package sources policy cannot upgrade its way to it, because the update aborts before the package carrying it can be replaced. Run the recovery and log out and back in afterwards:

curl -fsSL https://raw.githubusercontent.com/omarchy-mac/omarchy-mac/quattro/fix-arm-packages.sh | bash

See docs/arm-package-sources.md for what it changes and how to pass --dry-run or --no-snapshot to the piped script.

Removal (uninstall)

There is no automatic uninstaller. Removal is done from macOS by deleting the Linux partitions and growing the macOS container back over them. Follow the Asahi Linux partitioning cheatsheet exactly — it identifies which partitions are Asahi's and which are macOS's own, and the wrong diskutil target can take macOS with it. If unsure, open an issue.

Support

Consider supporting the project: Buy Me A Coffee

More documentation

External resources

Acknowledgements

Thanks to Asahi Linux and Asahi Alarm for enabling Linux on Apple Silicon, and to DHH for creating Omarchy.

If this guide helped you, please star the repository and share feedback in issues or discussions. If you enjoy Omarchy Mac, please share your experience on Twitter/X by tagging @OmarchyMac.

Omarchy Mac Contributors

Partial contributor list:

omarchy-mac (omacom/omarchy-mac)

Searching Database…

2K ·GitHub
Omarchy-mac
Что это такое?Готовый настроенный рабочий стол Arch Linux + Hyprland для Mac на Apple Silicon (семейство M1/M2), который устанавливается рядом с macOS из Asahi Alarm одной командой — с шифрованием всего диска.
Он заменит macOS или будет работать рядом с ней?Полноценная система Arch Linux на отдельном дисковом пространстве рядом с macOS — это dual-boot, а не виртуальная машина. Установщик запускается со стороны macOS.
Что мне нужно перед началом?Свежая резервная копия macOS (Time Machine или похожий инструмент), Mac на Apple Silicon из семейства M1/M2, не менее 50 ГБ свободного места на внутреннем SSD (лучше 100 ГБ) и доступ в интернет.
А если потом захочу от него избавиться — можно удалить?Автоматического удаления нет. Удаление делается из macOS: нужно снести разделы Linux и вернуть освободившееся место контейнеру macOS — в точности следуйте шпаргалке по разметке Asahi, потому что неверная цель в diskutil может унести с собой и macOS.
Мой диск будет зашифрован?Да, по умолчанию — установщик спросит, включать ли шифрование, а затем попросит имя хоста, имя пользователя и пароль. На зашифрованных машинах пароль при загрузке совпадает с паролем входа, так что вы сразу попадаете на рабочий стол. Чтобы пропустить шифрование, передайте --no-encrypt.
При установке спрашивают про сборку пакетов, для которых нет ARM-сборки, — что отвечать?Отвечайте «нет» — по умолчанию и так нет. Один obs-studio компилируется около трёх часов, а потом проваливает проверку архитектуры. Пакеты без ARM-сборки в конце установки просто перечисляются, а не ломают её.
Почему после установки перестал работать SSH?В Asahi Alarm openssh включён сразу, а установка Omarchy поднимает файрвол с политикой «запрещено всё, что не разрешено», и порт 22 в нём никто не открывает — ничего не удаляли, машина просто перестаёт отвечать. Включите SSH обратно задокументированной командой или через меню: Setup → Security → SSH.
Обновление что-то сломало — можно откатиться?Да — omarchy snapshot restore работает на Apple Silicon. Он предлагает снапшоты snapper, а также @fresh (система до установки Omarchy) и @factory (установленная система до того, как вы её настроили под себя), и перед любыми действиями говорит, что именно собирается восстановить.
Как это связано с самим Omarchy?Это форк, который приносит Omarchy (созданный DHH) на Mac с Apple Silicon через Asahi Alarm. По умолчанию из ветки quattro ставится линейка Omarchy 4; в main пока лежит Omarchy 3.x, а cat version показывает, что именно вам поставят.
What are similar projects?AgentOS, omarchy-workspace-layout, serpantinum, omarchy-meeting-recorder, omarchy, omastorm, flea, omacosy
Which topics is it in?archlinux, omarchy, tiling-window-manager, hyprland, linux-desktop, wayland, dotfiles, script, arm64, configuration, installer, apple-silicon
Creator
omacom
Size
258.4 MB
Stars
2K
Updated
CommitSep 25Releasev4.0.2-2Sep 07
Age
1y
Commits · 90 Days