Building Omarchy from Scratch

Addendum (2025/9/6)

Omarchy 2.0 has been released. Starting with 2.0, ISO images are available, making Omarchy easier to install. See the article below for the latest steps. https://www.munenick.me/blog/omarchy2

Introduction

When I was thinking about building a Linux desktop environment, I came across a project called Omarchy. It is based on Arch Linux and Hyprland and includes various tools.

Previously, I configured Hyprland on NixOS to prepare a Linux desktop environment, but both NixOS and Hyprland required many individual settings, so it took a lot of time to make them comfortable. (It was especially painful that the navigation bar and application launcher were not set up by default…)

Omarchy lets you skip that setup and use a tiling window manager desktop environment immediately after installation.

This article introduces how to build Omarchy, configure Japanese localization, and set up VNC.

What is Omarchy?

https://omarchy.org/

Omarchy is an “omakase” remix environment based on Arch Linux + Hyprland developed by DHH (author of Ruby on Rails). It carefully selects and integrates the applications and settings needed for development. It can be built with one command.

Features

Arch Linux based It is based on Arch Linux, so you can use the latest packages and customize the environment freely.

Hyprland adopted It uses Hyprland, a native Wayland tiling window manager, to provide a polished desktop experience. image_1755677274044_e3518c67a04b49f3a9e77082c27df18c.png

Opinionated design It was created with a clear opinion that “this is a good environment,” so the overall setup feels cohesive. You get an environment that can be used as is without thinking through every detail.

Includes development environment Neovim (with LazyVim configured) is included as the default editor, so you can skip the tedious Neovim setup. Other useful TUI tools include Lazygit, Lazydocker, and Btop.

Arch Linux image download

Visit the link below.

https://archlinux.org/download/#http-downloads

Scroll down and visit any regional mirror site. image_1755666040550_3d9b0ba001df40a5af2c97515d2c79e6.png

Click “archlinux-x86_64.iso” and download the ISO. image_1755666062228_a1c836df4a044858ad69ccdcf380db19.png

Prepare USB installer (optional)

When installing on a server or PC, create a USB installer from Windows or macOS. Create the installer with a tool such as Rufus or balenaEtcher.

Official procedure:

https://wiki.archlinux.jp/index.php/USB_%E3%82%A4%E3%83%B3%E3%82%B9%E3%83%88%E3%83%BC%E3%83%AB%E3%83%A1%E3%83%87%E3%82%A3%E3%82%A2

After creating the installer, connect it to the server or PC and boot from it. If you are using a virtual machine, skip this step. Instead, mount the ISO to your virtual machine.

Once mounted, boot the machine.

Click “Arch Linux install medium”. (It will start automatically if you leave it alone.)

Installing Arch Linux

This is the installation procedure for Arch Linux. If you can install it on your own, you can skip this section. For this article, I am building it on a Hyper-V virtual machine. The same procedure should work on a server or PC.

Pre-installation network settings

When you start the machine, a shell opens. You can configure the installation from here. You can see that the installation flow is different from Ubuntu and similar distributions. image_1755661444382_682dad25a5c04f099823faae5c5d70cf.png

Configure network settings. No special settings are required if you are using wired networking and DHCP is available. When using Wi-Fi, refer to the following site for setup. Reference site:

https://qiita.com/doraneko94/items/dfc04b36d46701eca3e0

image_1755661464536_92b1170ea7b84d779ba2960033d06133.png

After completing the network settings, send a ping to test connectivity.

ping archlinux.org

image_1755661509574_85e9c7d4dccf4f70bde2177550a6c66e.png

Arch Linux installation settings

There are multiple ways to install Arch Linux. It is also possible to customize the settings and build your own Arch Linux environment from this shell.

Here we will use a simple TUI-based installation method. Enter the following command to start the installation TUI.

archinstall

image_1755661380712_b532588f005e48f2bc35b870edbfe35e.png

Once the TUI starts, configure the OS installation settings.

Here we will use Omarchy’s recommended procedure.

https://manuals.omamix.org/2/the-omarchy-manual/50/getting-started

Change the settings as needed for your environment.

image_1755661532782_55afe988ac404b5ea712ffa89b6312c1.png

