Arch hands you two package managers and expects you to know both. Pacman runs the official repos, yay reaches the Arch User Repository, and this sheet collects the commands that cover a package’s whole life: install, update, query, downgrade, clean up, and fix. Every one of them was run on a live Arch install (Pacman 7.1.0, yay 13.1.0, kernel 7.2.11) in November 2026, so the output you see is what the terminal actually printed, not what a model imagined.
Keep it open in a second terminal. If you’re setting the system up from scratch, start with the archinstall walkthrough and the post-install steps, then come back here for the package management you do daily. We ran everything against one test machine, so the flags, versions and error messages here match what you’ll see on your own box.
The Single-Letter Operations
Pacman groups its work under single-letter operations, and once these click the flags stop feeling random. Every pacman command you’ll ever type is one operation plus modifiers:
| Operation | Meaning |
|---|---|
-S | Sync: install or upgrade from the remote repositories |
-R | Remove installed packages |
-Q | Query the local database (what is installed) |
-F | Query the files database (which package ships a file) |
-U | Upgrade or install from a local or remote package file |
-D | Database operations such as changing the install reason |
Lowercase letters modify an operation. The most common are -y (refresh databases), -u (upgrade), -s (recursive or search), and -i (info). That’s why a full upgrade is -Syu: sync, refresh, upgrade. Read any pacman command by splitting it into these letters and the flags stop being memorization.
Here are several of those operations running on the live Arch system we used to test this guide. Each block is one real run, unedited.

The rest of this sheet walks through those operations one at a time, from daily updates to cache cleanup and the yay layer on top.
Upgrade Arch the Right Way
Arch is a rolling release, so there’s no version to upgrade to, only forward motion you start by hand. A full system upgrade is the single most important maintenance task on this distro, and there’s exactly one correct command for it. We run it daily, and so should you:
sudo pacman -Syu
That refreshes the package databases and upgrades everything in one transaction, so the system is never left half-synced. When everything is already current, pacman says so and finishes in seconds:
:: Synchronizing package databases...
core downloading...
extra downloading...
:: Starting full system upgrade...
there is nothing to do
If a mirror switch or a stale sync left your databases out of step, force a full re-download with a doubled -yy. It costs a few extra seconds of downloading and guarantees pacman compares against fresh metadata:
sudo pacman -Syyu
Run it and walk away. We ran the doubled form on the test machine, and it refreshed the databases, ran its hooks and exited cleanly; the capture further down shows the plain form pulling a pending htop build when one exists. That’s all a daily update should do, which is why this one command covers the whole routine and you don’t need update managers or timers for the core job.
Why “sudo pacman -Sy” alone breaks Arch
This is the mistake that wrecks more Arch installs than any other. pacman -Sy refreshes the database without upgrading installed packages. Arch keeps no old library versions, so when a shared library gets an ABI bump, every package that links against it is rebuilt and pushed together. Run -Sy and then pacman -S somepackage, and you pull in a package built against the new library while your system still has the old one. The result is a partial upgrade that breaks at runtime.
The rule is simple: never run -Sy on its own. Always upgrade with -Syu, and fold new installs into the same transaction so the library set stays consistent:
sudo pacman -Syu --needed package-name
One command, one consistent system. If an install can wait an hour, let it wait, because folding it into the next -Syu costs you nothing and keeps the shared libraries matched to the packages that link them.
Check for updates without touching the system
To see what’s pending without touching the real sync databases, and without root, use checkupdates from the pacman-contrib package. It copies the databases to a temp directory, syncs the copy, and answers “what would update?” safely:
checkupdates
Each pending package prints with its current and new version. That version pair is also what you feed a downgrade when an update misbehaves.
htop 3.4.1-1 -> 3.5.3-1
The same check on the test machine, captured while htop was pending. One line, one pending package, nothing else.

The related pacman -Qu lists the same thing, but it reads the database from your last sync, so it can under-report if you have not synced recently. For an accurate check, checkupdates wins because it works against a temporary copy of the databases.
Keep the three update checks straight, because they answer slightly different questions:
- checkupdates syncs a temp copy, needs no root
- pacman -Qu reads your last sync, can under-report
- yay -Qua covers AUR packages only
We run checkupdates in one terminal before deciding when to do the real -Syu, because it tells us the size of the incoming upgrade without locking the database.
Install Packages
Installing from the official repositories takes one operation and one package name. We’ll use htop for most of the examples on this page because it’s small, useful, and safe to install anywhere:
sudo pacman -S htop
Pacman resolves dependencies, pulls the package, and runs the post-transaction hooks, all inside one transaction. This is the full output you should expect from a clean install:
resolving dependencies...
looking for conflicting packages...
Packages (1) htop-3.5.3-1
Total Installed Size: 0.41 MiB
:: Proceed with installation? [Y/n] y
checking keyring...
checking package integrity...
loading package files...
checking for file conflicts...
checking available disk space...
:: Processing package changes...
installing htop...
Optional dependencies for htop
lm_sensors: show cpu temperatures
lsof: show files opened by a process
strace: attach to a running process
:: Running post-transaction hooks...
(1/1) Arming ConditionNeedsUpdate...
The whole transaction took a few seconds, hooks included. The prompt is the only stop, so on a fast mirror the install feels instant.

