Skip to content

Instantly share code, notes, and snippets.

@loukamb

loukamb/loukas_arch_notes.md

Last active July 5, 2025 19:30
Show Gist options
  • Save loukamb/3bb2d6c9f7acda962e5349a9ab078fcd to your computer and use it in GitHub Desktop.
Save loukamb/3bb2d6c9f7acda962e5349a9ab078fcd to your computer and use it in GitHub Desktop.
Download ZIP
Louka's Arch Notes
Raw
loukas_arch_notes.md

Louka's Arch Notes

A cheat sheet, notes sheet, and general guidance to setup a competent, stable, secure Arch Linux system. Written because some of my friends are looking into switching to Linux as Windows 10 falls out of support this year.

These notes will help you install an Arch Linux system, but also explain the packages you're installing and what they do, so you can better understand how a Linux system (in general) is structured.

Table of Contents

Why Arch?

  • Arch Linux has all the software. It fixes the problem of insufficient software support suffered on other distributions.
  • Arch Linux has the most recent software. Most distributions are versioned and it's likely you will run 1+ year old package versions on other distributions. On Arch, all system components are automatically built by Arch's servers and shipped to you.
  • Arch Linux's ecosystem has user-first software configuration. For example, Visual Studio Code from the code package comes with a patch to make the software source commandline flags from ~/.config/code-flags.conf (as commandline flags in shortcuts/launchers are not offered on every DE).
  • Arch Linux has a user-generated set of repositories called the AUR. If something is missing from Arch's main repositories, you can probably find it in there. This includes, for instance, cracked software/software mods/lesser-known software (like browser forks) :P, but also things like themes
  • Arch Linux allows you to opt into highly optimized, x86-64-v3 w/ LTO builds of packages. This is mostly unheard of on other distributions, except in from-source distributions like Gentoo, or a few rare less-supported ones like CachyOS.

Isn't Arch unstable?

There is a misconception that Arch Linux is "unstable". It is considered "unstable" because Arch Linux is easy to break due to the freedom provided, whereas other distributions tend to limit what you can do with the system. I never suffered a problem updating my OS. If an update can break your system, the Arch Linux team will literally post news on their website telling you so. Arch updaters will alert you if there are recent news before updating. The procedure to prepare your system for a potentially "breaky" update is usually one or two commands after updating.

Isn't Arch hard to install?

No. You no longer have to manually install Arch Linux as recent images now come with archinstall.

Installation

1. ISO

1.1. Download

Grab an ISO from a mirror here. This is a complete Arch installation environment.

1.2. Write to USB

Write it to a USB drive with Rufus or use Ventoy to make a multi-boot USB drive (recommended).

2. Boot

Boot into the USB drive. If you are using Ventoy, make sure to select the Boot with grub2 option. Pick the first option in Arch Linux's bootloader, which will copy the Arch ISO to RAM and boot into it. When you have reached the commandline, you can unplug your USB drive. Isn't this cool? Can't do this with Windows!

3. Preinstall

3.1. Notes on vim

Arch Linux comes preinstalled with vim, the best but also most confusing text editor of all time. You are free to use GNU's nano, which is also preinstalled. However, if you want to use vim like me, here are the only things you need to know for this guide:

  • You can insert text by pressing I to enter insert mode.
  • You can leave the current mode using Esc.
  • You can enter a command by typing : while not in any mode.
  • You can save and quit your file with :wq.
  • You can force-quit your file w/o saving changes with :q!.
  • You can delete the current line by double pressing D while not in any mode.
  • You can use your arrow keys to move around.

3.2. Setting up parallel installs

By default, Arch Linux's package manager, pacman, downloads only a few packages at a time. If you have a good enough Internet connection, you can probably bump up that number to something like 40, which is what I do. This is, generally, the first step I do.

Input this into the commandline after booting:

# Open pacman's configuration file.
# FYI, sudo is not necessary, because the ISO logs you into root by default.
vim /etc/pacman.conf

# Scroll down to ParallelDownloads, remove the '#', and set a higher number. Press I to enter insert mode (yes, you can delete stuff in insert mode)
#ParallelDownloads = 5
ParallelDownloads = 40

# Save with ":wq" in vim.
:wq

3.3. Updating the keyring

Arch Linux issues a new package keyring every few months. It's used to verify the integrity of download packages. If your ISO is recent enough, you probably don't have to do this, but I recommend doing it just in case to save you an ISO re-download when it grows old and moldy.

The -S option for pacman means you're requesting to install a package. -y downloads the latest package database from the repositories.

The archlinux-keyring package contains the latest repository keyring.

pacman -Sy archlinux-keyring

4. archinstall

After the above is done, invoke archinstall in the commandline. Long gone are the days of manually installing Arch, we now have an automated installer! Let's go through each option.

Press Space to toggle an option. Press Enter to confirm your selection(s) or input(s). Press Esc in a menu to cancel all changes and go back.

4.1. Archinstall language

Leave this as is.

4.2. Locales

Leave this as is. If you want more locales or layouts later, you can configure them in your desktop environment, which is recommended since doing it now will setup horrible keyboard defaults in a console environment.

On Linux, changing locales to anything but American English can break some software. For example, Steam will not run without the en-US locale installed. You can install additional locales later on, which won't cause problems, but you cannot do this in the installer.

4.3. Mirror and repositories

Open it with Enter, and select your country with Space. Press Enter to confirm your mirror selection.

Enable the multilib repository. This guide assumes you will also install multilib (32-bit) versions of some packages to enabling gaming.

4.4. Disk configuration