Change the keyboard layout

Change the keyboard layout. Select Locales → Keyboard layout.

image_1755661593651_323a0c4d05654993bb51ff43bcfb5449.png

image_1755661605524_431cd26f64704c428ab1589aa1c6ff09.png

When the layout list is displayed, set your keyboard layout. If you are using a Japanese keyboard, enter “/jp” and select “jp106”.

image_1755661638204_f29c6481f5b5405dae5d25e6861b2fcc.png

Confirm that the keyboard layout has been changed and select “Back”.

image_1755662717449_14cab83dad204c33b483544cc61de8f9.png

image_1755662733561_28ab7462a86e40f1ad6863c43c080fb1.png

Mirror settings

Select the server used during OS installation. Select Mirrors and repositories → Select regions.

image_1755661655666_810a6b4da44048668e57bc20e3d402ff.png

image_1755661667726_ae637560db914d43ab93200b4f85adfb.png

Select your country or region. For Japan, select “Japan”.

image_1755661682795_4413a211af3545ed8a53ff4b4ab262dc.png

Make sure your region is selected and select Back.

image_1755661694203_1ee6f110ac0047a680cca24a7c9f53e1.png

Disk settings

Configure the disk settings during OS installation.

Partition creation

First, create a partition. Select Disk configuration → Partitioning.

image_1755661714261_ef4b359c7b2e4717888ee7d73d8ad0fc.png

image_1755661723214_c030b0c7a90243ea9d53137c45ea4a20.png

Select “Use a best-effort default partition layout.” If you want to adjust the partitions manually, select “Manual Partitioning”.

image_1755661734913_0a596aef7dfa4116a4021e068d4810b8.png

A list of disks will be displayed. Select the disk where you want to install the OS using the Space key. *If more than one disk is displayed, be careful not to select the wrong installation destination.

image_1755661744646_a5e6cee0f2504976a61f34cb14257352.png

Select a format method. Here, select “btrfs”.

image_1755661755755_18a90e3a56334fa580c24b9bd93c9a1f.png

Select Yes when asked if you want to use the default volume configuration.

image_1755661765305_8ab8db42166343ce96b4753b0a882b9e.png

You will be asked if you want to use compression, so select “Use compression”.

image_1755661776277_01a806ffba1041f4a9d38a7229a126c9.png

Verify that the partition was created.

image_1755661785928_cecfb9f2a92948068fa14ecf8c253611.png

Disk encryption (recommended)

Encrypt the disk. Omarchy seems to recommend disk encryption.

Please note that disk encryption must be configured to use Omarchy as designed. With this configuration, the user is automatically logged in after the disk is decrypted at startup, so the device’s security relies solely on disk encryption.

We have confirmed that Omarchy works without disk encryption, but from a security perspective, we recommend performing this procedure (disk encryption) when installing it on a portable device such as a laptop. The password set in this procedure essentially becomes the password for logging into the PC/server. (On the other hand, if you do not perform this procedure, the OS can be accessed without a password.)

For remote systems such as servers in data centers or stationary PCs where you do not touch the physical console, disabling encryption is also an option. This is because if disk encryption is enabled, systemd will not start and you will not be able to connect to SSH/VNC until you enter the decryption password on the physical console after rebooting.

If you want to avoid physical input while maintaining encryption, consider remote decryption using initramfs (e.g. Dropbear) or automatic decryption using TPM/FIDO2.

Select Disk encryption.

image_1755661828817_161ada5f6c624a3fa4a9b5dd7ab39ad5.png

Select Encryption type.

image_1755661838331_5119287409e44bc7aee4db2233e47523.png

Select “LUKS”.

image_1755661847496_95d99b72df884169a64397ff0d0d8c0d.png

Select Encryption password.

image_1755661858836_cd67f2896dd24a338f14392580fdaf6a.png

Enter the disk encryption password. This password essentially becomes the password for logging into your PC/server.

image_1755661874383_256d9834db5b426fa930cddb540d6905.png

Confirm that the encryption settings are configured and select “Back”.

image_1755661886410_be23f5b9b5a54403a244a00f702dd758.png

Setting the host name (optional)

Set the host name. Select “Hostname” and change it to your desired host name.