Several common install variations live in one place here. Each line is its own command:
# Install several packages at once
sudo pacman -S vim git curl wget
# Install only if not already current (no needless reinstall)
sudo pacman -S --needed vim
# Disambiguate when a name exists in more than one repo
sudo pacman -S extra/nginx
# Download to the cache without installing
sudo pacman -Sw ripgrep
# Reinstall a package to repair a corrupted install
sudo pacman -S htop
To install a package file you built or downloaded yourself, use -U. Arch packages have used zstd compression since 2020, so they end in .pkg.tar.zst:
sudo pacman -U ./mypackage-1.0-1-x86_64.pkg.tar.zst
The same operation accepts a URL, which is how you install a specific build straight from a mirror or archive. It also lets you pin an exact build, so a newer release can’t surprise you.
sudo pacman -U https://archive.archlinux.org/packages/h/htop/htop-3.4.1-1-x86_64.pkg.tar.zst
One install flag is worth knowing before you need it. When two packages ship the same file, pacman refuses with a file-conflict error. To prove the point, two demo packages were built in the lab, demo-a and demo-b, both shipping /usr/lib/demo-file, and the conflict was resolved with a narrow --overwrite glob rather than the dangerous --overwrite '*':
sudo pacman -U --overwrite '/usr/lib/demo-file' ./demo-b-1.0-1-any.pkg.tar.zst
Keep the glob as narrow as the conflict. A blanket overwrite hides real packaging bugs, while a single named file fixes yours without side effects. The two demo packages were built in the lab precisely to rehearse this failure, and the conflict message named the owner before any damage was done, which is exactly the behavior you want to lean on.
Install Package Groups
A group is a named bundle of packages, like xfce4 or plasma, that installs as one unit. Before you commit disk space to a whole desktop, list what’s available:
pacman -Sg
Show what a group contains before you commit to it. A group’s contents change between releases, so check even for a name you know.
pacman -Sg xfce4
The members print one per line. Fourteen for xfce4, and the count shifts between releases.
xfce4 exo
xfce4 garcon
xfce4 thunar
xfce4 thunar-volman
xfce4 tumbler
xfce4 xfce4-appfinder
xfce4 xfce4-panel
xfce4 xfce4-power-manager
xfce4 xfce4-session
xfce4 xfce4-settings
xfce4 xfce4-terminal
xfce4 xfconf
xfce4 xfdesktop
xfce4 xfwm4
Fourteen members, one per line, straight off the test machine. Checking the count before you install is cheaper than discovering mid-transaction that a “small” group drags in a desktop:

Install the whole group with a normal -S, deselecting members by number at the prompt if you want a subset. The prompt lists every member first, so you see the cost before you confirm.
sudo pacman -S xfce4
One thing trips people up: base-devel used to be a group and is now a regular meta-package, so install it with plain -S base-devel, not as a group. To see which members of a group you already have installed, query the local database with pacman -Qg xfce4. Groups are also how Arch stages big changes, so when a group’s member list changes between syncs, the next install prompt shows the newcomers and expects you to tick them deliberately.
Remove Packages and Clean Orphans
Removal has three levels of thoroughness, and picking the right one saves you from orphaned dependencies later. The everyday forms are these:
# Remove just the package, keep its deps and config
sudo pacman -R htop
# Remove the package plus unused dependencies
sudo pacman -Rs htop
# Remove package, unused deps, and skip config backups (.pacsave)
sudo pacman -Rns htop
The -Rns form is the clean uninstall most people want, and it’s what we use by default. Two heavier hammers exist for special cases, and both deserve a second look before you press y:
# Cascade: remove the package and all its dependents (review the list!)
sudo pacman -Rsc package-name
# Skip dependency checks entirely (dangerous, can break the system)
sudo pacman -Rdd package-name
Over time, packages that were pulled in as dependencies stick around after nothing needs them. We call these orphans, and they’re the main reason a years-old Arch install grows bloated. Find and remove them in one line:
sudo pacman -Rns $(pacman -Qtdq)
The screenshot shows the orphan check and the removal command together. After the sweep the check printed nothing, which is the state you want.