Open the menu, choose Use a best-effort default partition layout, and choose your preferred drive. For filesystem choice, the no-brainer option is xfs. Some Linux distributions default to btrfs, so you may have heard of it, but it is a more experimental filesystem (even though it is considered production ready). ext4 is stable but old, and other choices are probably not recommended.

If it asks if you want to setup /home on a separate partition, answer Yes if you want to encrypt your drive. If you do not want to encrypt your drive, feel free to answer No.

4.4.1. Encryption (optional)

Open the menu, select your drive and partition (your /home), then follow the prompts to setup a passphrase. You do not have to encrypt your root partition, as your user data will be stored in /home. When asked for a encryption type, choose LUKS. LVM is not necessary. Anything else should be self-explanatory.

Setting up additional drives (e.g. pre-existing encrypted drives) will be explained after installation.

4.5. Swap

If you have less than 32 GB of ram, leave this to Enabled. If you have more than 32 GB of ram, feel free to disable this. No special partitioning is needed as Arch Linux uses the new and improved zram technology! Woohoo!

4.6(a). Unified kernel image (UKI)

Note

This option may not be present. It will only be present on UEFI devices. If it isn't present, don't mind it, just go to 4.6(b).

Unified kernel images create a single binary with everything needed to boot Linux. If they are available, I suggest you enable them. They integrate better with UEFI and allow for Secure boot (!).

4.6(b). Bootloader

If your PC has UEFI, and you do not plan on dual-booting Windows, use systemd-boot, which will be most likely picked as the default.

If your PC has BIOS and/or you plan on dual-booting Windows (or another OS in general), pick Grub. Do note that choosing Grub will disable Unified kernel images.

Important

Keep this choice in mind! I will ask you to do something based on this choice later during the installation.

4.7. Hostname

Your computer's name. ASCII only characters, please.

4.8. Root password

Pick a root password, which will be used for system maintenance if something breaks. Something strong, and different from your user account's password.

Warning

It is possible to disable the root account later, but I don't recommend it because it will make system maintenance impossible (or more difficult if a live image on a USB drive somewhere) if you can't login.

4.9. User account

Go through the prompts, they are self-explanatory. When asked if the user should have access to sudo, say Yes.

4.10. Profile

Choose Minimal. Yes, even if you're setting up a server or a desktop environment. The dependencies offered in the Desktop profiles will be installed automatically anyway as you choose your desktop environment, lol.

4.11. Audio

You have two choices, PipeWire or PulseAudio.

  • If you have recent audio hardware, or audophile equipment (e.g. USB DACs, amplifiers, etc.), pick PipeWire.
  • If you have ancient audio hardware (think Dollar tree beige crackling microphones), or you are going to play music through weird audio protocols (e.g. audio through HDMI), pick PulseAudio.

4.12. Kernels

This is, arguably, the second most important chance (after your desktop environment). It can impact software usability and performance, but each kernel has its own set advantages and disadvantages. Here's a quick rundown:

  • linux is the all-around default. The traditional Linux kernel found in basically every distro.
    • The most extensively tested kernel by Arch maintainers. Guaranteed to work, unless there's some new features with weird bugs.
  • linux-hardened is a kernel with patches for increased security. Some kernel features, such as user namespaces, are disabled. Performance, surprisingly, is mostly the same as linux.
    • If you are on Nvidia, do not install this. User namespaces are necessary for GPUY drivers to work.
    • If you use Firefox, do not install this. Firefox leverages some features for sandboxing that this kernel disables.
    • If you have some funky networking equipment, do not install this. This kernel patches out support for some network stuff that could be vulnerable.
  • linux-lts receives no new feature updates for around 5-6 releases while bugs suffered by new features are worked on.
    • If you plan on running a server, you should install this. Arch's distribution of linux-lts comes with a few server-oriented optimizations.
    • This kernel is also good for overall system stability, since you won't accidentally receive a kernel update with a feature that is broken on your hardware.
  • linux-zen is a heavily patched Linux kernel that optimizes for responsiveness on desktop environments. Basically, the gaming kernel.
    • Do not install this if you want to do compute-heavy tasks on your PC. It increases visual responsiveness at the cost of reduced CPU throughput. linux or linux-lts are still excellent kernels for gaming, and the difference is usually unnoticeable.
    • You should install this one if you're setting up a desktop environment on a lower-end device (e.g. old laptops). The desktop will feel far smoother even if throughput is reduced.

In case of doubt, install multiple kernels (or all of them). You can choose to boot into the kernel you want! My personal preference as a programmer not doing anything intense other than gaming and streaming media over Plex is linux-zen, and I haven't noticed anything bad.

4.13. Network configuration

Choose Use NetworkManager. This will allow you to graphically configure things such as your Internet connection, but also Bluetooth and some other stuff. The ISO network configuration sucks and manual configuration isn't worth it. NetworkManager will set up any wired connections automatically anyway.

4.14. Additional packages

Press / and type away to search in the very big list. You want to install vim and git for post-installation configuration. Choose them with Space (or Tab if space just alters the search).

Warning

Do not install anything you think you need at this stage. We'll do it in a minute, bear with me.

4.15. Timezone

Choose your timezone. Self-explanatory.

4.16. Automatic time sync (NTP)

Leave as is. If it's disabled by default for some reason, enable it.

4.17. Install

Choose Install and let it install everything! There's nothing you need to do now.

When done, congratulations! The Arch Linux base system is in! But we're not done yet.

5. Postinstall configuration

We will now install the userland. You know, desktop environment, visuals, Steam, games, and all that stuff. Including drivers, BTW, which I know isn't part of the userland but whatever.

5.1. chroot

At the end of the installation, you will be asked if you want to chroot into your install. Select Yes. This will allow us to perform the rest of your system configuration before rebooting.

5.2. Installing kernel headers