image_1755661799674_2fc7513956b84d8aa8c2b6a5d3f74823.png

Authentication settings

Set the user password.

Root password setting

Set the password for the root user. Select “Authentication” → “Root password”.

image_1755661935390_9bdbc34be59e4767bc8f987c07fd26b2.png

image_1755661944288_bec56db1d4694117b0a669ddeebd6674.png

Set any password.

image_1755661956524_9e6618f9c134472582f9e25c91f92f41.png

Create a superuser (required)

Using Omarchy as the root user is not recommended. Therefore, create a separate superuser.

Select User account → Add a user.

image_1755661968957_f0ed880cac894cc7811af6fdd40395b4.png

image_1755661981029_de25ebe954924dd6a7d6acf1dce4c62e.png

Specify any user name.

image_1755661991579_cc17cc9ef0704d5d87750ba4b1a1a849.png

Set any password.

image_1755662004888_002606087c4f4a4884c1eae83b04dd36.png

You will be asked whether to make the created user a superuser, so select “Yes”.

image_1755662016497_8c45de817d42480d8a21828482f559af.png

Select “Confirm and exit”.

image_1755662876095_bd431898340b46d48d696b0b313c70f2.png

Verify that the root password is set and the user has been created.

image_1755662951311_a8a77e0c44ac43378d6477c934e68b9c.png

Application settings

Configure the applications to install during OS setup. Here, we will install only “Pipewire”, which is used by Omarchy.

Select Applications → Audio.

image_1755662055452_bd931e9889e54fec89e6bde89d9b161c.png

image_1755662064534_a5b8548cb2a84d00a1b8cc5fd61fd776.png

Select “pipewire”.

image_1755662073396_57bc6cf48f2446b78ad0edc491e13d4d.png

Make sure “pipewire” is selected and select “Back”.

image_1755662081794_7200ada07172458ea77edfbbbcc0b4d6.png

image_1755662089512_19e955cc685c4986970944037c48480c.png

Network settings

Configure network settings. There are several options, but the settings configured in the pre-installation network step will be used as the OS network. If you want to change the network configuration, use “Manual configuration”.

Select Network configuration.

image_1755662098443_2a6d7f7e6aae430388fa434c8c1555e4.png

Select “Copy ISO network configuration to installation”.

image_1755662109397_70d6af6835e743dcb903be9bc0d5ecb9.png

Verify that the settings are correct.

image_1755662116249_e16b4371ae1e43cead4a4de4b502157e.png

Additional package settings

Configure additional packages during OS installation. Here, we will specify only “wget”, which is required for the Omarchy installation.

Select “Additional packages”.

image_1755662126031_0dcdae90d5034ae491674e89bf163557.png

When the package list is displayed, enter “/wget”.

image_1755662138367_a292ce40be4d4b2bbb0c26c371f34165.png

When the “wget” package is displayed, press Enter to select it.

image_1755662154808_4e2e7515fb18431b9595641f04adce37.png

Make sure wget is specified.

image_1755662164230_0cdff9b882ba44278321648677c90d0a.png

Time zone settings

Set the time zone.

Select Timezone.

image_1755662173234_272572b169b94deaadfce5de768aafc0.png

When the time zone list is displayed, specify the time zone for your area. For Japan, search for “/tokyo” and select “Asia/Tokyo”.

image_1755662193675_37ebdf7540d04078845f5b73b9af10b1.png

Make sure your time zone is selected.

image_1755662202914_e87cd3098ed44e1c965c4bde78a0f043.png

Run the installation

At this point, the Arch Linux installation settings required for Omarchy are complete. Now start the installation.

Select “Install”.

image_1755662239829_8711ee6d85734dddbd7b398dff5a7264.png

The settings will be displayed in JSON format, so review them briefly and click “Yes”.

image_1755662250127_20a33503083d4aaa9f9c79a034a26631.png

When the Arch Linux installation is complete, a screen like the one below appears. At this point, remove the installer USB and unmount the ISO from the virtual machine.

After unmounting the installer, select “Reboot system” to reboot.

image_1755662432018_7cd85668f92847288fac6792fd3dabef.png

Installing Omarchy

Now that Arch Linux is installed, install Omarchy.