If there are no orphans, pacman -Qtdq hands pacman an empty target list and it answers “error: no targets specified” while changing nothing, so the message is safe to ignore. Removing one batch can create more, because their own dependencies become unneeded, so it’s worth running the pair again until it reports nothing left.
Search Repositories and Show Package Info
Search the remote repositories by name or description. The search matches substrings in both, so short terms return plenty.
pacman -Ss nginx
Results show the repository, name, version, and description.
extra/certbot-nginx 5.9.0-1
Nginx plugin for Certbot
extra/kubectl-ingress-nginx 1.12.0-2 (kubectl-plugins)
kubectl plugin for managing NGINX Ingress Controller for Kubernetes
extra/nginx 1.30.6-2 [installed]
Lightweight HTTP server and IMAP/POP3 proxy server
extra/nginx-mainline 1.31.8-1
Lightweight HTTP server and IMAP/POP3 proxy server, mainline release
Inspect a package in the repos before installing with -Si. Add a second i (-Sii) to also list what requires it:
pacman -Si nginx
You get the repository, version, dependencies, optional deps, and sizes. Download size against installed size tells you whether a package is cheap to try.
Repository : extra
Name : nginx
Version : 1.30.6-2
Description : Lightweight HTTP server and IMAP/POP3 proxy server
Architecture : x86_64
URL : https://nginx.org
Licenses : BSD-2-Clause
Groups : None
Provides : None
Depends On : glibc pcre2 zlib openssl mailcap libxcrypt
Optional Deps : nginx-mod-geoip: GeoIP support
nginx-mod-image-filter: transform images
nginx-mod-mail: proxy IMAP, POP and SMTP protocols
nginx-mod-perl: perl variables and location handlers
nginx-mod-stream: proxy TCP/UDP data streams
nginx-mod-xslt: transform XML responses
Conflicts With : None
Replaces : None
Download Size : 658.55 KiB
Installed Size : 1723.35 KiB
Packager : Antonio Rojas <[email protected]>
Build Date : Sat Oct 17 17:39:01 2026
Validated By : SHA-256 Sum Signature
For packages already on your system, swap -S for -Q. Search installed packages with pacman -Qs htop, and show full details, install date and install reason included, with -Qi:
pacman -Qi htop
The install reason at the bottom is what orphan cleanup keys off. Read it before any -Rns run, because it tells you which packages will survive the sweep.
Name : htop
Version : 3.5.3-1
Description : Interactive process viewer
Architecture : x86_64
URL : https://htop.dev/
Licenses : GPL
Groups : None
Provides : None
Depends On : libcap libcap.so=2-64 libnl ncurses libncursesw.so=6-64
Optional Deps : lm_sensors: show cpu temperatures [installed]
lsof: show files opened by a process
strace: attach to a running process
Required By : None
Optional For : None
Conflicts With : None
Replaces : None
Installed Size : 421.16 KiB
Packager : Christian Hesse <[email protected]>
Build Date : Sun Aug 16 16:15:40 2026
Install Date : Tue Nov 10 06:03:09 2026
Install Reason : Explicitly installed
Install Script : No
Validated By : Signature
To list every package in a repository, use pacman -Sl extra. Drop the repo name to list packages across all of them. The flags layer cleanly too, so piping an -Ss search through grep cuts the noise when a name matches in several repos. Between -Ss to find a package, -Si to judge it and a plain -Sl to enumerate a repo, you can audit what’s available without ever opening a browser.
Find Which Package Owns a File
List every file a package installed. The list runs long for anything real, so pipe it through less or grep when you’re hunting one path.
pacman -Ql htop
Go the other way and find which package owns a file on disk. This is the reverse lookup, and it works on any file a package installed.
pacman -Qo /usr/bin/htop
Pacman names the owning package and version. A foreign package shows as foreign, which is your cue that pacman alone can’t update it.
/usr/bin/htop is owned by htop 3.5.3-1
Those two only work for installed packages. To search files in packages you have not installed, use the files database. Sync it once (and after big updates), then query it:
sudo pacman -Fy
pacman -Fx "bin/nginx$"
The -Fx form takes a regex, which keeps the result tight to the file you actually mean. Plain names work too, so start loose and tighten the pattern when the list runs long.
usr/bin/nginx is owned by extra/nginx 1.30.6-2
usr/bin/nginx is owned by extra/nginx-mainline 1.31.8-1
This is the command to remember when something runs command not found and you need to know which package provides it. We reach for it constantly when following install instructions that assume a binary is already present. The three lookups sound alike, so it pays to keep their jobs straight:
- pacman -Ql lists files of an installed package
- pacman -Qo names the owner of one file on disk
- pacman -Fx searches packages you have not installed
The first two read the local database, so they cost nothing. The third downloads the files database once and then answers offline, which is why we sync it on a schedule rather than on demand.
List and Filter Installed Packages
The -Q operation has a set of filter flags that answer almost any “what is installed?” question. Each line below is a standalone command:
# Everything installed
pacman -Q
# Only packages you installed on purpose (not pulled as deps)
pacman -Qe
# Foreign packages: from the AUR or installed by hand
pacman -Qm
# Native packages: present in the official repos
pacman -Qn
# Explicit AND not required by anything: your real "top level" list
pacman -Qet
# Orphans: dependencies nothing needs anymore
pacman -Qtdq
# Count installed packages
pacman -Qq | wc -l
The foreign list is the one AUR users want most often. On a fresh install with only yay added, it is short:
yay 13.1.0-1
yay-debug 13.1.0-1
A short foreign list is a healthy sign, because everything on it is software you chose and nothing else provides. When that list starts filling with debug packages and build leftovers, it’s a prompt to run the cleanup commands later in this sheet. We review ours after every heavy AUR session, which keeps the count honest and the system predictable.
The -Qe list, the foreign list and the package count from the test machine.

To see what is eating your disk, the expac tool sorts installed packages by size far more cleanly than parsing -Qi. It is not installed by default and is not part of pacman-contrib either, so install expac first if the command comes back empty. List the biggest packages:
expac -H M "%m\t%n" $(pacman -Qq) | sort -rh | head
The result is an instant view of where your disk space goes, and it usually names a compiler or a language runtime you forgot you installed:
220.89 MiB gcc
164.88 MiB llvm-libs
161.64 MiB linux
73.88 MiB python
72.30 MiB perl
54.49 MiB guile
The screenshot below shows both queries side by side, the -Qi detail view and the expac size table.

Add a package name to expac to limit the list, and point it at a directory with du when the space is not in a package at all. Between -Qi for one package and this sort for the whole system, you never have to guess where the space went. The sort also settles the argument about what to drop first, because the numbers come from pacman’s own database rather than a rough guess over directories that several packages share.
Change a Package’s Install Reason
Every package is marked as either explicitly installed or installed as a dependency, and that mark is what makes orphan cleanup work. A dependency that nothing requires becomes an orphan, while an explicit package never does. Sometimes the mark is wrong: a library you installed directly, for example, that you now want auto-removed once nothing uses it. Fix the mark with -D:
# Re-mark as a dependency (eligible for orphan cleanup)
sudo pacman -D --asdeps package-name
# Re-mark as explicitly installed (protected from orphan cleanup)
sudo pacman -D --asexplicit package-name
A common case: you built something from the AUR that pulled in a library as a make-time dependency, then later decided that library earns a permanent place. Promote it to explicit, and the next orphan sweep leaves it alone. We run pacman -D --asdeps most often in the other direction, demoting tools we installed by hand that should now clean themselves up.
Check Integrity and Dependencies
If a package misbehaves, verify its files are intact. A single -Qk checks that every file exists; doubling it to -Qkk also checks file sizes, permissions, and modification times:
pacman -Qkk htop
A clean package reports no altered files. Anything it does list was changed by you, a script or a bad shutdown, and pacman is pointing right at it.
htop: 16 total files, 0 altered files
Before removing something, it pays to know what depends on it. The pactree tool (from pacman-contrib) draws the dependency tree, and the reverse tree answers “what breaks if this goes away?”:
pactree -r ncurses
The output walks up the chain of packages that need it. Read it top down and you see exactly which packages would break, in order.
ncurses
├─bash
│ ├─at-spi2-core
│ │ ├─gtk3
│ │ │ ├─gtk-layer-shell
│ │ │ │ ├─xfce4-panel
│ │ │ │ ├─xfce4-session
│ │ │ │ ├─xfce4-terminal
│ │ │ │ └─xfdesktop
│ │ │ ├─libdbusmenu-gtk3
│ │ │ │ └─xfce4-panel
│ │ │ ├─libwnck3
That tree explains why pacman refuses to remove a core library: half the system sits above it. Remove bash and pacman would find nothing left to run, so the refusal is protecting you from an unbootable system rather than being difficult. When you genuinely need to bypass the check, -Rdd exists, but we have never needed it outside a deliberate provider swap.
Downgrade a Package
When a new version breaks something, you roll back. The fastest path is the local cache, because pacman keeps every version it downloaded until you clean it. Point -U at the older file:
sudo pacman -U /var/cache/pacman/pkg/htop-3.4.1-1-x86_64.pkg.tar.zst
If the version you want is no longer cached, the Arch Linux Archive keeps every package ever published. The URL path uses the package’s first letter. Installing it is a normal -U from the archive:
sudo pacman -U https://archive.archlinux.org/packages/h/htop/htop-3.4.1-1-x86_64.pkg.tar.zst
Pacman treats the older file as an upgrade target and warns you it is going backwards. The warning is informational, because the transaction itself is complete and safe.
loading packages...
warning: downgrading package htop (3.5.3-1 => 3.4.1-1)
loading package files...
:: Processing package changes...
downgrading htop...
The full downgrade output from the test machine. It reads like an upgrade in reverse, because that is exactly what it is.

A quick pacman -Q htop after the transaction confirms the rollback took. For an interactive picker, the downgrade tool from the AUR lists every cached and archived version and lets you choose one. It installs through yay, which gets its own section below, so if yay is not on the box yet come back to this step after reading it. Install it with yay, then run it against any package:
yay -S downgrade
sudo downgrade htop
So the three downgrade routes, in the order we try them:
- the local cache first, fastest and offline
- the Arch Linux Archive when the cache is empty
- the downgrade tool when you’re unsure which version
After downgrading, the next -Syu pulls the package forward again, which defeats the point. To make a downgrade stick, hold it as shown in the next section, and unhold it the moment a fixed release lands. A held package you forget about is how systems drift out of date.
Hold Packages Back from Upgrades
To skip a package for a single upgrade, pass --ignore (comma-separated for several):
sudo pacman -Syu --ignore linux,linux-headers
To hold something permanently, set it in the config file. Open it:
sudo vim /etc/pacman.conf
Add an IgnorePkg line in the [options] section. Globs work, so this pins the whole kernel set:
IgnorePkg = linux linux-headers
IgnoreGroup = nvidia
The two ways to hold a package cover different time scales:
- –ignore skips one upgrade, nothing persisted
- IgnorePkg in pacman.conf holds until you remove it
Pick the narrowest one that works, because a forgotten hold is a stale system waiting to happen.
Hold packages sparingly. A frozen package while everything else moves forward is, by definition, a partial upgrade, and if it shares a library dependency with packages that do upgrade, it can break. Pacman prints ignoring package upgrade on every run as a standing reminder, and we treat that line as a todo: unhold the package as soon as a fixed release lands. That is also why a hold belongs in the config with a comment naming the reason, so the next reader knows when to lift it.
Manage the Package Cache
Pacman stores every package it downloads in /var/cache/pacman/pkg/, and on a rolling system that directory grows to several gigabytes over months. This cache is also your fastest downgrade path, so trim it rather than wiping it. First, see what you’re holding:
sudo du -sh /var/cache/pacman/pkg/
Pacman’s built-in cleaners are blunt, so know what each one costs before you run it. The single -Sc removes cached versions of packages you no longer have installed, which is usually safe. The double -Scc wipes the cache entirely, which means no offline reinstall and no downgrade-from-cache afterward:
# Remove cached packages you no longer have installed
sudo pacman -Sc
# Remove everything in the cache (aggressive)
sudo pacman -Scc
For real control, use paccache from pacman-contrib, which keeps the most recent versions and trims the rest. Always preview with a dry run first so you know what will go:
# Show what would be removed, change nothing
paccache -d
# Keep the 3 most recent versions of each package
sudo paccache -r
# Keep only 1 version
sudo paccache -rk1
# Remove all cached versions of uninstalled packages
sudo paccache -ruk0
The four paccache runs, and when each earns its place. The first two suit most machines, so start there and reach for the rest only under disk pressure.
- paccache -d previews, changes nothing
- paccache -r keeps three versions, safe default
- paccache -rk1 keeps one, frees the most
- paccache -ruk0 clears leftovers of removed packages
Both runs, back to back, on the test machine.

On the test machine those two runs cut the cache from 671 MB to 456 MB without touching a single installed package. To never think about it again, enable the timer that runs paccache -r weekly:
sudo systemctl enable --now paccache.timer
With the timer on, paccache keeps the last three versions of each package, its documented default, and older builds fall off the disk on their own schedule. A few prior versions is exactly what a downgrade-from-cache needs, which is why we recommend the timer over the blunt -Scc wipe. Run the dry run whenever you’re unsure, because the preview is the only place pacman tells you what it’s about to delete.
Fix Keyring and PGP Signature Errors
Packages are signed, and an outdated keyring is the most common reason an upgrade suddenly fails with an error like invalid or corrupted package (PGP signature) or signature is unknown trust. It bites hardest on machines that have been powered off for a while. Work through the fixes in this order, mildest first:
sudo pacman -S archlinux-keyring
sudo pacman -Syu
When even that cannot start because the keyring itself is too broken, reset it from scratch. This re-initialises the keyring and reloads the official Arch master keys:
sudo rm -r /etc/pacman.d/gnupg
sudo pacman-key --init
sudo pacman-key --populate archlinux
After repopulating, pull the current keyring package and run the upgrade again: sudo pacman -S archlinux-keyring && sudo pacman -Syu. The master keys you just loaded can still predate the latest signing keys on a machine that sat idle, so don’t stop here.
One non-obvious cause trips people every year: a wrong system clock makes valid signatures look invalid, because signature validity is time-based. If the keyring is current and signatures still fail, check that timedatectl shows the correct date before anything else. We have seen a laptop with a dead CMOS battery fail every upgrade until the clock was fixed, and no amount of keyring resets could have saved it. Work the fixes in order and the errors clear without touching anything else, because the keyring package refreshes the trust store while a correct clock keeps the validity checks honest.
Update and Rank Mirrors with reflector
Slow updates usually mean a slow mirror, not a slow connection. The mirror list lives in /etc/pacman.d/mirrorlist, and reflector measures the candidates and ranks the fastest ones for you. Install it first:
sudo pacman -S reflector
Back up the current list, then write a fresh one filtered to your region. This example takes recent HTTPS mirrors from two countries and sorts them by measured download rate:
sudo cp /etc/pacman.d/mirrorlist /etc/pacman.d/mirrorlist.bak
sudo reflector --country Germany,France --protocol https --age 12 --latest 10 --sort rate --save /etc/pacman.d/mirrorlist
The written file headers record exactly how it was generated. When a mirrorlist misbehaves later, those lines tell you which command to rerun or blame.
# With: reflector --country Germany,France --protocol https --age 12 --latest 10 --sort rate --save /etc/pacman.d/mirrorlist
# When: 2026-11-10 06:12:16 UTC
# From: https://archlinux.org/mirrors/status/json/
# Retrieved: 2026-11-10 06:11:42 UTC
# Last Check: 2026-11-10 05:55:53 UTC
Server = https://frankfurt.mirror.pkgbuild.com/$repo/os/$arch
Server = https://ftp.halifax.rwth-aachen.de/archlinux/$repo/os/$arch
Server = https://mirror.ubrco.de/archlinux/$repo/os/$arch
The tail of the freshly ranked mirrorlist, captured on 10 November. The fastest servers head the list, and pacman works down it in order.

After changing mirrors, force a database refresh so the new servers are actually used. Without the doubled y, pacman can keep reading the old list from memory.
sudo pacman -Syyu
To keep the list fresh automatically, edit the options in /etc/xdg/reflector/reflector.conf and enable the timer with sudo systemctl enable --now reflector.timer. If you would rather build a list by country interactively, the country-based mirrorlist guide covers the web generator approach. Ranked mirrors also make upgrades less of a lottery, because pacman stops stalling on a server that happens to be having a bad week.
Handle .pacnew and .pacsave Files
When an upgrade ships a new default config for a file you have edited, pacman doesn’t overwrite your version. It writes the new one beside it as file.pacnew and prints a warning during the transaction. Ignore these for too long and your configs drift from upstream until something quietly breaks. Find any pending ones:
sudo find /etc -name '*.pacnew'
On a machine that is kept current, like the one used to test this guide, that search often comes back empty because nothing has drifted yet. The moment an upgrade touches a config you have edited, the file appears here. The clean way to review and merge them is pacdiff from pacman-contrib, which walks each one and lets you diff, merge, or remove it. Set a diff tool you like first:
sudo DIFFPROG=nvim pacdiff
The mirror image is file.pacsave, which pacman writes when you remove a package that owns a config flagged for backup. It is your old config, kept in case you reinstall. We make the pacnew sweep part of the routine after every big upgrade, because merging one file the week it appears takes a minute, and merging a year of drift takes an afternoon.
Install AUR Packages with yay
The Arch User Repository holds tens of thousands of community-maintained build scripts for software the official repos don’t carry, from Google Chrome to niche dev tools. yay is the most popular AUR helper, and it wraps pacman rather than replacing it, so once you know pacman, yay is almost free. If you’re torn between yay and paru, our yay vs pacman vs paru comparison measures build time, RAM use and the paru-bin breakage on current Arch.
yay itself lives in the AUR, so you bootstrap it once by hand. The yay-bin package installs a pre-built binary and skips the Go toolchain, which is the quickest route we’ve found. For the source build and other helpers, the dedicated yay install guide covers each option:
sudo pacman -S --needed git base-devel
git clone https://aur.archlinux.org/yay-bin.git
cd yay-bin
makepkg -si
The yay-bin package installs a prebuilt binary rather than compiling from source, which is why the transaction runs fast and skips the compiler entirely.

