CachyOS + niri (Wayland) setup with a Tokyo Night theme, made for a CachyOS install with the niri desktop, tested on a ThinkPad T480. The niri and login-screen themes are Tokyo Night; the Noctalia shell uses the Oxocarbon community palette.
On top of what CachyOS installs, it adds:
- a niri config with Spanish/English keyboard layouts and vim-style keys;
- Noctalia (the shell CachyOS ships) set up to match: bar, launcher, notifications and lock screen;
- zsh with starship, Neovim, Doom Emacs, and Rose Pine GTK/Qt themes;
- scripts that install the packages, link the files, set up the desktop and the editors, and check the result.
Quick start, on a fresh CachyOS install with the niri desktop (details in Installation):
git clone https://github.com/GerMP21/dotfiles.git ~/dotfiles
~/dotfiles/install-packages.sh # packages
~/dotfiles/setup-dotfiles.sh # link the configs into ~, copy the fonts
~/dotfiles/setup-desktop.sh # themes, folders, services, zsh as login shell
~/dotfiles/setup-editors.sh # Doom Emacs and Neovim plugins (the slow one)
~/dotfiles/verify.sh # check everything- Repository layout
- What you get: components and features
- Keybindings
- Customizing: keys, Noctalia, Doom modules, Neovim
- Dependencies
- Installation
- The scripts in detail
- Testing in a virtual machine first
- Going back to your old setup
- Troubleshooting
dotfiles/
├── home/ everything that goes into ~, laid out as in ~
│ ├── .zshenv .zprofile .zshrc .gtkrc-2.0 .gitconfig
│ ├── .icons/default/ default cursor theme
│ ├── .config/ niri, noctalia, nvim, doom, gtk-*, Kvantum, qt5ct, qt6ct,
│ │ xdg-desktop-portal, alacritty, ardour-x (Openbox for Ardour),
│ │ starship.toml, mimeapps.list (default apps)
│ └── .local/ share/: fonts (copied), wallpaper, goodvibes radio stations
│ bin/keybinds: the Mod+Shift+H cheat sheet
│ bin/ardour-x: starts Ardour in its own X server (Mod+Shift+D)
├── packages.txt packages from the CachyOS/Arch repos (pacman)
├── packages-aur.txt packages from the AUR (paru)
├── packages-pipx.txt Python tools (pipx)
├── install-packages.sh installs the three lists
├── setup-dotfiles.sh links home/ into ~ and copies the fonts; nothing else
├── setup-desktop.sh themes, folders, services, zsh as login shell
├── setup-editors.sh Doom Emacs, Neovim plugins, parsers and language servers
├── setup-login-screen.sh optional: SDDM login theme, background and profile picture
├── setup-yabridge.sh optional: Windows VST3/VST2/CLAP plugins through Wine (yabridge)
├── system/sddm/ the login theme (tokyo-night/), background and avatar.jpg
└── verify.sh checks all of the above, plus the boot setup; changes nothing
home/.config/niri becomes ~/.config/niri, and so on. setup-dotfiles.sh symlinks everything from home/ into ~, so editing a file in ~/.config edits it in the repo, and git diff shows your changes. Only the fonts are copied. That's all setup-dotfiles.sh does: no downloads, no sudo. The themes and Doom Emacs aren't in the repo; setup-desktop.sh and setup-editors.sh download them.
| Role | Tool | Config |
|---|---|---|
| Window manager | niri (scrollable tiling) | home/.config/niri/config.kdl |
| Shell | Noctalia (installed by CachyOS): bar, launcher, clipboard history, notifications, volume/brightness popups, control center, lock screen, wallpaper, password prompts | home/.config/noctalia/config.toml |
| Login screen | SDDM (installed by CachyOS) with a Tokyo Night theme: background, square profile picture, clock | system/sddm/, installed by setup-login-screen.sh (optional) |
| Wallpaper | Raphael's The School of Athens (public domain), shown by Noctalia | home/.local/share/backgrounds/wallpaper.jpg |
| Terminal | Alacritty (installed by CachyOS) | home/.config/alacritty/alacritty.toml |
| Shell | zsh + starship | home/.zshenv (environment, PATH), home/.zprofile (login), home/.zshrc (interactive), home/.config/starship.toml |
| Editors | Neovim (lazy.nvim), Doom Emacs | home/.config/nvim/, home/.config/doom/ |
| GTK theme | Rose Pine (Rosepine-Dark, Rose-Pine-Moon icons, Sunity-cursors) |
home/.config/gtk-3.0/, home/.config/gtk-4.0/, home/.gtkrc-2.0, home/.icons/ |
| Qt theme | Kvantum rose-pine-foam + qt5ct/qt6ct |
home/.config/Kvantum/, home/.config/qt5ct/, home/.config/qt6ct/ |
| Portals | xdg-desktop-portal (file pickers through GTK, screencasting through GNOME) | home/.config/xdg-desktop-portal/niri-portals.conf |
| Fonts | JetBrains Mono / Iosevka Nerd Font (packages); CatV, Feather, Grape Nuts (bundled); the generic monospace font set to JetBrainsMono Nerd Font |
home/.local/share/fonts/, home/.config/fontconfig/fonts.conf |
| Default apps | Loupe for pictures, VLC for videos, File Roller for archives | home/.config/mimeapps.list |
| Git | git, with GPG signing and gh as the credential helper |
home/.gitconfig |
- niri
- Spanish (
es) and English (us) keyboard layouts: Spanish is the default,Mod+Ctrl+Spaceswitches, and the bar shows the current one. - Touchpad tap-to-click, natural scrolling, and disable-while-typing.
- Focus follows the mouse.
- 8px gaps, a 2px Tokyo Night focus ring and rounded corners.
- Preset column widths (1/3, 1/2, 2/3).
- A flat Tokyo Night background in the overview (
Mod+Tab). - Starts Noctalia and the Emacs daemon at login.
Mod+Shift+Hshows a compact cheat sheet of every binding in columns, read live from the config; niri's own overlay doesn't pop up at login.
- Spanish (
- Noctalia (Oxocarbon community palette, JetBrains Mono font):
- Bar left: launcher, battery, CPU, RAM, disk.
- Bar center: niri workspaces.
- Bar right: keyboard layout (
es/us), network, Bluetooth, volume, power profile, clock, tray, notifications, control center, session menu. - Clicking network, Bluetooth or volume opens its panel. The control center (
Mod+A) has Wi-Fi, Bluetooth, audio and power settings in one place. - Launcher (
Mod+D) with a calculator (/calc) and emoji (/emo), and clipboard history (Mod+V). - Popups for volume and brightness changes, and password prompts when an app needs admin rights.
- Changes made in its Settings window (
Mod+Shift+A) are saved to~/.local/state/noctalia/settings.tomland overrideconfig.toml.
- Idle: the idle behaviors are off, so the session never locks, turns the monitors off or suspends on its own. The timeouts are kept in
config.toml(lock after 10 minutes, monitors off after 15, suspend after 5 hours), so turning one back on only needsenabled = truein its[idle.behavior.*]block. When they are on, Noctalia locks before any suspend, including closing the lid, which suspends right away (systemd's default). The lock screen takes your login password. - Login: the SDDM login screen starts the niri session. Your login password unlocks the GNOME keyring, so apps can save passwords.
.zprofilealso unblocks Wi-Fi. - Terminal: Alacritty with CachyOS's config (translucent, Nord colors), kept in the repo at
home/.config/alacritty/alacritty.toml. - Screenshots: built into niri, saved to
~/Pictures/Screenshots. - File pickers: "Open file" dialogs from portal-using apps (Flatpaks, Firefox-based browsers) use the GTK file chooser, because GNOME's portal would need Nautilus.
- Wayland-native apps: Electron and Qt apps run natively on Wayland. Qt apps without the Wayland plugin fall back to X11 through xwayland-satellite.
- Zsh:
- Vi mode.
- Neovim as editor and man pager.
- Tab completion with a menu, case-insensitive.
- Environment and
PATHset in.zshenv, so apps launched from niri see them too. - XDG directories.
- An
extractfunction for archives. - Starship prompt, zoxide (
z), eza (ls), bat (cat), autosuggestions and syntax highlighting. - Every tool is optional: if one is missing,
ls,catand the prompt keep working without errors.
- Neovim:
- Native LSP (
vim.lsp.config, Neovim 0.12+), with servers installed through Mason, plus nvim-cmp and LuaSnip. - Treesitter.
- Telescope with fzf and zoxide.
- Harpoon, fugitive and undotree.
- VimWiki.
- Kanagawa colorscheme.
- Native LSP (
- Doom Emacs: Evil (vim keys), LSP, Magit, Org, spell and grammar checking, and 27 language modules (see Doom modules).
Mod is the Super key. Mod+Shift+H opens a compact cheat sheet with every niri binding in columns (any key closes it). Keys that share modifiers are joined, so Mod+H/← means Mod+H or Mod+←. It reads ~/.config/niri/config.kdl each time, so it always matches your config. niri's own key overlay no longer pops up at login.
| Key | Action |
|---|---|
Mod+Return |
Alacritty (terminal) |
Mod+E |
Emacs (client) |
Mod+W |
Firefox |
Mod+O |
Obsidian (notes) |
Mod+Shift+O |
LibreOffice |
Mod+G |
GIMP |
Mod+N |
Double Commander |
Mod+M |
Thunar (second file manager) |
Mod+P |
KeePassXC |
Mod+C |
VSCodium |
Mod+X |
Claude Desktop |
Mod+R |
Goodvibes (radio) |
Mod+Shift+T |
TuxGuitar |
Mod+Shift+S |
Discord |
Mod+Shift+I |
Audacity |
Mod+Shift+D |
Ardour, in its own X server so its menus work (why) |
Mod+S |
Steam |
Mod+Y |
YGO Omega (from ~/Documents/Games/YGO Omega) |
Thunderbird and Inkscape have no key; open them from the launcher.
| Key | Action |
|---|---|
Mod+D |
Launcher (apps; /calc, /emo for the calculator and emoji) |
Mod+V |
Clipboard history |
Mod+A |
Control center |
Mod+Shift+A |
Noctalia settings |
Mod+Escape |
Lock screen |
| Volume, mic-mute, brightness and media keys | Change the value and show a popup (also on the lock screen) |
| Key | Action |
|---|---|
Mod+Q |
Close window |
Mod+Shift+Q |
Force-kill the window's process (frozen apps) |
Mod+F / Mod+Shift+F |
Maximize column / fullscreen |
Mod+Ctrl+F |
Widen column to fill the free space |
Mod+T |
Toggle floating |
Mod+Tab |
Overview |
Mod+H / Mod+L (or Left / Right) |
Focus column left / right |
Mod+J / Mod+K (or Down / Up) |
Focus window or workspace down / up |
Mod+Home / Mod+End |
Focus first / last column |
Mod+Alt+H / Mod+Alt+L (or Left / Right) |
Move column left / right |
Mod+Alt+J / Mod+Alt+K (or Down / Up) |
Move window down / up, on to the next workspace at the edge |
Mod+Ctrl+Home / Mod+Ctrl+End |
Move column to first / last |
Mod+- / Mod++ |
Column width −/+ 10% |
Mod+Shift+- / Mod+Shift++ |
Window height −/+ 10% |
Mod+Ctrl+H / Mod+Ctrl+L (or Left / Right) |
Move window into the column on the left / right, or out of its column |
Mod+, / Mod+. |
Pull the window on the right into this column / push the bottom window out |
Mod+Space |
Cycle preset column widths |
Mod+Ctrl+Space |
Switch keyboard layout: Spanish ↔ English |
Mod+Shift+C |
Center column |
Mod+Ctrl+Escape |
Get your shortcuts back when a fullscreen app or a VM has grabbed the keyboard |
+ has its own key on the Spanish layout and is Shift+= on English; both are bound, so Mod++ works on either.
| Key | Action |
|---|---|
Mod+1…9, Mod+º (Mod+` on English) |
Go to workspace 1–9, 10 |
Mod+Shift+1…9, Mod+Shift+º (Mod+Shift+` on English) |
Move column to workspace 1–9, 10 |
Mod+Scroll |
Previous / next workspace |
Ctrl+Alt+P |
Screenshot (select area) |
Print / Alt+Print |
Screenshot screen / window |
Mod+Shift+P |
Monitors off |
Mod+Alt+Q |
Quit niri (log out; asks to confirm) |
Leader is Space.
| Key | Action |
|---|---|
<leader>pd |
File explorer (netrw) |
<leader>ff / <leader>fg |
Telescope: find files / git files |
<leader>ps |
Telescope: grep for a string |
<leader>fz |
Telescope: zoxide directories (C-f find files inside) |
<leader>a / C-e |
Harpoon: mark file / toggle menu |
<leader>1…<leader>4 |
Harpoon: jump to file 1–4 |
<leader>gs |
Fugitive git status |
<leader>p / <leader>P / <leader>t |
In fugitive: push / pull --rebase / push -u origin |
<leader>u |
Undotree |
gd |
Go to definition |
gn / gp |
Next / previous diagnostic |
<leader>ca |
Code action |
<leader>rr / <leader>rn |
References / rename |
C-n / C-p / C-y / C-Space / C-e |
Completion: next / previous / confirm / open / close |
C-h C-j C-k C-l |
Move between splits |
C-Arrows |
Resize splits |
< / > (visual) |
Indent and keep selection |
Alacritty's keys with the config in this repo:
| Key | Action |
|---|---|
Ctrl+Shift+C / Ctrl+Shift+V |
Copy / paste |
Ctrl++ / Ctrl+- / Ctrl+0 |
Font bigger / smaller / reset |
Shift+PageUp / Shift+PageDown, Shift+Home / Shift+End |
Scroll back / forward, to the top / bottom |
Ctrl+Shift+F / Ctrl+Shift+B |
Search the scrollback forward / backward |
Ctrl+Shift+N |
New terminal in the same folder |
Ctrl+Shift+Space |
Vi mode (select and copy with the keyboard) |
Edit the files in ~/.config (they're links into ~/dotfiles/home/), then commit them from ~/dotfiles. After changing keys, update the keybinding tables above too.
Bindings live in the binds { } block of ~/.config/niri/config.kdl. niri reloads the file as soon as you save it, so there's nothing to restart. Run niri validate if a change doesn't take effect; a broken file keeps the last working config and shows an error.
Each line is <keys> { <action>; }:
binds {
// Launch an app
Mod+B { spawn "firefox"; }
// Arguments are separate strings
Mod+Ctrl+Return { spawn "alacritty" "-e" "btop"; }
// Shell syntax (pipes, $VARS, ~) needs sh -c
Mod+Ctrl+S { spawn "sh" "-c" "grim -g \"$(slurp)\" - | wl-copy"; }
// Built-in actions
Mod+Shift+C { center-column; }
// Media keys, still working on the lock screen
XF86AudioPlay allow-when-locked=true { spawn "noctalia" "msg" "media" "toggle"; }
// Repeat-limited (good for mouse wheel binds)
Mod+WheelScrollDown cooldown-ms=150 { focus-workspace-down; }
}-
Modifiers:
Modis Super. You can also useSuper,Ctrl,AltandShift, combined with+. -
Key names follow xkb. Run
wev(sudo pacman -S wev) and press a key to see its name, e.g.Return,Print,XF86AudioMute,Comma. -
Spanish keyboard: niri matches the key's symbol on the current layout, and falls back to the English layout when that symbol isn't a plain character. Keys that need AltGr on Spanish, such as
[and], can't be bound reliably; use letters, digits or,.-+instead. -
Changing a key: edit the key on the left. A key can only be bound once; if two lines use the same key,
niri validatereports it. -
Removing a bind: delete the line.
-
All actions:
niri msg action --helplists them, and the niri wiki documents them. -
Using Alt as Mod: add
mod-key "Alt"to theinput { }block. That's useful when running niri nested inside another session. -
Cheat sheet (
Mod+Shift+H): the script~/.local/bin/keybindsreads thebinds { }block and shows it in columns, so new binds appear in it without changes:- a comment after a blank line starts a section, and the text before the first
:,(,.or,is its heading (// Apps,// Media and brightness, …); comments right after a bind are notes and are skipped; - a bind's description is its
hotkey-overlay-title, or else its action (focus-column-left→ "Focus column left"):Mod+B hotkey-overlay-title="Browser" { spawn "firefox"; }
- keys with the same description share a line, keys with the same modifiers are joined (
Mod+H/←), and runs likeMod+1…Mod+9become one (Mod+1–9); - it uses as few columns as fit the window's height, each only as wide as its content, and shortens descriptions only when the window is too narrow.
It opens in a floating Alacritty window (the
keybindswindow rule inconfig.kdl). Runkeybindsin any terminal to see it there. niri's own overlay is no longer bound, andhotkey-overlay { skip-at-startup }inconfig.kdlstops it appearing at login;niri msg action show-hotkey-overlaystill opens it. - a comment after a blank line starts a section, and the text before the first
- Settings:
~/.config/noctalia/config.tomlsets the theme (Oxocarbon), wallpaper, idle timeouts (the idle behaviors are off in it) and bar layout. Its comments say what each part does; every option is documented at docs.noctalia.dev. Check it withnoctalia config validate. - Settings window: changes made in Noctalia's Settings window (
Mod+Shift+A) go to~/.local/state/noctalia/settings.toml, not the repo, and win overconfig.toml. If an edit toconfig.tomlseems ignored, look there. - Bar widgets: the
start,centerandendlists in[bar.default]pick and order them. Bar clicks are set per widget; see the bar actions docs. - Keys: Noctalia's panels use fixed keys (arrows, Enter, Escape), set in the
[keybinds]section. Anything Noctalia can do from a key is anoctalia msgcommand, which you bind in niri;noctalia msg --helplists them:Mod+Shift+N { spawn "noctalia" "msg" "notification-clear-history"; }
Modules are switched on and off in ~/.config/doom/init.el: a line starting with ;; is off. After changing it, run doom sync and restart Emacs. Every module you switch off is less for doom install and doom upgrade to download and compile, so switching off unused languages makes installs much faster.
Language modules that are on (27): cc (C/C++), csharp, dart, elixir, elm, emacs-lisp, go, graphql, haskell, json, java, javascript, julia, kotlin, markdown, nim, ocaml, org, php, python, rust, scala, sh, swift, web, yaml, zig.
Switched off on purpose: clojure, common-lisp, lean, lua, nix, raku, solidity and latex. The grammar checker needs LanguageTool, which brings in Java; switch it off and drop languagetool from packages.txt if you don't use it.
Doom keys: Doom uses Evil (vim keys), and SPC is the leader. Add bindings with map! in ~/.config/doom/config.el, then run SPC h r r (or restart Emacs):
(map! :leader
:desc "Save file" "w" #'save-buffer)
(map! :n "C-h" #'evil-window-left
:n "C-l" #'evil-window-right)SPC h k then a key shows what it's bound to.
- Keys: global maps are in
~/.config/nvim/lua/core/remaps.lua. Plugin maps sit next to each plugin's config in~/.config/nvim/lua/plugins/config/(e.g.telescope.lua,harpoon.lua). LSP maps are in theLspAttachblock oflsp.lua, and completion keys are incmp.lua.-- mode, keys, action, options vim.keymap.set("n", "<leader>w", "<cmd>write<CR>", { desc = "Save file" }) vim.keymap.set({ "n", "v" }, "<leader>y", '"+y', { desc = "Yank to clipboard" }) vim.keymap.set("n", "<leader>fb", require("telescope.builtin").buffers)
- Modes:
nnormal,iinsert,vvisual,tterminal. - The leader is
Space, set at the top ofremaps.lua. Changevim.g.mapleaderto use another key. - Check whether a key is free with
:verbose nmap <key>. - List everything with
:Telescope keymaps. - Restart Neovim after editing.
- Modes:
- Plugins: listed in
~/.config/nvim/lua/plugins/init.lua. Add or remove an entry, then run:Lazy sync. - Treesitter parsers: listed in
~/.config/nvim/lua/plugins/config/ts_parsers.lua: bash, lua, python, javascript, typescript, rust, c, markdown, vim, vimdoc and query. Each one compiles when installed; add a language there and run:TSUpdate. - Language servers:
setup-editors.shinstalls bash, Python, TypeScript, Rust and Lua servers through Mason. Add more with:Mason.
Alacritty reads ~/.config/alacritty/alacritty.toml, which is linked into the repo as home/.config/alacritty/alacritty.toml. It's CachyOS's own config: translucent, Nord colors, and a [keyboard] section with the vi-style and search bindings already in it. Add your keys to that bindings list rather than writing a second [keyboard] (that would be an error):
[keyboard]
bindings = [
# ...the entries already there...
{ key = "T", mods = "Control|Shift", action = "SpawnNewInstance" },
]man 5 alacritty lists every action and option. Alacritty reloads the file as soon as you save it.
The shell uses vi mode (bindkey -v in ~/.zshrc). Add your own bindings after that line:
bindkey '^R' history-incremental-search-backward # Ctrl+R
bindkey -M viins '^E' autosuggest-accept # Ctrl+E accepts the suggestionRun bindkey with no arguments to list the current ones. To find a key's code, run cat, press the key, then Ctrl+C. Open a new terminal or run source ~/.zshrc to apply. Environment variables and PATH go in ~/.zshenv, so apps started from niri see them too.
~/.gitconfig is linked into the repo, so the identity, the GPG signing key and the gh credential helper travel with the dotfiles. Change them there, not in ~/.gitconfig directly (it's the same file):
[user]
signingkey = 2CEF07CF3799668B # your GPG key id
email = you@example.com
name = Your NameGit signs every commit and tag (gpgsign = true). The gh helper handles GitHub logins, so git push asks for the token once and then reuses the keyring. On a new machine, run gh auth login after installing gh.
The lists are in packages.txt (CachyOS and Arch repos), packages-aur.txt (AUR) and packages-pipx.txt (Python tools, installed with pipx). They only hold what a CachyOS install with the niri desktop doesn't already have. To add a package, put its name on its own line in the right list and run install-packages.sh again.
packages.txt can also name a pacman group, like pro-audio: install-packages.sh installs all its members (pacman -Sg pro-audio lists them). A line starting with !, like !audacity, leaves that package out even when a group includes it. verify.sh checks the members the same way.
Already installed by CachyOS (and used by these configs): niri, noctalia (from cachyos-niri-noctalia), xwayland-satellite, xdg-desktop-portal-gnome, xdg-desktop-portal-gtk, wl-clipboard, gnome-keyring, sddm, networkmanager, bluez, bluez-utils, pipewire-pulse, wireplumber, pavucontrol, power-profiles-daemon, xdg-user-dirs, noto-fonts, noto-fonts-emoji, cantarell-fonts, zsh, zsh-autosuggestions, zsh-syntax-highlighting, fzf, git, base-devel, python, ripgrep, unzip, unrar, alacritty and firefox.
Installed from this repo:
| Group | Packages | Used by |
|---|---|---|
| AUR helper | paru (in the CachyOS repo) |
packages-aur.txt, paru -Syu |
| Python tools | python-pipx; pipx: trustsight |
packages-pipx.txt. TrustSight risk-scores AUR updates before you install them (repo) |
| Keyring | libsecret, seahorse |
Saved passwords for Thunderbird, browsers, git; seahorse to manage them |
| Scripts | jq |
Mod+Shift+Q force-kill |
| Fonts | ttf-jetbrains-mono-nerd, ttf-iosevka-nerd, ttf-nerd-fonts-symbols-mono (Doom icons); AUR: ttf-symbola (Emacs's fallback for symbols) |
Noctalia, GTK. CatV, Feather and Grape Nuts aren't packaged, so they're in home/.local/share/fonts/ |
| Qt theming | kvantum, kvantum-qt5, qt5ct, qt6ct, qt5-wayland, qt6-wayland |
Same Rose Pine look and icons for Qt apps (Double Commander, KeePassXC) |
| Theming | nwg-look, sassc, gnome-themes-extra; AUR: sunity-cursors-git, gtk-engine-murrine |
GTK tools and theme build dependencies; cursor theme Sunity-cursors |
| Shell | starship, eza, bat, zoxide, pyenv, yt-dlp |
.zshrc aliases and prompt |
| Archives | 7zip, cabextract, cpio |
The extract function |
| Neovim | neovim (0.12+, needed by nvim-treesitter's main branch), tree-sitter-cli, fd, nodejs, npm, python-pip, luarocks |
lazy.nvim, treesitter parsers, Telescope, telescope-fzf-native, Mason servers |
| Doom Emacs | emacs-wayland, aspell, aspell-en, aspell-es, languagetool, shellcheck |
Doom, spell, grammar, sh modules |
| Development | docker, docker-buildx, docker-compose, geany, vscodium (CachyOS repo), mysql-workbench, mariadb-libs, rustup, uv; AUR: postman-bin, pyenv-virtualenv |
Containers, editor, MySQL/MariaDB client, Rust and Python toolchains, API client |
| Network | wireguard-tools, qbittorrent; AUR: wireguird |
WireGuard VPN (and its GUI), torrents |
| Audio production | groups pro-audio, lv2-plugins, vst-plugins (about 290 packages, ~6 GB); zam-plugins-* in every format; x42-plugins, lsp-plugins, cardinal, distrho-ports, dragonfly-reverb, wolf-shaper, sfizz, geonkick, drumgizmo, helm, stochas, yoshimi, soundfont-fluid; ardour with pipewire-jack, xorg-xwayland and openbox (for ardour-x); AUR: vcvrack-bin, airwindows-lv2, neural-amp-modeler-lv2, sooperlooper, paulxstretch. Vitalium, Vital's open-source build, comes with distrho-ports. audacity is left out (!audacity) for audacity3-git |
DAWs (Ardour, LMMS, Reaper…), synths (Surge XT, Dexed, ZynAddSubFX…), effects (Calf, LSP, x42, ZAM, Guitarix…), patchbay (qpwgraph), plugin host (carla), Windows plugins (yabridge) |
| Media and writing | discord, calibre; AUR: audacity3-git, tuxguitar, trelby |
Audio editing and recording, chat, e-books, guitar tabs, screenwriting |
| Games | steam, 0ad, cataclysm-dda-tiles; AUR: airshipper (Veloren launcher) |
Open them from the launcher (Mod+D); Steam also has Mod+S |
| Apps | thunderbird, libreoffice-fresh, gimp, inkscape, keepassxc, obsidian, doublecmd-qt5, thunar (with gvfs for trash and USB drives, tumbler for thumbnails), loupe (image viewer), vlc with vlc-plugins-all (video player and its codecs), thunar-archive-plugin with file-roller and zip (extract and create archives from Thunar's right-click menu); AUR: goodvibes, claude-desktop |
Mod+ app shortcuts and the launcher |
Not packaged, so setup-desktop.sh (themes) and setup-editors.sh (Doom) download them, or see the manual install:
- GTK theme
Rosepine-Darkand icon themeRose-Pine-Moon, from Fausto-Korpsvart/Rose-Pine-GTK-Theme. - Qt theme
rose-pine-foam, from rose-pine/kvantum. - Doom Emacs, from doomemacs/doomemacs.
The guide has four parts. If CachyOS is already installed with the niri desktop, skip to Part 2.
- Install CachyOS, with the whole system encrypted and the niri desktop.
- Install the dotfiles, with the scripts or step by step.
- Check the install and first login:
verify.sh, monitors and a checklist. - Keeping it up to date.
You can also test everything in a virtual machine first.
- A USB stick of 4 GB or more. It will be erased.
- An internet connection, ideally a cable. Wi-Fi works too. The installer downloads the packages.
- A backup of anything on the target disk. The install erases the whole disk.
- To keep Windows on the same disk (dual boot), stop here: that needs manual partitioning, which this guide doesn't cover.
- Download the desktop ISO from cachyos.org/download.
- Write it to the USB stick:
- On Windows: use Rufus. Select the stick and the ISO, click Start, and choose Write in DD Image mode when asked.
- On Linux: find the stick with
lsblk(for example/dev/sdb), then run:Replacesudo dd if=cachyos-desktop-linux-*.iso of=/dev/sdX bs=4M status=progress oflag=sync/dev/sdXwith the stick, not a partition like/dev/sdb1. Double-check it:ddoverwrites whatever you point it at.
The computer must boot the USB stick in UEFI mode. In Legacy/CSM mode the installer asks where to put the bootloader ("MBR of the drive" or a partition), and with an encrypted disk both GRUB and Limine fail to install there, or install but don't boot without the USB stick.
ThinkPad T480: press Enter at the red ThinkPad logo, then F1:
- Startup → UEFI/Legacy Boot:
UEFI Only. CSM Support then disappears, or set it toNo. - Security → Secure Boot → Secure Boot:
Disabled. If the Secure Boot keys were cleared, choose Restore Factory Keys first, then check it's stillDisabled. Cleared keys don't stop Linux from booting while Secure Boot is off; restoring them keeps the option to turn it on later. - Startup → Boot Order Lock:
Disabled, so the installer can add its boot entry. - Press F10 to save. To boot the stick, press Enter at the logo, then F12, and pick the USB stick.
Other computers: the setup key is usually F2, Del or F10, and the boot menu is F12, F11 or Esc. Turn Secure Boot off, set the boot mode to UEFI only, and pick the entry that starts with UEFI: in the boot menu.
Once the live desktop is up, open a terminal and check:
ls /sys/firmware/efiIf it lists files, you're in UEFI mode. If it says "No such file or directory", go back to the firmware settings.
Connect to the network (Wi-Fi is in the panel), then choose Launch installer in the CachyOS Hello window. Leave every option not listed here at its default.
-
Location: your timezone (for example
Europe/Madrid) and language. -
Keyboard:
Spanish. This also sets the layout for the disk-passphrase prompt at boot. -
Bootloader:
Limine(the default) orsystemd-boot. There's no location question in UEFI mode; if one appears, you're in Legacy mode (see 1.3). -
Partitions:
- Pick the disk; check its size so you pick the right one. Choose Erase disk.
⚠️ This erases the whole disk. - Leave the file system (
btrfs) and swap at their defaults. - Tick Encrypt system and type the disk passphrase. You'll type it at every boot. Use letters, numbers and spaces only: characters like
ñ,ç,-,/,@or"sit in different places on Spanish and English keyboards. A long phrase of words is strong and easy to type.
The installer keeps the small EFI partition unencrypted (the firmware has to read it) and encrypts the rest.
- Pick the disk; check its size so you pick the right one. Choose Erase disk.
-
Desktop:
Niri. It installs niri, the SDDM login screen and the Noctalia shell, which this setup uses. -
Packages: leave the defaults. Firefox is ticked, which is the browser
Mod+Wopens. Add Printing-Support if you have a printer. -
Users: your name, username and password. This password also unlocks the keyring at login and the lock screen.
-
Summary: check the disk, encryption and user, then Install. When it finishes, restart and remove the USB stick.
What CachyOS sets up, so the dotfiles don't have to: the GPU driver (chwd detects it, NVIDIA included), NetworkManager, Bluetooth, PipeWire audio, the firewall, zram swap and the SDDM login screen. It also makes fish your login shell; setup-desktop.sh switches it to zsh.
- Type the disk passphrase and press Enter. Nothing shows while you type; that's normal.
- On the SDDM login screen, check that the session (bottom left) is niri, then log in.
- Open a terminal with
Mod+Return(Alacritty, from CachyOS's default niri config). For Wi-Fi, runnmtui, choose "Activate a connection" and pick your network.
If you forget the disk passphrase, the data can't be recovered. Do these now (verify.sh reminds you if you don't):
- Find the encrypted partition. It's the one marked
crypto_LUKS, for example/dev/sda2on a SATA SSD or/dev/nvme0n1p2on an NVMe one:lsblk -f
- Add a second, backup passphrase. Keep it somewhere safe outside this computer, for example in KeePassXC on another device:
It asks for the current passphrase first, then the new one twice. Either passphrase unlocks the disk at boot.
sudo cryptsetup luksAddKey /dev/sda2
- Back up the encryption header. If that part of the disk gets damaged, this copy can save the data:
Copy
sudo cryptsetup luksHeaderBackup /dev/sda2 --header-backup-file luks-header.img
luks-header.imgoff the computer (to another drive or a USB stick), then delete it here.
Use your partition's name from lsblk -f in both commands.
Older T480 firmware has known Thunderbolt and charging bugs. Lenovo publishes its updates through LVFS:
sudo pacman -S fwupd
fwupdmgr refresh && fwupdmgr update- On a system you've already been using: back up your home folder to another drive.
setup-dotfiles.shalso moves every file it replaces into~/.dotfiles-backup/<date>/, including CachyOS's default niri and Noctalia configs. - Space: keep about 10 GB free on
/. Doom Emacs, LibreOffice and the language servers are large. - Time: the slowest step is Doom Emacs, which downloads and compiles its packages; expect 10–20 minutes for the whole run.
- Log in as your normal user, not root.
install-packages.sh installs the packages, setup-dotfiles.sh links the files into your home folder, setup-desktop.sh sets up the themes and the system bits, setup-editors.sh installs Doom Emacs and the Neovim plugins, and verify.sh checks the result. Run them from Alacritty (Mod+Return in CachyOS's default niri config) or from a text console (Ctrl+Alt+F2). The scripts in detail has the full list of what each one does.
1. Clone the repo:
git clone https://github.com/GerMP21/dotfiles.git ~/dotfiles2. Install the packages:
~/dotfiles/install-packages.shIt asks for your sudo password once, then pacman and paru ask you to confirm. Accept the defaults, including replace prompts such as 7zip replacing p7zip. It:
- updates the system and installs the packages in
packages.txt,paruandpipxincluded. Names that aren't in the repos are skipped with a warning; - installs the AUR packages in
packages-aur.txt. A failed one is retried on its own and then skipped with a warning; - installs the Python tools in
packages-pipx.txtwith pipx, each in its own environment.
3. Look at the files first (optional): everything the next step puts in your home folder is in ~/dotfiles/home/, laid out the same way. Hidden files start with a dot, so use ls -la ~/dotfiles/home. The only things not in the repo are the themes and Doom Emacs, which steps 5 and 6 download.
4. Link the dotfiles:
~/dotfiles/setup-dotfiles.shIt only links and copies; it downloads nothing and doesn't need sudo. It:
- symlinks every config from
~/dotfiles/home/into~. Anything already there, such as CachyOS's niri, Noctalia and Alacritty configs,.zshrcand.gitconfig, is moved to~/.dotfiles-backup/<date>/first; - copies the bundled fonts and refreshes the font cache.
5. Set up the desktop:
~/dotfiles/setup-desktop.shsudo and chsh ask for your password. It:
- downloads and installs the GTK, Qt, icon and cursor themes, then applies them with
gsettings; - creates
~/Pictures/Screenshots,~/Projectsand~/org; - makes Loupe open pictures, VLC videos and File Roller archives, so double-clicking one in Thunar or Double Commander opens it there;
- enables power profiles and the GNOME keyring socket (CachyOS already enabled NetworkManager, Bluetooth and PipeWire, and SDDM unlocks the keyring with your login password);
- makes zsh your login shell instead of CachyOS's default, fish;
- checks the niri and Noctalia configs with
niri validateandnoctalia config validate.
6. Install the editors:
~/dotfiles/setup-editors.shIt installs Doom Emacs, then the Neovim plugins, treesitter parsers and language servers, and builds Telescope's fzf extension. This is the slow step: Doom downloads and compiles its packages. It needs step 4 first, because it uses the linked ~/.config/doom and ~/.config/nvim. If you don't use one of the editors, you can skip this step.
Read the output of every script. Anything in a yellow !! line failed; the message says what to run to retry it. A failed step doesn't stop the later ones. All the scripts are safe to run again: finished steps are skipped or redone harmlessly.
7. Check the result:
~/dotfiles/verify.shIt prints a ✓ or ✗ for each check and changes nothing. See 3.1 for what each line means.
8. Log in to the new setup: reboot, then log in from the SDDM login screen with the niri session:
sudo rebootThe same steps as the scripts, one at a time.
1. Clone the repo:
git clone https://github.com/GerMP21/dotfiles.git ~/dotfiles
cd ~/dotfiles2. Install the packages (paru comes from the CachyOS repo with the rest):
sudo pacman -Syu --needed - < <(grep -v -e '^#' -e '^$' -e '^!' packages.txt)
paru -S --needed - < <(grep -v '^#' packages-aur.txt | grep -v '^$')pacman asks which members of each group to install. Press Enter for all, except in pro-audio, where you leave out audacity because it conflicts with audacity3-git. install-packages.sh does that for you.
If pacman stops with target not found: <name>, that package has left the repos (often for the AUR). Remove it from packages.txt and run the command again; install-packages.sh skips such names automatically.
Then install the Python tools in packages-pipx.txt with pipx (~/.local/bin is already on PATH through .zshenv):
grep -v '^#' packages-pipx.txt | grep -v '^$' | xargs -n1 pipx installThis installs TrustSight. From then on, run trustsight before paru -Syu to review pending AUR updates for risky changes.
3. Link the dotfiles. Each file or folder in ~/dotfiles/home/ gets a symlink at the same path under ~, after you move whatever is already there out of the way. .config/gtk-2.0, gtk-3.0, gtk-4.0, Kvantum and xdg-desktop-portal are linked file by file, because themes and apps add their own files there. For example:
mv ~/.config/niri ~/.config/niri.bak
ln -s ~/dotfiles/home/.config/niri ~/.config/niriCopy the fonts, create the folders the configs expect, enable the two services CachyOS doesn't, and switch to zsh:
mkdir -p ~/.local/share/fonts && cp ~/dotfiles/home/.local/share/fonts/* ~/.local/share/fonts/ && fc-cache -f
xdg-user-dirs-update && mkdir -p ~/Pictures/Screenshots ~/Projects ~/org
sudo systemctl enable --now power-profiles-daemon
systemctl --user enable gnome-keyring-daemon.socket
chsh -s /usr/bin/zsh4. Install the GTK and icon themes. Both come from Fausto-Korpsvart/Rose-Pine-GTK-Theme. It isn't in the AUR; rose-pine-gtk-theme-full there is a different theme.
git clone --depth 1 https://github.com/Fausto-Korpsvart/Rose-Pine-GTK-Theme.git /tmp/rose-pine-gtk
cd /tmp/rose-pine-gtk/themes
./install.sh -c dark -l # builds ~/.themes/Rosepine-Dark; -l also sets it for GTK 4 / libadwaita apps
mkdir -p ~/.local/share/icons
cp -r /tmp/rose-pine-gtk/icons/Rose-Pine-Moon ~/.local/share/icons/
gtk-update-icon-cache -f ~/.local/share/icons/Rose-Pine-Moon
cd ~/dotfilesThe cursor theme Sunity-cursors comes from the AUR package sunity-cursors-git (installed in step 2). To install it by hand instead:
git clone --depth 1 https://github.com/alvatip/Sunity-cursors.git /tmp/sunity
mkdir -p ~/.icons
tar -xzf /tmp/sunity/archives/Sunity-cursors.tar.gz -C ~/.icons/Install the matching Qt theme from rose-pine/kvantum. The configs already select it (rose-pine-foam, with Rose-Pine-Moon icons via qt5ct/qt6ct, and niri sets QT_QPA_PLATFORMTHEME):
git clone --depth 1 https://github.com/rose-pine/kvantum.git /tmp/rose-pine-kvantum
mkdir -p ~/.config/Kvantum
tar -xzf /tmp/rose-pine-kvantum/dist/rose-pine-foam.tar.gz -C ~/.config/Kvantum/To try another accent (rose-pine-iris, rose-pine-moon-rose …), extract it the same way and pick it in kvantummanager.
Then apply everything for GTK 4 / libadwaita apps, which ignore settings.ini on Wayland:
gsettings set org.gnome.desktop.interface gtk-theme 'Rosepine-Dark'
gsettings set org.gnome.desktop.interface icon-theme 'Rose-Pine-Moon'
gsettings set org.gnome.desktop.interface cursor-theme 'Sunity-cursors'
gsettings set org.gnome.desktop.interface cursor-size 24
gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark'5. Install Doom Emacs:
git clone --depth 1 https://github.com/doomemacs/doomemacs ~/.config/emacs
~/.config/emacs/bin/doom install --env
~/.config/emacs/bin/doom sync
~/.config/emacs/bin/doom doctor--env generates Doom's envvar file, so Emacs sees the PATH from .zshenv. Your Doom config is already linked at ~/.config/doom.
6. Wallpaper: the repo includes one, Raphael's The School of Athens (public domain), linked to ~/.local/share/backgrounds/wallpaper.jpg. Noctalia shows it ([wallpaper] in ~/.config/noctalia/config.toml). To use another image, replace that file, or put images in ~/.local/share/backgrounds and pick one in Noctalia's wallpaper panel. fill_mode = "crop" crops the image to fill the screen; "fit" shows all of it with borders.
7. Set up Neovim: run nvim. lazy.nvim installs the plugins, treesitter builds its parsers, and Mason installs the language servers (this takes a minute). Make sure Telescope's fzf extension got compiled, then check everything:
make -C ~/.local/share/nvim/lazy/telescope-fzf-native.nvim:checkhealth
:Mason8. Set up Python (optional): CachyOS already has a current Python. For other versions, pyenv compiles them from source, which takes several minutes:
pyenv install 3.13
pyenv global 3.139. Check and start: run ~/dotfiles/verify.sh, then reboot and log in from SDDM with the niri session. Continue with Part 3.
Log in from SDDM with the niri session: niri starts with the wallpaper and Noctalia's bar. Ctrl+Alt+F2 and up give you a plain text console, which is handy if something goes wrong.
~/dotfiles/verify.shIt checks everything the install scripts do, plus the boot setup, and prints one line per check:
✓passed;✗failed (most ✗ lines say what to run);-skipped, because the check can't run here (for example without sudo).
It ends with a count such as 30 passed, 0 failed, 0 skipped and exits with an error if anything failed. It changes nothing. It asks for your sudo password once, only to read the boot partition and the encryption header; ./verify.sh --no-sudo skips those two checks. Run it inside the niri session: a few checks, like the applied GTK theme, read your desktop settings.
What each section checks, and what to do when a line shows ✗:
| Section | Checks | If it shows ✗ |
|---|---|---|
| Packages | Everything in packages.txt, packages-aur.txt and packages-pipx.txt is installed |
The line lists what's missing; run install-packages.sh again |
| Dotfiles linked | Every path from home/ is linked into ~, no links into the repo are broken, the bundled fonts are copied |
Run setup-dotfiles.sh again. A broken link usually means a file was renamed or removed in the repo |
| Configs | niri validate and noctalia config validate |
The error from the tool is printed under the ✗ line, with the file and line number |
| Login shell and services | zsh is your login shell; sddm, NetworkManager, bluetooth, power-profiles-daemon are enabled, plus pipewire.socket, wireplumber and gnome-keyring-daemon.socket for your user |
For the shell: chsh -s /usr/bin/zsh, then log out and in. For a service: sudo systemctl enable --now <name> (add --user and drop sudo for user services) |
| Themes, fonts and default apps | GTK, icon, Qt and cursor themes are installed; gsettings applies Rosepine-Dark; PNG and JPEG open in Loupe, MP4 and MKV in VLC, ZIP in File Roller; JetBrains Mono and Iosevka Nerd Fonts are present |
Run setup-desktop.sh again for the themes and default apps, or setup-dotfiles.sh for the bundled fonts; for the Nerd Fonts, pacman -Q ttf-jetbrains-mono-nerd ttf-iosevka-nerd shows whether the packages are there |
| Editors and tools | trustsight runs; Doom Emacs and its packages, the Neovim plugins, Telescope's fzf extension and the Mason language servers are installed; once yabridge is set up, yabridgectl status runs and you're in the realtime group |
Run setup-editors.sh again, or the commands in Troubleshooting; for yabridge, setup-yabridge.sh (3.6) |
| Boot and encryption | Booted in UEFI mode; which firmware entry this boot came from; a LUKS-encrypted partition; the bootloader's config in /boot; at least two passphrases on the encrypted partition |
See 3.2 and 1.6 |
verify.sh shows the firmware entry this boot came from, for example Boot0001: Limine. To see all of them:
efibootmgrIn a working install:
BootCurrentis the entry the laptop booted from, and it's the one called Limine (or Linux Boot Manager for systemd-boot), pointing at\EFI\limine\limine_x64.efion your EFI partition;- that entry is first in
BootOrder, so the laptop boots it without the USB stick.
Other entries are normal:
- ThinkPad's built-in entries (Setup, Boot Menu, Diagnostics, USB, NVMe, PCI LAN…) belong to the firmware.
- A Windows Boot Manager entry is left over if the disk had Windows before; the installer erased Windows, but the firmware still lists it. If
lsblkshows no other disk with Windows on it, nothing can boot from it. It's harmless, and you can remove it withsudo efibootmgr -b 0000 -B, using the numberefibootmgrshows for it.
The real test: reboot with the USB stick removed. You should get the passphrase prompt, then the SDDM login screen.
Open a terminal (Mod+Return) and list the screens:
niri msg outputsIf a resolution, refresh rate or scale is wrong, add a block to ~/.config/niri/config.kdl using the name shown (for example eDP-1 or HDMI-A-1):
output "eDP-1" {
mode "1920x1080@60"
scale 1.0
}niri applies it as soon as you save.
SDDM, the login screen, runs before you log in, so its files live outside your home folder and the main scripts leave it alone. setup-login-screen.sh installs a small Tokyo Night theme from system/sddm/tokyo-night/ with the background and profile picture from system/sddm/:
~/dotfiles/setup-login-screen.shIt asks for sudo and writes three things:
/usr/share/sddm/themes/tokyo-night-dotfiles/: the theme and the background;/usr/share/sddm/faces/<you>.face.icon: your profile picture. SDDM can't read your home folder, which CachyOS keeps private, so~/.face.iconwouldn't work;/etc/sddm.conf.d/10-dotfiles-theme.conf: selects the theme, leaving/etc/sddm.confalone.
Preview it without logging out:
sddm-greeter-qt6 --test-mode --theme /usr/share/sddm/themes/tokyo-night-dotfilesThe real login screen changes the next time SDDM starts (log out or reboot).
Other images: pass your own, in any format Qt reads (JPG, PNG…). A square picture works best for the profile picture:
~/dotfiles/setup-login-screen.sh --background ~/Pictures/login.jpg --avatar ~/Pictures/me.pngOr replace system/sddm/tokyo-night/background.jpg and system/sddm/avatar.jpg and run the script again.
Tweaks: system/sddm/tokyo-night/theme.conf sets the font and where the login card sits (cardPosition: 0.5 is centered, 0.68 keeps it over the night sky in the default background). The layout and colors are in Main.qml. Run the script again after editing.
Undo: sudo rm /etc/sddm.conf.d/10-dotfiles-theme.conf, and SDDM goes back to its previous theme.
-
Mod+Returnopens Alacritty with the starship prompt, andMod+Dopens Noctalia's launcher. - The bar shows the launcher, battery, CPU, RAM, disk, workspaces, keyboard layout, network, Bluetooth, volume, power profile and clock, in Oxocarbon colors.
-
Mod+Ctrl+Spaceswitches between Spanish and English, and the bar shows the layout. - The volume, mic-mute, brightness and media keys work and show a popup.
-
notify-send hishows a notification. -
Mod+Escapelocks the screen, and your password unlocks it. -
Ctrl+Alt+Psaves a screenshot to~/Pictures/Screenshots. -
Mod+Vopens the clipboard history, andMod+Athe control center. -
Mod+Wopens Firefox, its file dialogs open, and nothing asks for a keyring password. - GTK apps (Thunderbird) and Qt apps (
Mod+PKeePassXC,Mod+NDouble Commander) use the Rose Pine theme. - In the terminal,
z <dir>jumps to a directory,lsshows eza output, and Tab completes. -
nvimopens. In it::checkhealthshows no errors (warnings about optional tools are fine).Space ffopens Telescope.:LspInfolists a server on a.lua,.pyor.tsfile.
-
Mod+Eopens Emacs. - After a reboot without the USB stick, the passphrase prompt and SDDM appear.
yabridge lets Ardour (and other Linux DAWs) load Windows VST3, VST2 and CLAP plugins.
How it fits together:
- Wine runs Windows programs. It keeps a fake Windows drive, the prefix, in
~/.wine:C:\is the folder~/.wine/drive_c. - Windows plugins are installed into that drive as on Windows. VST3 plugins go to
C:\Program Files\Common Files\VST3, which is~/.wine/drive_c/Program Files/Common Files/VST3. - yabridge connects them to Ardour.
yabridgectl synclooks in the plugin folders and, for each Windows plugin, puts a small Linux stand-in plugin in~/.vst3/yabridge/(~/.vst/yabridge/for VST2,~/.clap/yabridge/for CLAP). - Ardour scans
~/.vst3, finds the stand-ins and loads them like Linux plugins. Each stand-in starts the real plugin in Wine and passes audio, MIDI and its window back and forth.
So adding a plugin is always: install it into Wine → yabridgectl sync → rescan in Ardour.
~/dotfiles/setup-yabridge.shIt asks for sudo, then:
- installs
wine-staging(withwine-monoandwine-gecko, so Wine doesn't ask to download them),winetricksandrealtime-privileges, and adds you to therealtimegroup. If plainwineis installed, pacman asks to replace it: answery; - installs yabridge's newest development build in
~/.local/share/yabridgeand linksyabridgectlinto~/.local/bin. The latest release, 5.1.1, doesn't work with Wine 9.22 or newer (clicks in plugin windows don't register); the fix is only in development builds so far. Arch'syabridgepackage, which comes with thepro-audiogroup, is that release, so the script removes it andpackages.txtleaves it out (!yabridge); - creates the Wine prefix
~/.winewith the folders Windows installers use for plugins (C:\Program Files\Common Files\VST3,…\CLAPandC:\Program Files\Steinberg\VstPlugins), registers them withyabridgectland runsyabridgectl sync.
Then reboot if the script asked you to. Its last line says so when it added you to the realtime group, which lets audio programs run with high priority and lock memory (fewer crackles and dropouts). It takes effect after you log in again, and also fixes Ardour's warning about the locked memory limit.
To check: yabridgectl status shows where yabridge is, the three folders it watches and the plugins it found (none yet). ./verify.sh checks it too.
1. Get the installer from the plugin maker's website. If it's a .zip, extract it (double-click it in Thunar, or right-click → Extract Here). Keep the .exe or .msi wherever you like, for example ~/Music/Plugin installers/.
2. Run the installer with Wine in a terminal (Mod+Return):
wine "$HOME/Music/Plugin installers/PluginSetup.exe"For an .msi installer:
wine msiexec /i "$HOME/Music/Plugin installers/Plugin.msi"Quote paths with spaces. To type a path quickly, write wine and drag the file from Thunar into the terminal. The first time, Wine may show an "updating Wine configuration" window for a few seconds.
In the installer:
- Install location: keep the default (
C:\Program Files\...). Those are the folders yabridge watches. - Formats, if it asks:
- VST3: yes.
- CLAP: optional; yabridge supports it, but Ardour may not load CLAP.
- VST2 ("VST", "64-bit VST"): optional; it works too, but one copy of each plugin is enough.
- AAX: no; that's Pro Tools only.
- Standalone app: optional; it runs with Wine on its own, outside Ardour.
- 64-bit: skip 32-bit versions if offered.
Afterwards the plugin is in ~/.wine/drive_c/Program Files/Common Files/VST3/. In Thunar, Ctrl+H shows hidden folders such as .wine.
A plugin without an installer (just a .vst3 file or folder) only needs copying into that folder. If an installer used another folder (some VST2 plugins go to C:\Program Files\VSTPlugins or a folder named after the maker), add it once:
yabridgectl add "$HOME/.wine/drive_c/Program Files/<that folder>"3. Let yabridge set it up:
yabridgectl syncIt ends with something like Finished setting up 1 plugin (1 new), and yabridgectl status lists the plugin as set up. If it found 0 plugins, the plugin isn't in a watched folder (see step 2).
4. Rescan in Ardour. Open Ardour with Mod+Shift+D, then Window → Plugin Manager and use its rescan button for new plugins. Or restart Ardour, if it scans for new plugins at startup (Edit → Preferences → Plugins). The first scan of a Windows plugin takes a few seconds, because Ardour has to start Wine to read it. While you're in the Plugin Manager, you can hide plugins you never use, so the lists stay short.
An effect (EQ, compressor, reverb…):
- Open the mixer: Window → Mixer → Show, or
Alt+M. - In a track's strip, find the black box above the fader, which lists the track's plugins.
- Right-click it → New Plugin → Plugin Selector….
- Search for the plugin; filtering by type shows only VST3.
- Select it, click Add, then Insert Plugin(s).
Plugins above the fader process the sound before it; plugins below it, after.
An instrument (synth, sampler, drums): add a track (Ctrl+Shift+N, or Track → Add Track, Bus or VCA…), choose MIDI Tracks, pick the plugin in the Instrument list, then Add and Close.
The plugin's window: double-click the plugin in the strip. The first time in a session it can take a few seconds, while Wine starts.
Good to know:
- Licenses: serial numbers and online activation inside the plugin usually work. Plugins that need iLok or similar copy protection usually don't work under Wine at all, so check before buying.
- Presets and the plugin's own files are saved in the Wine drive, usually under
~/.wine/drive_c/users/<you>/Documents/orAppData/. - Loading: each plugin runs in its own Wine process, so opening one takes a little longer than a Linux plugin.
- CPU: the processing costs about the same as on Windows, plus a small bridge overhead. If you hear crackles, raise the buffer size in Window → Audio/MIDI Setup.
- New version of a plugin: run its new installer the same way, then
yabridgectl sync. - Remove a plugin:
wine uninstalleropens Wine's Add/Remove Programs; or delete its files from the plugin folder. Thenyabridgectl sync --pruneremoves its stand-in from~/.vst3/yabridge/. - After a system update that updated Wine (
paru -Syu): runyabridgectl sync; it warns if Wine and yabridge don't match. - Newer yabridge build: run
~/dotfiles/setup-yabridge.shagain.
| What happens | What to do |
|---|---|
yabridgectl sync finds 0 plugins |
The plugin isn't in a watched folder: find it under ~/.wine/drive_c and yabridgectl add that folder |
| Ardour doesn't list the plugin | Check yabridgectl status, then rescan in Window → Plugin Manager, where Ardour also lists the plugins that failed |
| Text in the plugin's window is missing or shows boxes | Install the Microsoft fonts into Wine: winetricks corefonts |
| The plugin crashes, or Ardour hangs while loading it | Quit Ardour and start it from a terminal with ardour-x; yabridge's and Wine's messages appear there |
| It works on Windows but not here | Check yabridge's known issues; many plugins have a listed fix |
- System and AUR packages: check pending AUR updates with TrustSight first, then update everything:
trustsight
paru -Syu
- yabridge (if you set it up): run
~/dotfiles/setup-yabridge.shagain for the newest development build, andyabridgectl syncafter Wine updates. - pipx tools (TrustSight):
pipx upgrade-all
- Dotfiles: pull the latest version and run
setup-dotfiles.shagain, which links any new files. Then check withverify.sh:Runcd ~/dotfiles && git pull && ./setup-dotfiles.sh && ./verify.sh
setup-desktop.shagain to update the themes, andsetup-editors.shafter changes to the Doom or Neovim setup. All of them are safe to repeat. New packages in any of the three lists need./install-packages.sh, which is also safe to re-run. Packages removed from a list stay installed until you remove them withsudo pacman -Rns <name>(orpipx uninstall <name>). - Doom Emacs: after a pull that changed
~/.config/doom/init.elorpackages.el, rundoom sync. To update Doom and its packages:doom upgrade
- Neovim plugins:
:Lazy sync, then:TSUpdateand:MasonUpdate. - Firmware:
fwupdmgr refresh && fwupdmgr updatenow and then (T480).
All of them run as your normal user (they refuse to run as root) and are safe to run again. Run them in this order: install-packages.sh, setup-dotfiles.sh, then setup-desktop.sh and setup-editors.sh (those two in either order).
- Asks for sudo once and keeps it alive while AUR packages build.
sudo pacman -Syu, then installspackages.txtwith--needed. Names not in the repos are listed with a warning and skipped, instead of making pacman refuse the whole list.paru -S --neededforpackages-aur.txt. If that fails, it retries each package on its own and warns about the ones that still fail.pipx installfor each tool inpackages-pipx.txtthat isn't installed yet.
It never removes packages.
Links and copies, nothing else: no downloads, no sudo, no services.
- Links every path from
home/into~. Existing files are moved to~/.dotfiles-backup/<date>/first, and paths already linked are left alone..config/gtk-2.0,gtk-3.0,gtk-4.0,Kvantum,xdg-desktop-portalandalacrittyare linked file by file, because themes and apps add their own files there..gitconfigand.config/mimeapps.listare linked too, so the git identity and the default apps are part of the dotfiles. - Copies the bundled fonts, keeping fonts already there, and refreshes the font cache.
- Stops before changing anything if
gitorsasscis missing (runinstall-packages.shfirst). - Downloads and installs the Rose Pine GTK theme and icons, the Sunity cursors (only if the AUR package isn't installed), and the Rose Pine Kvantum theme. Each failure is a warning; run the script again later.
- Creates
~/Pictures/Screenshots,~/Projectsand~/org, and applies the theme withgsettings. - Makes
org.gnome.Loupe.desktopthe default for everyimage/type Loupe lists,vlc.desktopfor everyvideo/type VLC lists, andorg.gnome.FileRoller.desktopfor the archive types File Roller lists (not.exeand.jar, so those still run), withxdg-mime default. They're saved in~/.config/mimeapps.list, which is linked into the repo, so the defaults travel with the dotfiles; the other defaults there stay as they are. - Enables
power-profiles-daemon(with sudo) and the GNOME keyring socket, and switches your login shell to zsh if/usr/bin/zshis in/etc/shells. - Runs
niri validateandnoctalia config validate.
- Stops before changing anything if
git,emacs,nvimormakeis missing, or if~/.config/doomor~/.config/nvimisn't there yet (runsetup-dotfiles.shfirst). - Installs Doom Emacs, or runs
doom syncif it's already installed. An existing~/.config/emacsthat isn't Doom is left alone. Then runsdoom doctor. - Installs the Neovim plugins with lazy.nvim, builds Telescope's fzf extension, installs the treesitter parsers from
ts_parsers.lua, and the language servers through Mason.
Optional; see 3.4. Installs the theme from system/sddm/tokyo-night/, the background (--background FILE to use another) and the profile picture (--avatar FILE), then selects the theme with a drop-in in /etc/sddm.conf.d/. It warns if /etc/sddm.conf sets its own theme, since that file wins over drop-ins.
Optional; see 3.6. Installs Wine Staging, winetricks and realtime privileges, removes Arch's yabridge/yabridgectl packages if present, downloads yabridge's newest development build from its automated builds (via nightly.link) into ~/.local/share/yabridge (skipped when that build is already installed), creates ~/.wine and its plugin folders, and runs yabridgectl add and sync. Safe to run again.
See 3.1. Options: --no-sudo skips the checks that need sudo; --help shows the usage.
- Packages: installed or upgraded, never removed, except by
setup-yabridge.sh: it removes Arch'syabridgeandyabridgectl(replaced by yabridge's development build) and lets pacman replacewinewithwine-staging. - Groups:
setup-yabridge.shadds you to therealtimegroup. - Services:
power-profiles-daemonis enabled (setup-desktop.sh). - Login shell: set to zsh with
chsh(setup-desktop.sh). - Login screen (optional):
setup-login-screen.shadds the SDDM theme and your picture under/usr/share/sddm/and one file in/etc/sddm.conf.d/. Apart from that and the group change, no script writes in/etc.
Nothing touches the bootloader, the boot image or the PAM login settings, so the scripts can't stop the computer from booting or block the passphrase prompt. If the login theme ever fails to load, SDDM falls back to its built-in theme; deleting the /etc/sddm.conf.d file undoes it.
To try everything without touching your computer, use VirtualBox (free):
- Create a VM: type Linux, version Arch Linux (64-bit), 4 GB of RAM or more, 2–4 CPUs, Enable EFI ticked, and an 80 GB disk. Enable EFI matters: without it the installer runs in Legacy mode and the bootloader fails, as in 1.3.
- Settings → Display: Graphics Controller VMSVGA, Enable 3D Acceleration ticked, Video Memory at the maximum. niri needs 3D acceleration in a VM.
- Follow Part 1 using the CachyOS ISO as the VM's optical drive. Skip 1.2, 1.3 and 1.7. CachyOS's hardware detection normally installs the VirtualBox guest tools; if
systemctl status vboxservicesays the unit doesn't exist, runsudo pacman -S virtualbox-guest-utilsandsudo systemctl enable --now vboxservice. - After the first boot, take a snapshot (Machine → Tools → Snapshots → Take) so you can roll back.
- Follow Part 2 and Part 3.
VirtualBox quirks:
- Its Host key is Right Ctrl: use Left Ctrl for shortcuts, and
Right Ctrl+F2to switch to tty2. - Turn on File → Preferences → Input → Auto Capture Keyboard and click inside the VM, so the Super key reaches niri.
- Windows keeps
Win+Lfor itself.
- Every file
setup-dotfiles.shreplaced is in~/.dotfiles-backup/<date>/. Copy the ones you want back over the links. - Your packages aren't removed. To get CachyOS's default niri and Noctalia setup back, move
~/.config/niriand~/.config/noctaliaback from the backup folder, or copy them from/etc/skel/.config/. - To go back to fish:
chsh -s /usr/bin/fish.
- The bootloader fails to install, or the system only boots with the USB stick in: the installer ran in Legacy/CSM mode. Set the firmware to UEFI only (see 1.3), check with
ls /sys/firmware/efi, and install again. - The disk passphrase isn't accepted at boot: try typing it as if on an English (US) keyboard. If that works, the boot screen isn't using the Spanish layout; check that
/etc/vconsole.confsaysKEYMAP=es, then rebuild the boot image withsudo limine-mkinitcpio(Limine) orsudo mkinitcpio -P(systemd-boot). You can always unlock with the backup passphrase from 1.6. verify.shsays there's only 1 passphrase: add the backup passphrase from 1.6:sudo cryptsetup luksAddKey /dev/sda2(your partition's name is in the ✗ line).efibootmgrlists a Windows Boot Manager you don't have: it's left over from before the install; see 3.2.
- niri doesn't start, or the screen stays black: press
Ctrl+Alt+F2, log in, then runniri validateandjournalctl --user -b -u niri --no-pager | tail -40. - SDDM logs you straight back out: press
Ctrl+Alt+F2, log in, and runniri validate. Check that SDDM's session menu says niri. - niri ignores your config and uses its defaults: a duplicate keybinding or a typo stops niri loading
config.kdl. Runniri validateto see the line. - No bar after logging in: run
noctalia config validateto find errors in~/.config/noctalia/config.toml, then start it by hand withnoctaliato see its log. If a setting from the file seems ignored, it was probably changed in Noctalia's Settings window; check~/.local/state/noctalia/settings.toml. - The lock screen crashed and the screen stays locked (red or blank): niri keeps the session locked on purpose. Press
Ctrl+Alt+F3, log in, and runloginctl terminate-user $USER. That logs you out everywhere (unsaved work in open apps is lost); go back to the login screen withCtrl+Alt+F1orF2and log in again. - Apps keep asking for a keyring password: the login unlock isn't working. Check that
grep pam_gnome_keyring /etc/pam.d/sddmshows theauthandsessionlines. If the keyring was created with a different password, delete~/.local/share/keyrings/login.keyringand log in again. Mod+ºdoes nothing: runwev, press the º key and check the keysym it prints. If it isn'tmasculine, use that name in the two workspace-10 binds.- No network after installing: run
nmtui. If it says NetworkManager isn't running:sudo systemctl enable --now NetworkManager. - No sound: run
systemctl --user status wireplumber. - Other apps go silent while Ardour is open: Ardour is using its ALSA backend, or
jack2, and either one takes the sound card for itself. Installpipewire-jack(it's inpackages.txtand replacesjack2), restart the audio services, then pick JACK in Ardour's Audio/MIDI Setup (Window → Audio/MIDI Setup). Ardour then goes through PipeWire like every other app:sudo pacman -S pipewire-jack systemctl --user restart pipewire pipewire-pulse wireplumber
Ardour is an X11 app, and niri runs X11 apps through xwayland-satellite. With it, Ardour's dropdown menus (track type, instrument, record mode…) open where Ardour doesn't expect them: you have to hold the button down, and the item picked is several rows away from the pointer. So Mod+Shift+D runs ~/.local/bin/ardour-x instead, which starts Ardour in its own X server: an Xwayland window that niri opens maximized (a window rule in config.kdl), with Openbox inside. The X screen inside takes the window's size, so Ardour gets exactly the space between niri's bar and the screen edges. There the menus work.
- Windows: Ardour's main window fills the X server window. Plugin windows, the detached mixer and dialogs open inside it with a title bar: drag it to move a window (or Alt+drag anywhere on the window), drag an edge or Alt+right-drag to resize, double-click it to maximize.
Alt+Tabswitches between Ardour's windows. Openbox's settings are in~/.config/ardour-x/rc.xml. - Leaving it: quit Ardour (
Ctrl+Q) and the X server closes too. While Ardour is open, niri's keys still work, so you can switch workspaces as usual. - Limits: you can't drag files from Thunar into Ardour, because they're in different display servers; use Session → Import instead. Copying and pasting text between Ardour and other apps may not work either. Audio is unaffected: Ardour still goes through PipeWire.
- Ardour from the launcher (
Mod+D) starts it the normal way, with the broken menus. UseMod+Shift+D, or runardour-xin a terminal; it takes the same options as Ardour, for example a session folder. - To try without it (for example after an xwayland-satellite update that might fix the menus), run
ardour9in a terminal. If the menus work, change theMod+Shift+Dline inconfig.kdlback to start Ardour directly.
- Thunar has no "Extract Here" in the right-click menu: Thunar loads plugins when it starts, so quit every Thunar window (or run
thunar -q) and open it again. If it's still missing, checkpacman -Q thunar-archive-plugin file-roller. In File Roller, a format that won't open usually needs its tool from the optional list inpacman -Qi file-roller. - GTK theme isn't applied: check that
ls ~/.themeslistsRosepine-Dark, then run thegsettingscommands from step 4 of the manual install again, or pick the theme innwg-look. - Qt apps look unthemed: check
echo $QT_QPA_PLATFORMTHEMEshowsqt5ct:qt6ctinside niri, and thatls ~/.config/Kvantumlistsrose-pine-foam. Openqt6ct(orqt5ctfor Double Commander) and check that Style iskvantum. - Cursor is the default one: check that
ls ~/.icons /usr/share/icons | grep Sunityfinds the theme, then log out and back in. - Boxes instead of icons in the prompt: the terminal's font has no Nerd Font icons.
fc-match monospaceshould printJetBrainsMono Nerd Font(from~/.config/fontconfig/fonts.conf); terminals set tomonospace, like the Alacritty config in this repo, then show them. Apps with their own font setting need it set there. For VSCodium's built-in terminal, add this to its settings (Ctrl+Shift+P→ "Preferences: Open User Settings (JSON)"):The prompt's icons are Nerd Fonts 3 codes; icons from Nerd Fonts 2 configs (codes"terminal.integrated.fontFamily": "JetBrainsMono Nerd Font"
U+F500–U+FD46) show as boxes with Nerd Fonts 3. - A font is reported missing:
pacman -Q ttf-jetbrains-mono-nerd ttf-iosevka-nerdshows whether the packages are installed, andfc-list : family | grep -i "nerd font"whether fontconfig sees them. Runfc-cache -fif it doesn't.
- Telescope says fzf isn't built: run
make -C ~/.local/share/nvim/lazy/telescope-fzf-native.nvim, then restart nvim. - Neovim says nvim-treesitter needs a newer version: the
mainbranch needs Neovim 0.12+. Check withnvim --version. - Treesitter errors in Neovim: check that
tree-sitter --versionworks, then run:TSUpdate. - Doom Emacs complains about missing packages after a pull: run
doom sync, then restart Emacs.doom doctorlists anything else it needs. doom doctorsaysCannot open load file … straight, ordoom syncfails withunknown revisionorambiguous argument 'HEAD': some of Doom's package downloads are broken. Follow Debugging Doom Emacs packages.doom doctorwarns that Symbola is missing: install the AUR package withparu -S ttf-symbola(it's inpackages-aur.txt), then restart Emacs.
Doom downloads each package as a git repository into ~/.config/emacs/.local/straight/repos/ and builds it into ~/.config/emacs/.local/straight/build-*/. If doom install or doom sync is interrupted (a network drop, closing the terminal, a reboot), it can leave a repository folder whose download never finished. Doom then thinks the package is there and fails when it tries to use it.
Symptoms:
doom doctorreportsCannot open load file…straight.doom syncordoom upgradestops withThe package manager threw an error, and the log showsgit rev-parse HEADfailing in a package's folder:$ cd ~/.config/emacs/.local/straight/repos/auto-minor-mode/ $ git rev-parse HEAD fatal: ambiguous argument 'HEAD': unknown revision or path not in the working tree.doom syncsaysNo packages need attentionbut Emacs still can't load a package.
These folders are only downloaded copies. Deleting them loses nothing of yours; your config is in ~/.config/doom, which none of this touches.
1. List the broken downloads. This changes nothing; it prints each package folder without a finished download:
cd ~/.config/emacs/.local/straight/repos
for d in */; do git -C "$d" rev-parse -q --verify HEAD >/dev/null 2>&1 || echo "${d%/}"; done2. Delete them, together with their half-built copies:
cd ~/.config/emacs/.local/straight/repos
for d in */; do
d="${d%/}"
if ! git -C "$d" rev-parse -q --verify HEAD >/dev/null 2>&1; then
rm -rf "$d" ../build*/"$d"
echo "removed $d"
fi
done3. Download them again and check:
doom sync
doom doctorUse doom sync once Doom is installed. doom install is only for the first setup; running it again just repeats the same sync.
If that doesn't fix it, for example when step 1 lists dozens of packages or doom sync keeps failing on another one, delete all downloaded packages and fetch everything fresh. It takes longer, since every package is downloaded and compiled again, but it leaves nothing half-done:
rm -rf ~/.config/emacs/.local/straight
doom syncWhere to look for more:
doom syncprints the last lines of straight's error log, which name the package and the git command that failed.- The full logs are in
~/.config/emacs/.local/state/logs/; the newest file is the last run. - Run
doom syncagain once the network is stable: a download that failed because of the network usually works the second time.