image_1755663411264_a86c400e119a49979f3076b89dbcbeff.png

Run the Omarchy installation script with the following command:

wget -qO- https://omarchy.org/install | bash

If you do not need extra tools (Spotify, Zoom, etc.) and want to install only the bare minimum, use the following command.

If you’re a purist who doesn’t want Omarchy to install full-featured applications like Spotify, Pinta, LocalSend, OBS Studio, or any other applications in the GUI apps section, you can run the installer in “bare mode”. In that case, only the basic required system tools and Chromium, Alacritty, and neovim will be installed. You must perform other installations yourself.

wget -qO- https://omarchy.org/install-bare | bash

image_1755663443794_075c533a9a96474796fed2de89fc338a.png

The sudo password will be requested when the script runs. Enter the superuser password.

image_1755663457661_cff26b27628a4daab4f2ce6f8a97741e.png

You will be asked for some input during the installation steps. When asked to enter a “Name”, enter any name you like.

image_1755663495030_ce486a27edaa40d7b1303527d46c94ca.png

You will be asked to enter your email address, so enter any email address.

image_1755663503934_5177e0486b3745a88f4e4f6f5590a31b.png

After completing these steps, the installation will begin. Wait until the installation is complete.

After the installation is complete, the system restarts automatically. If you have disk encryption configured, you will be prompted for a password every time you reboot. Enter the disk decryption password.

image_1755672684108_cf8954dce8a34bddaa6ef8332c90604b.png

If you do not encrypt the disk, you will not be prompted to enter a password as shown below.

image_1755664617373_1d2712cf91f54a9290e3f0cf0ffbe358.png

The installation is complete when the desktop appears as shown below.

image_1755664891183_a06160b3702943f2a534d5b23fbc2290.png

Change keyboard layout (optional)

After installing Omarchy, the keyboard layout is automatically set to “US”. If you are using a Japanese keyboard, follow the steps below.

Launch the menu with “Super + Alt + Space” and open “Setup” → “Input”. image_1755665093470_3ce354fdd599492c9e14e3af428c92de.png

image_1755665588183_36e66d5a48c4400e9bf023ab6f5fc73b.png

The editor starts. The first time, Neovim installation begins. Wait for it to finish. image_1755665148935_080556a2400d4f54b9fcfdfe30f7dd92.png

Once the editor is available, uncomment kb_layout and specify jp. If you want to use multiple layouts, you can specify multiple layouts using “,”. image_1755665629775_039365bcd6ba41a9b533a149200a6ee6.png

image_1755665671433_98186a1660c14cc8b1c03a2708b9995c.png

Save with “:wq”. Note that this is still using the alphabetic keyboard layout. If you are using a Japanese keyboard, you can enter “:” by pressing “Shift + ;”.

image_1755665696367_8054b520cdc348c3926bfff30108d0d4.png

This changes the keyboard layout.

Change UI scale (optional)

Omarchy sets the UI scale to 2x by default. If you are not using a 4K monitor, the UI may look too large, so adjust it here.

Launch the menu with “Super + Alt + Space” and open “Setup” → “Monitors”.

image_1755665093470_3ce354fdd599492c9e14e3af428c92de.png

image_1755665107498_a9376a3264324fbf9b07ab6af8ac2d28.png

Change 2 to 1 in env = GDK_SCALE, 2. Change the auto at the end of monitor=,preferred,auto,auto to 1. The “1” specified here means 1x. If you specify “1.333”, it will be displayed at about 1.3x scale. Specify a scale that suits your environment.

image_1755665214624_d17cec812f3f40ecb2dd81d3a70e5872.png

image_1755665368324_4c10597217334ab79f4779b4ce9fa910.png

Save with “:wq”. The wallpaper may appear small, but it fixes itself when you open the menu. If it bothers you, try Relaunch or a similar action.

image_1755665412549_8c0de237b1a34bf8adf77c9bc180a7df.png

image_1755665762702_a9b3d30424514115ace5f509cb0f65e4.png

Japanese input settings (optional)

Earlier, I made the keyboard settings compatible with the Japanese keyboard layout, but Japanese input is still not possible in this state.

Therefore, we will install Mozc, an OSS version of Google Japanese Input, to enable Japanese input.

Enter the command below to install Fcitx5 and Mocz.

yay -S --needed fcitx5 fcitx5-configtool fcitx5-gtk fcitx5-qt fcitx5-mozc-ut

Enter the following command to open the Fcitx5 settings screen.

fcitx5-configtool

image_1755675590784_c7a46fec30e746f09e56ee154c6a6306.png

A notification will appear at the top of Fcitx5, so click “Restart”. image_1755675663767_c42a844f207f4f6e8dd83726371b13b8.png

Delete “Keyboard - English (US)” in Current Input Method and add “Keyboard - Japanese” and “Mozc”.

image_1755675718346_62f20f56e6f34d989a98be25873b145d.png

Click “Apply” at the bottom right and close the settings screen.

Now you can input Japanese. The input switching shortcut is “Ctrl + Space” by default. image_1755675864658_360fbbb5b10744f2ae60c7405aa0d962.png

Configuring a remote desktop environment using VNC (optional)

The settings above are enough for basic Omarchy use. This section is useful when installing Omarchy on a remote server. It may not be necessary if you are running it on a nearby device such as a laptop.

WayVNC configuration

If you install Omarchy on a remote server, you may need a remote desktop environment. Here I will introduce WayVNC, a VNC server compatible with Hyprland (Wayland).

Enter the command below to install WayVNC.

pacman -S wayvnc

The basic usage is as follows. With Hyprland, you can create a headless display and share that display via WayVNC.

Start the terminal with “Super + Enter”. Enter the following command to create a headless display. (HEADLESS-1 is an arbitrary name)

hyprctl output create headless HEADLESS-1

Enter the command below to start WayVNC.

wayvnc -o HEADLESS-1 0.0.0.0 5900

The WayVNC settings are now complete. VNC connection is now possible with {Omarchy IP address}:5900 from a remote client.

However, running this command every time after starting the server is troublesome, so automate it. Omarchy allows you to configure commands that run automatically after startup.

Open Omarchy’s autostart configuration file with the following command. (n is an alias for Neovim. Since the default vim is not included, use Neovim.)

n ~/.config/hypr/autostart.conf

Add the following content.

exec-once = bash -lc 'hyprctl output create headless VNC-1; \
  sleep 0.2; \
  hyprctl keyword monitor "VNC-1,1920x1080@60,auto,1"; \
  wayvnc -o VNC-1 -k jp 0.0.0.0 5900'

Save with “:wq”.

image_1755673987775_80ea2d9974d2459b8231545ccf593294.png

Now WayVNC will start automatically when the OS starts.

*If disk encryption is enabled, WayVNC’s automatic startup will not work until you enter the disk decryption password. Therefore, for this remote server, disk encryption was disabled.

Connection test from Windows

Install RealVNC, a VNC client, on Windows and try to connect. image_1755674129971_b8b68a71fa9544f58d97830265676c9c.png

A warning appears because TLS encryption is disabled by default. image_1755674140074_7dab3458e2844c1aa0007569492e5d43.png

I was able to connect to Omarchy via VNC.

image_1755674202628_50a7a914e4b544b486b25cd0899110e5.png

Here are some useful settings on the RealVNC side.

In the connected session, open RealVNC’s “Properties” (gear mark) and search for “DynamicResolution” under “Expert”. Setting this to “True” changes the resolution dynamically. Then, even if you change the window size, margins will not remain visible.

image_1755674344612_27dcebd18a6e4cf9b64bd00cebfda363.png

Additionally, if the mouse cursor and pointer dot are displayed separately and the delay bothers you, you can disable the dot display with the following settings.

Open RealVNC’s “Properties” (gear mark) and set both “DotWhenNoCursor” and “UseLocalCursor” to “False” from “Expert”. image_1755675153967_2f275f90478c4e4887794c600ef3e788.png

Conclusion

Omarchy is a project that brings the freedom of Arch Linux and the beauty of Hyprland within easy reach. It is recommended for those who want an environment they can use immediately without spending time on detailed setup. Since the base environment is already prepared, you can customize it to your liking. A good approach is to first create a working environment, then make adjustments little by little.

Subscribe to RSS?