Run yay as your normal user, never with sudo. It calls sudo itself only for the pacman steps, and running the whole helper as root breaks its cache permissions. The core commands mirror pacman exactly, with the AUR folded in:
# Upgrade everything: repos AND the AUR (bare yay does the same)
yay -Syu
# Install from repos or the AUR
yay -S google-chrome
# Search repos and the AUR together
yay -Ss spotify
# Remove cleanly, exactly like pacman
yay -Rns google-chrome
Run yay with a search term and no operation, and it searches both repos and the AUR, numbers the results, and prompts you to pick which to install. Type numbers, ranges like 1-3, or ^2 to exclude. Installing an AUR package shows the build in real time:
yay -S downgrade
yay clones the build files, pulls any repo dependencies through pacman, then builds and installs. The whole flow runs in your user’s cache, so a failed build leaves nothing behind in the system.
Total Installed Size: 0.08 MiB
checking keyring...
checking package integrity...
loading package files...
checking for file conflicts...
:: Proceed with installation? [Y/n] checking available disk space...
:: Processing package changes...
installing downgrade...
Optional dependencies for downgrade
sudo: for installation via sudo [installed]
:: Running post-transaction hooks...
(1/1) Arming ConditionNeedsUpdate...
A real AUR install, including the dependency check, from the test machine. It reads just like a repo install, which is the whole point of yay.

The screenshot also carries yay -Ps output, which prints installed-package counts, foreign packages and cache sizes in one shot.
List AUR packages that have updates (yay -Qua)
This is the question pacman cannot answer on its own. pacman -Qu only checks the official repos, because the AUR is not in the sync databases. yay extends the query with the -a (AUR) flag, so the AUR-only equivalent of pacman -Qu is:
yay -Qua
It prints each foreign package that has a newer version in the AUR, in the same oldver -> newver form as checkupdates, and it installs nothing. When every AUR package is current, it prints nothing and exits with a nonzero status, which is itself the answer. Plain yay -Qu lists both repo and AUR updates together, and adding -a narrows it to the AUR. To upgrade only the AUR packages and leave repo packages untouched, use yay -Sua.
Inspect, count, and clean up
yay adds a print operation for system insight. The statistics view is a quick health snapshot:
yay -Ps
It totals your packages, separates the foreign ones, and lists the biggest. That biggest list is the same information expac gives you, pre-sorted. We run it after big cleanup sessions, because the counts should move exactly as much as the packages we removed.
==> Yay version v13.1.0
===========================================
==> Total installed packages: 436
==> Foreign installed packages: 3
==> Explicitly installed packages: 40
==> Total Size occupied by packages: 2.1 GiB
==> Size of pacman cache /var/cache/pacman/pkg/: 474.8 MiB
==> Size of yay cache /home/josphat/.cache/yay: 2.8 MiB
===========================================
==> Ten biggest packages:
gcc: 220.9 MiB
llvm-libs: 164.9 MiB
linux: 161.6 MiB
python: 73.9 MiB
perl: 72.3 MiB
That snapshot, plus the AUR update check you saw above, is what yay adds on top of pacman. A few more print and cleanup commands round out daily use, and each line below is its own command:
# List your installed AUR packages
yay -Qm
# Print the latest Arch news (read before big upgrades)
yay -Pw
# Count pending updates (handy for a status bar)
yay -Qu | wc -l
# Remove unneeded dependencies (orphans), AUR-aware
yay -Yc
# Clean the build and package caches
yay -Sc
Each of these is a pacman operation you already know, extended to see the AUR, so there’s nothing new to memorize. The one we run most is yay -Yc, because AUR builds leave more orphans behind than repo installs do. Between the statistics view, the news reader and the cleanup, yay covers the maintenance half of package management that pacman leaves to separate tools.
Read and edit PKGBUILDs before you build
The AUR is user-submitted, so reviewing a build script before running it is your main line of defense. We read the PKGBUILD of anything we install for the first time, and so should you. Print any package’s build script straight to the terminal without cloning it:
yay -Gp yay-bin
You see the maintainer, the package name and the exact version it will build. Those three lines are usually enough to decide whether to build.
# yay-bin
# Maintainer: Jguer <pkgbuilds at jguer.space>
pkgname=yay-bin
pkgver=13.1.0
pkgrel=1
By default yay shows a diff menu on AUR updates, so you can see what changed in the PKGBUILD since you last built it. That diff is your warning system against a hijacked package, so resist the urge to disable it. When you want the full build directory for hands-on editing, yay -G package-name downloads it.
Track -git and devel packages
Packages that build from a git branch (names ending in -git) only show an update when their version field changes, which can be never. To make yay check the upstream commit instead, enable devel tracking once and generate its database:
yay -Y --gendb
yay -Syu --devel
To make devel checks and a combined upgrade menu permanent, save them to the config. yay reads ~/.config/yay/config.json, and any flag becomes the default when you append --save:
yay --devel --combinedupgrade --cleanafter --save
With --cleanafter set, yay removes build files after a successful install, and --removemake drops make-only dependencies, which keeps an AUR-heavy system from filling up with build leftovers. The devel flag costs extra time on every upgrade, because yay queries upstream for each -git package, so we enable it only on machines that actually run -git software.
Use paru as an Alternative to yay
paru is the other widely used AUR helper, written in Rust by a former yay maintainer, and we keep it installed on one machine so we can compare behavior. The day-to-day commands are interchangeable: paru upgrades everything, paru -Sua upgrades AUR-only, paru -Qua lists AUR updates, and paru --gendb with paru --devel handles git packages. People pick paru for its stronger review defaults and its tighter pacman-style flag parity, so switching between the two helpers costs nothing but a package install. For most users the choice comes down to taste, Go versus Rust, rather than capability.
Build Your Own Packages with makepkg
Under every AUR install sits makepkg, which turns a PKGBUILD into an installable package. You’ll use it directly when packaging your own software or building from a PKGBUILD you fetched by hand. Install the build toolchain first:
sudo pacman -S --needed base-devel git
From inside a directory containing a PKGBUILD, this builds it, pulls any missing dependencies, installs the result, and cleans up afterward. The letters do three jobs, which is why the same line works for both AUR checkouts and your own packaging tests.
makepkg -sic
Never run makepkg as root. It refuses to start, by design, because build scripts run arbitrary code and root gives them the whole system. Two settings in ~/.config/pacman/makepkg.conf are worth setting:
MAKEFLAGS="-j$(nproc)"compiles across all coresPACKAGER="Your Namestamps you into builds"
The parallel flag is the one that changes your day, because AUR builds that crawl along on a single core finish in a fraction of the time once every core joins in. Neither setting affects correctness, so set them once and forget them.
Tune pacman.conf
A handful of settings make pacman faster and more readable. Open the config.
sudo vim /etc/pacman.conf
Uncomment or add these in the [options] section. Each one changes something you can see in the very next transaction.
# Colored output
Color
# Detailed version and size table before each transaction
VerbosePkgLists
# Download several packages at once (big speedup)
ParallelDownloads = 5
# Pac-Man animation in the progress bar
ILoveCandy
ParallelDownloads makes the most visible difference on large upgrades, and 5 to 10 suits most connections. To install 32-bit packages for Steam or Wine, enable the multilib repository in the same file: uncomment the [multilib] section header and its Include = /etc/pacman.d/mirrorlist line, then run sudo pacman -Syu to pick up the new repository. The Arch Wiki pacman page documents every option in full. One naming note for the testing repos: the old single [testing] was split into [core-testing] and [extra-testing], so enable those if you opt into testing. Of the four, only ParallelDownloads changes anything you can feel, so treat the rest as polish and enable it first.
Read the pacman Log
Every install, upgrade, and removal is recorded in /var/log/pacman.log, and it’s the first place we look when something changed and nobody admits to it. Filter it to just package transactions:
grep -E '\[ALPM\] (installed|upgraded|removed)' /var/log/pacman.log | tail
Each line is timestamped and shows the version change. That version pair, read in order, is your undo history.
[2026-11-10T06:16:43+0000] [ALPM] installed google-chrome (157.0.8103.38-1)
[2026-11-10T06:16:54+0000] [ALPM] removed google-chrome (157.0.8103.38-1)
[2026-11-10T06:16:54+0000] [ALPM] removed xdg-utils (1.2.1-2)
[2026-11-10T06:16:54+0000] [ALPM] removed ttf-liberation (2.1.5-2)
[2026-11-10T06:16:54+0000] [ALPM] removed libxss (1.2.5-1)
[2026-11-10T06:18:27+0000] [ALPM] installed mypackage (1.0-1)
[2026-11-10T06:18:33+0000] [ALPM] removed mypackage (1.0-1)
[2026-11-10T06:18:34+0000] [ALPM] installed mypackage (1.0-1)
[2026-11-10T06:18:40+0000] [ALPM] installed demo-a (1.0-1)
[2026-11-10T06:18:43+0000] [ALPM] installed demo-b (1.0-1)
The same window from the log file, grep filtered. Same lines, same order, straight off disk.

When an upgrade breaks something, this log tells you exactly which version you came from, which is what you feed to the downgrade steps above. It answers the other question too: whether a failure followed an install you just ran, or arrived on its own. We have more than once traced a “broken system” back to a single line in this log showing exactly which package changed and at what minute, which turns a vague complaint into a one-package fix.
Troubleshoot Common pacman Errors
Four errors account for most of the pacman questions people ask, and each has a fix you can run in seconds. Here is the map:
- a stale database lock
- a file conflict between packages
- a keyring signature failure
- downloads returning 404 errors
The first is a stale database lock. Pacman creates /var/lib/pacman/db.lck during a transaction and removes it when done, so a lock that lingers means pacman was killed mid-run and the next run fails:
error: failed to init transaction (unable to lock database)
error: could not lock database: File exists
if you're sure a package manager is not already
running, you can remove /var/lib/pacman/db.lck
Confirm no pacman is actually running before you touch the lock, then remove it:
pgrep -a pacman
sudo rm /var/lib/pacman/db.lck
Deleting that lock while a pacman process is genuinely running will corrupt the database, so the pgrep check is not optional. The second error is a file conflict, where a package wants to write a file that already exists:
error: failed to commit transaction (conflicting files)
demo-b: /usr/lib/demo-file exists in filesystem (owned by demo-a)
Check who owns the file with pacman -Qo /usr/lib/demo-file, which names demo-a. If the file is a known stale leftover, or you have verified the conflict is safe, reinstall with a narrow overwrite glob: sudo pacman -U --overwrite '/usr/lib/demo-file' ./demo-b-1.0-1-any.pkg.tar.zst. Never reach for --overwrite '*', which clobbers files owned by other packages and hides the real bug.
The third is the signature error covered earlier, fixed by updating archlinux-keyring. The fourth shows up as repeated download failures:
error: failed retrieving file 'htop-3.5.1-1-x86_64.pkg.tar.zst' from frankfurt.mirror.pkgbuild.com : The requested URL returned error: 404
error: failed retrieving file 'htop-3.5.1-1-x86_64.pkg.tar.zst' from ftp.halifax.rwth-aachen.de : The requested URL returned error: 404
error: failed retrieving file 'htop-3.5.1-1-x86_64.pkg.tar.zst' from mirror.ubrco.de : The requested URL returned error: 404
The three-mirror failure as the test machine printed it, pinned to an old archive snapshot. All three mirrors failed the same way, which points at the local database rather than any one server.

This means your local database points at packages a mirror has already rotated out, usually because you waited too long between syncs. To reproduce it, the test machine was pointed at a July snapshot of the Arch archive, which no longer carried the current htop build. Force a full database re-download, and if a mirror is simply dead, rank a fresh set with reflector first:
sudo pacman -Syyu
Once the databases are re-synced, the transaction finds the current package names and the 404s disappear. A dead mirror produces the same error text, so the fix above covers both causes: a stale local database and a mirror that’s gone away. The common thread is that pacman trusts its local view of the repositories, and when that view goes stale, every download against it fails until you force a refresh.
Pacman Command Reference
The full pacman quick reference, grouped by what you are doing.
| Command | What it does |
|---|---|
pacman -Syu | Refresh databases and upgrade everything (the only correct update) |
pacman -Syyu | Force a full database re-download, then upgrade |
checkupdates | List pending updates safely, without syncing the real database |
pacman -Qu | List installed packages with available updates |
pacman -S pkg | Install a package from the repos |
pacman -S --needed pkg | Install only if not already current |
pacman -Sw pkg | Download to the cache without installing |
pacman -U file.pkg.tar.zst | Install a local or remote package file |
pacman -Sg / -Sg group | List groups / list a group’s members |
pacman -R pkg | Remove a package, keep deps and config |
pacman -Rns pkg | Remove package, unused deps, and config |
pacman -Rns $(pacman -Qtdq) | Remove all orphaned packages |
pacman -Ss term | Search the repositories |
pacman -Si pkg | Show repo package details |
pacman -Qi pkg | Show installed package details |
pacman -Ql pkg | List files a package owns |
pacman -Qo /path | Find which package owns a file |
pacman -Fy / -Fx regex | Sync the file database / search it by regex |
pacman -Qe | List explicitly installed packages |
pacman -Qm | List foreign (AUR) packages |
pacman -Qtdq | List orphaned packages |
pacman -Qkk pkg | Verify a package’s files (size, perms, mtime) |
pacman -D --asdeps pkg | Mark a package as a dependency |
pacman -Sc / -Scc | Clean old cache / clean all cache |
pacman -Syu --ignore pkg | Upgrade while skipping a package |
Everything in the table has appeared earlier in the sheet with real output, so this is a bookmark page rather than new material.
Yay Command Reference
yay mirrors pacman’s flags and adds the AUR-aware commands. Anything you type in pacman’s spelling keeps working, so the table below only names the additions.
| Command | What it does |
|---|---|
yay or yay -Syu | Upgrade repos and the AUR together |
yay -Sua | Upgrade AUR packages only |
yay -Qua | List AUR packages that have updates |
yay -S pkg | Install from the repos or the AUR |
yay term | Search and pick from a numbered menu |
yay -Ss term | Search repos and the AUR |
yay -Rns pkg | Remove a package cleanly |
yay -Qm | List installed AUR packages |
yay -Ps | Print system and package statistics |
yay -Pw | Print the latest Arch news |
yay -Yc | Remove unneeded dependencies |
yay -Gp pkg | Print a package’s PKGBUILD |
yay -G pkg | Download a package’s build files |
yay -Y --gendb | Build the devel database for -git packages |
yay -Syu --devel | Upgrade, also checking -git packages for new commits |
yay --save | Persist the given flags to the config file |
The pacman spellings work unchanged inside yay, so anything from the pacman table earlier applies here too. That symmetry is the design goal, so learning pacman once covers both tools.
Set Up Shell Aliases That Save Keystrokes
Add these to ~/.bashrc or ~/.zshrc. They lean on yay because it covers both repo and AUR packages, so one alias does the whole job:
# Full system update (repos + AUR)
alias up='yay -Syu'
# Install and remove
alias get='yay -S'
alias rmv='yay -Rns'
# Search and info
alias pse='yay -Ss'
alias pin='yay -Si'
# Maintenance: list orphans and clean them with the cache
alias orphans='pacman -Qtdq'
alias clean='yay -Yc && yay -Sc'
Keep the set short. An alias you have to look up saves nothing, and every one of these hides a command you already know how to type. We keep up on every machine we touch and skip the rest when they don’t earn their keep, because muscle memory beats a lookup table every time.
If you would rather read a book than a web page, The Linux Command Line, 3rd Edition by William Shotts is the one to get. No Starch Press shipped the third edition in February 2026, it runs 544 pages, and it covers the same ground as this sheet with room to breathe. The book earns its shelf space because it explains the shell underneath these commands, which is knowledge that outlasts any cheat sheet.
Reload the shell with source ~/.bashrc and the aliases are live. Bookmark this page and keep it in a second terminal. The commands here cover the entire lifecycle of a package on Arch: finding it, installing it, holding it, downgrading it, cleaning up after it, and fixing the keyring when an upgrade refuses to run. For keeping the rest of a fresh install in shape, the Arch post-install guide picks up where package management leaves off.
This is an excellent guide to pacman and yay!
However, there is one thing that I can’t find in this cheatsheet …
I understand that “pacman -Qu” will list all pacman-accessible packages which have available updates.
But I’m also looking for a yay counterpart which will list all yay-accessible packages which have available updates.
Is there any way to get this info about yay packages with available updates?
Thank you very much in advance for any info you might be able to supply!
Use yay -Qua. The -a (–aur) flag limits the upgrade check to foreign/AUR packages, so it is the AUR-only counterpart to pacman -Qu. Plain yay -Qu lists repo and AUR updates together; adding -a narrows it to just the AUR ones. As an aside, yay -Qm lists your installed AUR packages regardless of whether an update is pending.