Prior to doing anything else, we need to install your kernel headers. If they are missing, some software may fail to install if they add kernel modules like drivers or pre-boot software.

Software is installed through the pacman -S command, which I briefly explained above, except without the -y because we are already sync'd up with the remote repositories.

Each kernel has its own corresponding set of headers. Pick and choose (install multiple if you have multiple kernels, obviously):

Kernel Header package
linux linux-headers
linux-hardened linux-hardened-headers
linux-lts linux-lts-headers
linux-zen linux-zen-headers

For example, if I have linux-lts and I want to install its headers, I'd type the following into the chroot terminal:

pacman -S linux-lts-headers

5.3. Bootloader optimizations

We will now optimize your bootloader so Linux takes seconds to launch (*assuming good hardware and your BIOS doesn't take forever to hit the bootloader), also known as the "PewDiePie" build since his own Arch booted in seconds and it impressed the whole of X.

5.3.1. Setting up plymouth

plymouth is an optimized boot process for Linux that replaces the default kms (aptly named, IMO) module. We don't need to install it right now, but we can configure it so it is ready when it gets installed.

First, open /etc/mkinitcpio.conf in your text editor of choice (vim!), go down to HOOKS=(...), add plymouth after udev, and remove kms which is located between modconf and keyboard on the same line. Do not replace kms with plymouth, plymouth needs to be initialized earlier.

Note

FYI, the initcpio is the initial root filesystem mounted into ram by the kernel. It includes drivers, kernel modules, and any software that is expected to run in kernelmode. mkinitcpio is the script used by Arch Linux to build this initial root filesystem.

# Open the file.
vim /etc/mkinitcpio.conf

# Add 'plymouth' after 'udev', remove 'kms'.
HOOKS=(base udev plymouth...)

# Save file.
:wq

Note

If you install something that triggers the initcpio rebuild process (e.g. install a driver) without plymouth being installed, don't worry about it, the kernel will still boot fine as it skips over a module if it isn't found.

5.3.2. Setting up kernel boot parameters

Pick the next subsection corresponding to your bootloader choice. I hope you remember your bootloader choice! I told you to!

5.3.2(a). systemd-boot

If you are on systemd-boot, open /etc/kernel/cmdline in your text editor of choice, and append quiet splash to the single line.

5.3.2(b). Grub

If you are on Grub, open /etc/default/grub in your text editor of choice, and append quiet splash to the list of arguments in GRUB_CMDLINE_LINUX_DEFAULT.

Also, this is a good time to make sure part_gpt, part_msdos, luks, and encrypt are listed under GRUB_PRELOAD_MODULES. If any are missing and you want encryption to work, add them. This is not necessary for systemd-boot as it automatically includes encryption support.

5.4. Setting up your GPU drivers

GPU drivers are no longer a problem on Linux. I know they used to be a pain in the ass, but now it's just a matter of installing a few packages.

Every driver install command will also be installing plymouth, flatpak, and lib32-systemd. These packages ship kernel modules, and installing them alongside your GPU driver will minimize the amount of initcpio rebuilds, which usually takes 10-20 seconds each.

Pick the next subsection corresponding to your GPU brand.

5.4.1. AMD

Install the following packages:

  • mesa: AMDGPU drivers. The core of what you need.
  • vulkan-radeon: Vulkan support. Probably a good idea to have.
  • lib32-mesa: 32-bit version of mesa.
  • lib32-vulkan-radeon: 32-bit version of vulkan-radeon. Command looks like this:
pacman -S plymouth flatpak lib32-systemd mesa vulkan-radeon lib32-mesa lib32-vulkan-radeon

The above will trigger an initcpio rebuild. Wait until it completes.

5.4.2. Nvidia

If you don't care for gaming, skip this section. The Linux kernel ships with nouveau, which are open-source drivers for Nvidia GPUs.

Otherwise, if you do want to game, install the following packages:

  • nvidia-open-dkms: Nvidia drivers. The core of what you need.
    • dkms is the kernel module installation strategy, which compiles the module against your kernel for added compatibility.
    • open is the semi-open-source kernel module provided by Nvidia. It is recommended on newer GPUs.
  • nvidia-utils: Hardware encoding/decoding support, Vulkan support, and implements vram suspend/resume protocols when your computer goes to sleep. A must have.
  • lib32-nvidia-utils: 32-bit version of nvidia-utils.

There is no need for a 32-bit version of nvidia-open-dkms, in case you are wondering. Command looks like this:

pacman -S plymouth flatpak lib32-systemd nvidia-open-dkms nvidia-utils lib32-nvidia-utils

The above will trigger an initcpio rebuild. Wait until it completes.

5.5. Essential packages

Now, let's install some essential utilities that I believe are useful to most power users. If there are things you feel you really don't need, don't install them, but then don't complain that shit is broken later down the road.

  • curl: Maybe you won't use it, but scripts will.
  • wget: Maybe you won't use it, but scripts will.
  • unzip: Allows you to unzip a bunch of archives. Used by graphical archivers.
  • zip: Allows you to archive a bunch of files. Used by graphical archivers.
  • unrar: unzip, but for rar archives.
  • ffmpeg: Used for video thumbnailing in explorers and some media encoding/decoding.
  • libheif: Implements high efficiency image decoding.
  • webp-pixbuf-loader: Makes webp images less painful to work with in image editing software or viewers. It doesn't seem like it's important, but you will thank me later if you collect images like me.
  • gnome-keyring: Implements some basic auth providers for GPG/PGP, polkit stuff for permission control, and is used by Visual Studio Code and browsers to store secrets. Install this even if you're not going to use Gnome, almost everything in existence uses it.
  • libsecret: The secret library used by software when gnome-keyring isn't supported (mostly older software). May be already installed.
  • code: Visual Studio Code.
  • grim: Screenshooter. Without this, you probably won't be able to take screenshots, unless you will install Gnome (then this library isn't necessary).
  • slurp: Region selector for screenshots. Without this, you can only take fullscreen screenshots, unless you will install Gnome (then this library isn't necessary).
  • xdg-desktop-portal-gtk: Implements file pickers.
  • wl-clipboard: Implements the clipboard.
  • mpv, yt-dlp: High performance media player. Comes with a minimal GUI now. yt-dlp is included because mpv receives some nice functionality when it's installed. If you don't care for either, you can leave them out and install something like vlc instead.
  • ufw: Configure-and-forget firewall.
  • tailscale: Tailscale daemon. Used in many workplaces!
  • bluez, bluez-utils, blueman: Bluetooth support.
  • power-profiles-daemon: Allows you to toggle between CPU power modes (performance, balanced, power saver, etc.)
  • noto-fonts, noto-fonts-emoji, noto-fonts-cjk: Implements base system fonts with complete Unicode support. Necessary if you want to see Kevin's phallic username on Discord.
  • ttf-liberation, ttf-jetbrains-mono, ttf-font-awesome: These are actually used by some Linux software by default and they didn't bother to include them in their dependencies, so we install those just in case.

Here's the command:

pacman -S --needed curl wget unzip zip unrar ffmpeg libheif webp-pixbuf-loader gnome-keyring libsecret code grim slurp xdg-desktop-portal-gtk wl-clipboard mpv yt-dlp ufw tailscale bluez bluez-utils blueman power-profiles-daemon noto-fonts noto-fonts-cjk noto-fonts-emoji ttf-liberation ttf-jetbrains-mono ttf-font-awesome

Then, enable the newly installed services with the following command:

systemctl enable tailscaled ufw bluetooth

Don't worry about stuff like browsers, we're getting there, hold on!

5.6. Desktop environment

As every desktop environment is different, it would get verbose for me to list how to install each of them. Therefore, I will show you how to install either Gnome, Sway, or Hyprland.

  • Gnome is your traditional PC environment. Cool toolbars, docks, and an ecosystem to work with. It isn't my preferred one, but it is the most supported in the Linux world.
  • Sway is the ubiquitous Wayland compositor (also known as window managers). Lightweight, well-made, and definitely more efficient to work with than a traditional desktop. However, no such thing as windows, only automatically resized surfaces.
  • Hyprland is a Wayland compositor known for its looks, adaptations for gaming, and a porn addicted developer that is very loud. No practical advantages over Sway other than HDR support and some gaming-related options that can help.

I personally recommend Sway, even if you plan on gaming. When you learn how to use it, it's really hard to go back to a normal desktop environment. They feel slow and bloated. Gaming works as well on Sway as on Hyprland, but if you use some specialty rendering configuration like HDR or game-specific upscaling, Hyprland will be better. Hyprland can also made to look better than Sway, but IMHO that's not something to care about.

All three listed options work natively with Wayland. All three offers backwards compatibility with X11 when needed. Do not worry about this. Always remember that you can always install another environment later. You can even install multiple and boot them separately if you want to.

5.6.1. Gnome

Install the following packages, which will provide a minimal but useful Gnome ecosystem:

  • gdm: Gnome display manager. Used to log into your account.
  • xorg: X11 provider for Gnome's backwards compatibility with X11 programs. You don't have to install this, but you probably should.
  • gnome-shell: The Gnome desktop itself.
  • gnome-tweaks: Allows you to fine-tune some Gnome stuff, like middle-click pasting, window titlebar buttons, fonts, etc.
  • gnome-control-center: Basically, the settings program.
  • gnome-software: Allows you to install software with a graphical interface. If you plan on only using the package manager for your programs, you don't need this.
  • gnome-system-monitor: For all intents and purposes, your process manager.
  • gnome-console: Terminal program.
  • gnome-clocks: Provides a clock.
  • gnome-weather: Provides cool weather info.
  • gnome-calendar: Provides a calendar, because Gnome decided clocks and calendars should be separate things.
  • gnome-text-editor: Linux notepad.
  • loupe: Image viewer.
  • sushi: File previewer. Press Space while selecting a file to open a preview window. Use Left or Right keys to move between files.
  • evince: Document (PDF) reader.
  • nautilus: File explorer.
  • gnome-shell-extension-appindicator: Provides a tray, which for some reason, is still not natively implemented on Gnome, lol.
  • gnome-shell-extension-dash-to-panel Optional, but if you want a standard dock/taskbar, install this. Otherwise, you have to use Gnome's Super-based overview to switch between windows.
pacman -S --needed gdm xorg gnome-shell gnome-tweaks gnome-control-center gnome-software gnome-system-monitor gnome-console gnome-clocks gnome-weather gnome-calendar gnome-text-editor loupe sushi evince nautilus gnome-shell-extension-appindicator gnome-shell-extension-dash-to-panel

Then, enable the gdm service with the following command:

systemctl enable gdm

That's it, Gnome is setup. Nothing else is necessary.

5.6.2. Sway or Hyprland

First, install the following global packages that are used on both Sway and Hyprland.

  • uwsm: Universal Wayland Session Manager. Used to configure user sessions with sane defaults on Wayland compositors, and also provides a nice graphical selector to choose between compostiors.
  • mako: Notification daemon. Since it's a user daemon, there's no service to enable.
  • waybar: Provides a kind of "taskbar" (even though it isn't one).
  • wmenu: Provides a program launcher. Replacement for your start menu.
  • j4-dmenu-desktop: By default, wmenu only lists binaries in /usr/bin. This is used to have it list actually installed programs, including those installed outside of /usr/bin.
  • foot: Your favorite. It's a terminal. Not smelly, unlike what the name implies.
  • swayimg: No-nonsense image viewer. Yes, it's also used on Hyprland, even though the name suggests otherwise.
  • dolphin: File manager. Much better than Gnome's!
  • wlr-randr: Used to retrieve screen info.

Command:

pacman -S uwsm mako waybar wmenu j4-dmenu-desktop foot swayimg dolphin wlr-randr

Enable the waybar user service with this command.

Note

Notice we are prefixing this command with sudo -u YOUR_USERNAME_HERE? This is because some commands must run in a non-root context to work. Remember this, because soon enough, we'll be using the living shit out of this pattern!

sudo -u YOUR_USERNAME_HERE systemctl --user enable waybar
5.6.2(a). Sway

Install the following software:

  • sway: The compositor itself.
  • swaylock: Locks your screen.
  • swayidle: Runs commands when you have idled for a certain amount of time. Usually ends up invoking swaylock.
  • swaybg: Provides a background.
  • xdg-desktop-portal-wlr: Provides screencasting functionality.

Command:

pacman -S sway swaylock swayidle swaybg xdg-desktop-portal-wlr

Warning

If you are on Nvidia, Sway will bitch and moan at you using proprietary drivers if you have them installed. To fix this, open /usr/share/wayland-sessions/sway.desktop and append --unsupported-gpu after Exec=sway. Don't worry, it works anyway.

5.6.2(b). Hyprland

Install the following software:

  • hyprland: The compositor itself.
  • hyprlock: Locks your screen.
  • hypridle: Runs commands when you have idled for a certain amount of time. Usually ends up invoking hypridle.
  • hyprpaper: Provides a background.
  • xdg-desktop-portal-hyprland: Provides screencasting functionality.
  • hyprpolkitagent: Provides a fancy password form when you do some stuff with systemd.

Command:

pacman -S hyprland hyprpaper hypridle hyprlock xdg-desktop-portal-hyprland hyprpolkitagent

Enable the hyprpaper and hypridle user services with these commands.

sudo -u YOUR_USERNAME_HERE systemctl --user enable hyprpaper.service
sudo -u YOUR_USERNAME_HERE systemctl --user enable hypridle.service
5.6.3. .bash_profile

Note

If you are on Gnome, skip this section.

To enable uwsm and use it to boot into your Wayland compositors, as well as to specify dark mode, you need to edit your .bash_profile.

First, cd into your home directory with the following command:

cd /home/YOUR_USERNAME_HERE

Then, open .bash_profile with your text editor of choice. The file already exists, then add the following text:

# This specifies dark mode.
export GTK_THEME=Adwaita:dark

# This launches uwsm after logon.
if uwsm check may-start && uwsm select; then
  exec systemd-cat -t uwsm_start uwsm start default
fi
5.6.4. Dotfiles and display setup

Note

Monitor/display setup and dotfiles (Linux software configuration files) are in the same section because in Linux philosophy, monitor configuration is not a system concern but a user concern, and therefore they are configured in dotfiles located in the user's directory. This is different from both macOS and Windows, where monitor configuration is not user-specific and configured the same as any other hardware.

First, cd into your home directory with the following command. if you haven't done so already in 5.6.3:

cd /home/YOUR_USERNAME_HERE

Before we proceed, let's setup some configuration files that provides the following common sense keybinds across Sway and Hyprland (Mod = Windows key), alongside some other sane defaults for software. I wrote them myself! (not applicable to Gnome, but you still get some other stuff, see below).

Do note that visuals may not necessarily be to your taste. Don't worry, we'll look into changing those afterwards.

Keybinds (Sway & Hyprland only)
Action Keybind
Open terminal Mod+Enter
Program launcher Mod+D
Close window Mod+Shift+Q
Move window Mod+Left Mouse
Resize window Mod+Right Mouse
Toggle tabbed layout Mod+W
Toggle fullscreen view Mod+F
Take a screenshot PrntScr
Exit compositor Mod+Shift+E
Sane defaults
  • Visual Studio Code automatically opts into Wayland rendering. This means it won't look stretchy and blurry.
  • Spotify also opts into Wayland rendering.
    • Don't worry, I'll teach you how to install Spotify later.
  • swayimg has a non-eye-hurting background.
  • waybar has an actual, useful taskbar, alongside a tray, a volume icon, an idle inhibitor (prevents computer from going to sleep when enabled), and a keyboard layout switcher.
  • foot, your default terminal, looks good!

To install those dotfiles, run these commands while cd'd into your home directory:

sudo -u YOUR_USERNAME_HERE git clone https://github.com/loukamb/dotfiles
sudo -u YOUR_USERNAME_HERE cp -r ./dotfiles/. .config

Then, you must install the appropriate waybar configuration. Cd into /home/YOUR_USERNAME_HERE/.config/waybar and run ls to see separate waybar configs, such as config.jsonc.sway and config.jsonc.hyprland. rm the existing configuration with rm config.jsonc, then mv the proper configuration into config.jsonc with mv config.jsonc.EXT_HERE config.jsonc. If you forgo this step, the current waybar will work, but will look wonky or some features won't work. FYI, the default config.jsonc is a symlink to ./config.jsonc.sway.

Finally, you must configure display information. On Sway, it will be found in /home/YOUR_USERNAME_HERE/.config/sway/config. On Hyprland, it'll be at /home/YOUR_USERNAME_HERE/.config/hypr/hyprland.conf. Both have mildly different syntaxes for display configuration, but they're similar enough so that you'll know what's going on. Let's take a look at, for example, Sway's display configuration, which is as such in my dotfiles:

output * bg /storage/MEGA/Pictures/Wallpapers/1725308238042220.jpg fill

output DP-3 position 0 0 scale 2
output HDMI-A-1 position 1920 0 scale 2

The first line is self-explanatory, defining a wallpaper for both monitors. To set a wallpaper, just change the path later on. If you won't have one by the time you reboot, just comment the line out (the file you opened will have plenty of examples of comments).

The two other lines define your monitor positions and scaling. In the example above, my left monitor is at x/y coordinates 0 0, and receives 2x scaling. My second monitor is located at x/y coordinates 1920 0, and also receives 2x scaling.

However, both of my monitors are 3840x2160, so why did I set the second one at x=1920 instead of x=3840? Because of 2x scaling. The coordinates use scaled pixels, not absolute pixels, so if you're scaling at a certain number, divide your resolution by that scale. 3840 / 2 = 1920, so therefore I place my second monitor at x=1920.

And no, you are not supposed to guess your monitor's names. I made you install wlr-randr earlier for the purpose of obtaining this information. Simply run wlr-randr and you will see your monitor's shorthand identifiers before their long names. Use those in your configuration. Here's my own wlr-randr output:

[louka@desktop ~]$ wlr-randr
DP-3 "LG Electronics LG HDR 4K 009NTZN19437 (DP-3)"
  Make: LG Electronics
  Model: LG HDR 4K
  Serial: 009NTZN19437
  Physical size: 700x400 mm
  Enabled: yes
  Modes:
    3840x2160 px, 59.997002 Hz (preferred, current)
  Position: 0,0
  Transform: normal
  Scale: 2.000000
  Adaptive Sync: disabled
HDMI-A-1 "LG Electronics LG HDR 4K 009NTQD2C084 (HDMI-A-1)"
  Make: LG Electronics
  Model: LG HDR 4K
  Serial: 009NTQD2C084
  Physical size: 700x400 mm
  Enabled: yes
  Modes:
    3840x2160 px, 60.000000 Hz (preferred, current)
  Position: 1920,0
  Transform: normal
  Scale: 2.000000
  Adaptive Sync: disabled
5.6.5. AUR manager

While still cd'd into your home directory, let's setup yay, your AUR manager. An AUR manager installs user-generated packages from the Arch User Repository (AUR), which is useful if you want to install anything that isn't open-source software, or lesser-known stuff like browser forks. In this guide, we'll use it to install some very useful things.

Run these commands while in your home directory:

# Clone the yay binary.
sudo -u YOUR_USERNAME_HERE git clone https://aur.archlinux.org/yay-bin.git

# Get into the yay directory.
cd yay-bin

# Install yay. Makepkg will break your system if used as root, so yes, we're still using sudo -u here.
sudo -u YOUR_USERNAME_HERE makepkg -si

Then, install the following using yay. Unlike pacman, yay -S will install stuff without confirmation, so be sure of what you typed!

  • arch-update: Provides a all-in-one update/upgrade script.
  • xpadneo-dkms: Provides drivers for Xbox controllers. If you don't have Xbox controllers, feel free to not install this. PlayStation controllers work out of the box, interestingly enough (anecdotally).
  • code-marketplace: Enables Visual Studio Code's marketplace. By default, open-source builds of VSCode are not allowed to tap into Microsoft's extension store, but this fixes it :P

When asked to cleanBuild or check diffs, feel free to answer No (N). When asked if you'd like to keep make deps, answer Yes (y), because otherwise every time one of those packages update you will have to reinstall them so why not install them in advance?

Command:

# 'yay' always requires that you are in your user's own context.
sudo -u YOUR_USERNAME_HERE yay -S arch-update xpadneo-dkms code-marketplace

Enable arch-update's tray icon with the following command:

sudo -u YOUR_USERNAME_HERE arch-update --tray --enable

5.7. Non-essential software

Okay, now let's install the GUI programs we know and love.

5.7.1. Browser

By default, Arch Linux's main repositories offers firefox and chromium. If you want anything else, like a corpo browser (e.g. Google Chrome, Microsoft Edge), or a privacy-oriented fork (e.g. LibreWolf, Ungoogled Chromium), you have to use the AUR.

Note

Reminder that to install a package from Arch's main repositories, you use pacman -S. To install a package from the AUR, you use sudo -u YOUR_USERNAME_HERE yay -S.

Here's a table with available packages for some common browsers:

Browser Package Fork of Notes
Firefox firefox N/A N/A
Chromium chromium N/A N/A
LibreWolf librewolf-bin (AUR) Firefox Privacy-oriented Firefox w/ uBlock Origin pre-installed. This is what I use!
Zen zen-browser-bin (AUR) Firefox Firefox but sexy, a bit experimental though
Floorp floorp-bin (AUR) Firefox Firefox patched for performance & brings back old UIs (optional)
Ungoogled Chromium ungoogled-chromium-bin (AUR) Chromium All the good of Chromium without spyware
Brave brave-bin (AUR) Chromium The furry browser and 3ds' favorite

Warning

If you are installing a Chromium-based browser, make sure to enable Wayland support. Otherwise, it will launch in X11 mode by default, and will look like shit. To do so, go to chrome://flags, search Ozone, and set the Ozone platform to Wayland. This is why Firefox wins.

5.7.2. Office

Install libreoffice-fresh. There is also libreoffice-still, which is the LTS version of LibreOffice. The fresh version is usually better, in my experience, since it ships the latest features.

For spellchecking, install hunspell-en_US (assuming you're an American). Other locales can be installed by just changing the name, so if you're Bri'ish, you probably want to install hunspell-en_GB, for example.

If you want Microsoft Office, you're in luck! Microsoft ships a disabled, shitty, barely working version on their website. If you want the real office, buy a Macbook or install Windows in a VM.

5.7.3. Image editing

Install gimp as a Photoshop replacement. Yes, GIMP used to be a joke, but 3.0 recently came out and it's wonderful now.

If you want to draw, install krita. Krita however isn't really good for editing.

If you want a Paint.NET replacement, I have two choices for you:

  • pinta (AUR) is a remake of Paint.NET for Linux. It is, however, terrible. Learn GIMP if you can, but this is the closest you'll get to Paint.NET.
  • PhotoPea is a competent replacement for Paint.NET. It is however web-based. That's what I used before learning GIMP.
5.7.4. Streaming

Install obs-studio. Everything will work out of the box.

5.7.5. Discord

Three choices:

  • Install discord. Mostly everything will work out of the box, except screensharing and Wayland support, which will make everything look blurry and disgusting.
  • Install vesktop-bin (AUR). Yes, it's not an official Discord client, but it has built-in Wayland and screensharing support.
  • Use Discord in your browser, which is what I do. Yes, screensharing works in the browser. Cool, isn't it?
5.7.6. Spotify

Install spotify-launcher, then add the following into ~/.config/spotify-launcher.conf to enable Wayland and HiDPI support: (change scale factor as needed)

[spotify]
extra_arguments = ["--force-device-scale-factor=2.0","--enable-features=UseOzonePlatform", "--ozone-platform=wayland"]

Note

These configuration files are why you are using Arch Linux! These do not exist on other distributions, and you would have been forced to launch these applications from the terminal to make them work! (or fuck around with endless .desktop files in /usr/share/applications)

5.7.7. Dotnet

Since I know some of you are .NET developers, you can install .NET (and ASP.NET support) with dotnet-sdk and aspnet-runtime. Then, add the following line to your user's .bash_profile under the export GTK=... line to enable use of dotnet tools (such as dotnet ef):

export PATH="$PATH:~/.dotnet/tools"

5.8. Finishing up

After you're done with all this, simply type in exit, and you'll leave the chroot.

Congratulations, your system is ~95% done! You can now reboot with systemctl reboot!

6. Post-reboot configuration

After rebooting, you will be able to login. If you installed a Wayland compositor, you will have a selection of compositors to choose from. If you installed Gnome, you will have a fancy login screen. Type in your information and you'll be in!

To access a terminal on a Wayland compositor, press Mod+Enter. To access a terminal in Gnome, launch it by pressing Mod and typing in Console (or just pick it in the program launcher).

We're not done, though. Let's go through a few last things to tweak with.

6.1. Gnome

Open Gnome Tweaks by pressing Mod and typing in tweaks. Go through the options, but most importantly:

  • Disable middle-click paste. This feature sucks.
  • Enable minimize and maximize window controls. Yes, Gnome, by default, does not have them.
  • Disable modal windows attaching to their parents.

Then, open Gnome Extensions (same procedure as above for search for extension instead of tweaks), enable AppIndicators to provide a system tray, and optionally, Dash-To-Panel (DTP) for a taskbar. Feel free to go through DTP's configuration to customize how it looks.

6.2. Sway/Hyprland

On Sway, open ~/.config/sway/config in your text editor of choice and look through the options. You can change border sizes, gaps, colors, keybinds, and some other things such as your wallpaper (if you have one now). To reload your Sway configuration, press Mod+Shift+C.

Sway Wiki can be found here for more documentation.

On Hyprland, open ~/.config/hypr/hyprland.conf in your text editor of choice and look through the options. The same options will be available, albeit in a mildly different format. Hyprland will automatically reload your configuration when it detects a change to the file.

Hyprland Wiki can be found here for more documentation.

6.3. Additional drives

Note

If you are on Gnome, these steps are optional as you can mount drives from the file explorer, but still recommended if you want your other drives to auto-mount.

6.3.1. Standard partitions

If you have external drives, you must configure them by adding their UUIDs and their filesystem information to /etc/fstab (which quite literally means "filesystem table"). Here is an example fstab entry:

UUID=d06cc6ee-44ad-4d20-be35-42a8a6ccedae /storage2 xfs defaults 0 2
  • UUID=... is your partition's ID, which I feel is quite obvious.
  • /storage2 is the location where your drive will be mounted. What I usually do is create /storage{n} folders for every partition, then I assign myself ownership with sudo chown louka /storage{n}.
  • xfs is the filesystem type.
  • defaults is a comma-separated array of filesystem options. I leave it as defaults.
  • 0 2 are mounting priorities. Root partitions should be mounted as 0 1, and anything else as 0 2.

The procedure to add drives is simple: use the blkid command to obtain your drivers' identifiers, make a folder for every drive, then create the corresponding entries in /etc/fstab (make sure to open this file with sudo, as it is a system file! otherwise, you will have errors while saving).

6.3.2. NTFS (Windows) partitions

Caution

It is highly recommended that you avoid using NTFS partitions as much as possible as Linux software (such as Steam, of all things) can be wonky with them, esp. regarding symlinks. There is a tool called ntfs2btrfs (AUR) that can convert in-place your filesystem into the natively supported btrfs filesystem, but be careful!

If you have a NTFS drive, install the ntfs-3g package, then use the ntfs-3g filesystem types and the following options (replacing defaults) in your /etc/fstab entries:

uid=userid,gid=groupid,dmask=022,fmask=133

Note

The variables userid and groupid are most likely going to be 1000 if you are the first non-root user on your system. If not, use id -g to get your group ID and id -u to get your user ID.

There is no support for BitLockered drives. You should do a proper, Linux-native encrypted setup. Speaking of which...

6.3.3. Encrypted partitions

Is it embarassing to say I have never setup an encrypted partition manually? I always did it through archinstall. Regardless, instead of fucking up your shit with half-understood instructions, I leave you this wonderful wiki page that, at first glance, seems to provide everything you need to know about setting up an encrypted partition with cryptsetup. It is very easy to do so.

6.3.4. Saving changes

Changes to /etc/fstab should take effect immediately. At least, on most desktop environments. If not, use sudo mount -a.

Changes to /etc/crypttab will only take effect after a reboot.

6.4. Gaming

6.4.1. Steam

You can install Steam with steam. That's it. It will run out of the box, provided you followed all my instructions. Do note that Steam will look blurry (except on Gnome) because it only supports X11 and there's nothing you can do about it. However, that shouldn't be a problem.

Enable Steam Play in Steam settings under the Compatibility tab and you'll be able to play all your Windows games! No extra setup needed, except for some rendering-related quirks. See the next section.

6.4.2. Gamescope

Note

This is not necessary on Gnome, but can be done anyway.

Some games won't support Wayland, which may make them look blurry on non-Gnome compositors. There is, however, an easy fix for this using Gamescope, which is thankfully shipped by Arch Linux.

Gamescope is Valve's special environment for rendering games on Linux. Not only does it fix X11's insane quality-destroying output scaling but it also allows HDR output on Wayland compositors that doesn't support it, which is currently only Sway as both Hyprland and Gnome support HDR.

You can install Gamescope from the gamescope package. To use Gamescope, add these commandline parameters to each game on Steam (you can do so in Steam's game properties) you want to fix if they don't support Wayland, or if you want to play with HDR:

gamescope -W WIDTH -H HEIGHT -r FPS --hdr-enabled -- %command%

Replace WIDTH, HEIGHT, and FPS with the desired resolution and framerate. Now, the game will launch, look good, and have HDR support. You can also enable variable refresh rates with --adaptive-sync if your GPU and monitors support it.

7. System maintenance

If you followed all my instructions right, you should now have a fully complete, working Arch Linux system. Maybe I missed something or I miswrote something, but you know where to find me.

Now, here are some general Linux maintenance instructions.

7.1. Updating your system

You can update your system by invoking arch-update in a terminal, no sudo necessary, it'll ask for permissions exactly when needed.

If arch-update tells you to read the news, read the motherfucking news. Arch Linux only publishes news when they know they shipped an update that could break existing systems, so read up! Generally, they'll prescribe you only a command or two before you update.

7.2. Installing shit from the AUR

The AUR is cool because it has so many things but you need to check individual packages and make sure (1) they're not ratted, and (2) they're well-maintained. This is why AUR packages have comments on their pages. If you install random stuff from the AUR without checking, you can easily break your system due to moldy packages or infected ones.

7.3. Deleting packages

You can delete packages with pacman -Rns.

7.4. Oh no! Something broke!

7.4.1. ...but I can still boot!

Relax and boot into the fallback entry in your bootloader, then log into root. If something fails during boot, it will ask you to log into root anyway in an emergency shell.

The procedure, generally, is to check for failed units with systemctl --failed. Check what errored, then look-up their errors. Look for errors in the log files located in /var/log/, as well as messages logged in the systemd journal using journalctl -b.

7.4.2. ...but I can still login!

If you can login but you can't boot into Gnome or your Wayland compositor, then just look for errors in the log files located in /var/log/, as well as messages logged in the systemd journal using journalctl -b.

If it's a problem with your Wayland compositor, try running the compositor directly in the terminal. Run sway or hyprland, for example, and check the output. Chances are, you will find your problem.

7.4.3. ...but I can't boot! It loads infinitely!

Stuck at the spinner? Press Esc and look. That will switch to verbose output mode. From experience, this usually occurs because the system is waiting for a drive from /etc/fstab or /etc/crypttab to appear but it never does. When that happens, systemd will wait for exactly 1 minute 30 seconds before booting in an emergency shell. If that happens, log into root when you're at the emergency shell, run blkid to see if your drives are detected, and check if you didn't make any mistakes in /etc/fstab or /etc/crypttab.

Otherwise, again, boot into fallback mode and check the journal.

7.4.4. ...but I can't boot at all! There's no output.

No bootloader? That's problematic, but it can be solved. Boot into your live USB and when you're at the shell, use blkid to find your partition's location in /dev, then mount it with mount /dev/drive_here /mnt.

Important

If you are on UEFI, also take care to mount your EFI partition to /boot after mounting your root partition. The EFI partition is the one with filesystem type vfat as returned by blkid.

Afterwards, run arch-chroot /mnt to "pseudo-boot" into your system, and look for errors in the log files located in /var/log/, as well as messages logged in the systemd journal using journalctl -b.

If you think it's a kernel problem, re-run one of the commands above to install your GPU driver. That sounds stupid, but it will force the kernel to rebuild itself. Reboot and check.

If you think it's a bootloader problem, then follow either of the below instructions depending on your chosen bootloader:

7.4.4(a). systemd-boot

exit from the chroot, then run the following command:

bootctl --root=/mnt install
7.4.4(b). Grub

Within the chroot, run one of either command if you're on UEFI or BIOS:

# Run on UEFI
grub-install --target=x86_64-efi --efi-directory=/boot/efi

# Run on BIOS
grub-install --target=i386-pc /dev/PATHTODEVICE

Make sure to replace /dev/PATHTODEVICE with the path to your device. Use lsblk to find out which device path it is.

7.4.5. ...shit still doesn't work and I hate you!

Contact me for assistance or re-install your OS. In other words, "works on my machine".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment