X Linux
Documentation menu

Overview/xpm — package manager

xpm — Usage

Complete usage reference for the xpm binary, based on crates/xpm/src/cli.rs, crates/xpm/src/main.rs, and the project README.


Global flags

These flags are accepted by every subcommand.

FlagShortValueDescription
--config-cPATHPath to the configuration file (default /etc/xpm.conf)
--verbose-vcountIncrease verbosity (-v, -vv, -vvv)
--no-confirmSkip confirmation prompts (alias --noconfirm)
--root-rPATHAlternative installation root directory
--sysrootPATHOperate on a mounted guest system (root, database and cache paths)
--dbpath-bPATHAlternative database directory
--cachedirPATHAlternative cache directory
--no-colorDisable colored output
--no-pacman-mirrorDo not mirror transactions into pacman's local database
--shell-integrationEnable ~/.local/bin shims and rc edits for non-root installs
--no-shell-integrationDisable shell integration (default)
--scriptletsMODEScriptlet policy: auto, skip or require
--noscriptletAlias for --scriptlets skip

The CLI is defined with clap and requires a subcommand (arg_required_else_help = true).

Commands

sync — Synchronize package databases

Alias: Sy. Downloads the latest .db (and best-effort .files) database files from every configured repository and parses them into local sync databases.

xpm sync [OPTIONS]
xpm Sy [OPTIONS]
FlagShortDescription
--force-fForce a full database refresh even if databases look up to date

Implementation note: cmd_sync in main.rs runs per-repository sync workers in parallel chunks, tries each configured mirror with retries, reports which mirror answered, and then parses the downloaded .db / .files so the local package count can be shown. Remote sync failures are warned and do not abort the whole run.

install — Install packages

Alias: S. Installs one or more packages by name from the synchronized databases.

xpm install <PACKAGES>... [OPTIONS]
xpm S <PACKAGES>... [OPTIONS]
FlagShortDescription
--download-only-wDownload packages without installing
--as-depsMark the package as installed as a dependency
--as-explicitMark the package as explicitly installed
--no-optionalSkip optional dependencies
--neededSkip packages already installed at the same version
--print-pPrint the resolved packages without downloading or installing
--overwriteOverwrite conflicting files matching PATTERN (repeatable, ! negates)
--ignoregroupIgnore packages in GROUP (repeatable)
--assume-installedAssume PKG=VER is installed for dependency resolution (repeatable)

Behavior (from main.rs): every configured sync database is loaded and the requested requirements (name or name=version) are solved with the SAT resolver, which picks candidates, honors depends/conflicts and unversioned provides, and returns the closure in dependency order. Each package is downloaded to the cache directory, checked against a remote .sig per the effective sig_level and against sha256sum when the database entry carries one, then committed as install operations on a Transaction (requested packages explicit, pulled dependencies as deps; --as-deps/--as-explicit override). With --download-only the run stops after downloading. Otherwise xpm asks for confirmation (unless --no-confirm) and the transaction extracts the files and registers each package in the local database.

remove — Remove packages

Alias: R. Removes installed packages, using the file manifest recorded in the local database.

xpm remove <PACKAGES>... [OPTIONS]
xpm R <PACKAGES>... [OPTIONS]
FlagShortDescription
--recursive-sAlso remove unneeded dependencies
--no-deps-dSkip dependency checks
--nosave-nRemove configuration files as well (purge)
--cascadeRemove packages that depend on the targets (pacman -Rc)
--unneeded-uKeep targets that are still required by another package

The package must be registered in the local database (otherwise xpm reports it is not installed). Confirmation is requested unless --no-confirm.

upgrade — System upgrade

Alias: Su. Upgrades all installed packages to the newest available versions.

xpm upgrade [OPTIONS]
xpm Su [OPTIONS]
FlagShortDescription
--forceForce reinstallation of up-to-date packages
--ignoreSkip specific packages (repeatable, --ignore <PKG>)
--print-pPrint the upgrade plan without downloading or installing
--download-only-wDownload packages without committing the upgrade
--overwriteOverwrite conflicting files matching PATTERN (repeatable)
--ignoregroupIgnore upgrades for packages in GROUP (repeatable)
--assume-installedAssume PKG=VER is installed for dependency resolution (repeatable)

upgrade always refreshes the databases first (equivalent to pacman -Syu), then resolves the transitive closure of the packages with newer versions so new or newly-required dependencies are installed in the same run. Upgraded packages keep their install reason; pulled dependencies are recorded as deps. With no packages installed it reports "Nothing to do".

query — Query the local database

Alias: Q. Lists installed packages from the local database.

xpm query [FILTER] [OPTIONS]
xpm Q [FILTER] [OPTIONS]
Argument / FlagShortDescription
FILTERPackage name (exact by default; substring with --search)
--formatOutput format: plain (default) or tsv
--explicit-eOnly explicitly installed packages
--deps-dOnly packages installed as dependencies
--searchTreat FILTER as a substring instead of an exact name
--quiet-qPrint only package names
--ownerFind the installed package that owns PATH
--foreign-mPackages not present in any configured sync database
--native-nPackages present in a configured sync database
--fileQuery a package file instead of the local database
--changelogShow the changelog stored for an installed package
--unrequiredPackages no other installed package directly requires
--orphans-tOrphan packages (no longer required)
--upgrades-uPackages with available updates

Implementation note: implemented against the local and sync databases (name filter plus --explicit, --deps and --upgrades). --orphans lists dependency packages that no explicitly installed package requires, using the depends/provides edges recorded at install time; legacy entries without a record are skipped.

search — Search packages

Alias: Ss. Searches for packages by name, description, or provides.

xpm search <QUERY> [OPTIONS]
xpm Ss <QUERY> [OPTIONS]
FlagShortDescription
--local-lSearch in the local database instead of the sync databases

Implementation note: implemented as a case-insensitive match over name, description and provides; --local matches installed package names.

info — Package information

Alias: Si. Displays detailed information about a package.

xpm info <PACKAGE> [OPTIONS]
xpm Si <PACKAGE> [OPTIONS]
FlagShortDescription
--local-lQuery the local database instead of the sync databases

Implementation note: implemented; merges the installed entry with the highest-priority sync entry, and --local limits the output to the installed database.

files — List package files

Alias: Ql. Lists all files owned by an installed package.

xpm files <PACKAGE>
xpm Ql <PACKAGE>

Implementation note: implemented; reads the files manifest recorded at install time (empty for legacy installs).

history, rollback, diff — Journal and generations

  • xpm history [--json] — recorded transactions, newest first. Finished entries link the generation they produced (gen:NNNN, when the state directory is readable).
  • xpm rollback [--last | --journal <ID>] [--dry-run] — replay the inverse of a successful transaction using the package cache; aborts before changing anything if an old package file is missing.
  • xpm diff <GENERATION> [--json] — compare the installed packages against a generation's packages.tsv (current resolves the default id).

Configuration files declared with backup in .PKGINFO follow pacman semantics: .pacnew on install/upgrade and .pacsave on removal (disable with --nosave). Pacman-style ALPM hooks from /usr/share/libalpm/hooks and /etc/pacman.d/hooks run around every transaction.

repo — Repository management

Manages user-added (temporary) repositories. Predefined repositories come from /etc/xpm.conf; user-added repositories are stored as TOML files under /etc/xpm.d/.

xpm repo list                 # predefined + user-added repositories
xpm repo add <NAME> <URL>     # add a temporary repository
xpm repo remove <NAME>        # remove a user-added repository

Examples (from the built-in help):

xpm repo add chaotic-aur https://cdn-mirror.chaotic.cx/$repo/$arch
xpm repo add my-repo https://username.github.io/my-repo/$arch
xpm repo add local file:///srv/packages/$arch

repo add refuses to overwrite an existing entry of the same name. After adding a repository, run xpm sync to fetch its database.

build — Build a source package with makepkg

Builds a PKGBUILD/XBUILD directory with makepkg and collects the resulting packages. This is the backend used by xpm-aur for AUR packages.

xpm build [DIR] [OPTIONS]
xpm build path/to/pkg --pkgdest ./out --clean --install
xpm build . --chroot --json build.json -- --nocheck
Flag / ArgumentDescription
DIRDirectory containing PKGBUILD (default: .)
--pkgdest PATHOutput directory (default: <DIR>/.xpm-packages)
--srcdest PATHmakepkg source cache directory
--builddir PATHmakepkg build directory
--nocheckSkip the check() function
--cleanRemove existing package files from --pkgdest before building
--chrootBuild inside a clean devtools chroot (requires devtools and sudo)
--chroot-dir PATHChroot root/copy directory (default /var/lib/archbuild/xpm-aur)
--installInstall the built packages with xpm after a successful build
--as-deps / --as-explicitInstall reason for --install
--preinstall PKGInstall a local package into the clean chroot (repeatable)
--json PATHWrite the build result as JSON
-- <args>Extra arguments passed through to makepkg

Other commands

CommandWhat it does
xpm bootstrap [PACKAGES]...Bootstrap an empty root with xpm (filesystem + bash, then base-devel by default).
xpm import-pacman [--from PATH] [--force]Import installed packages from pacman's local database.
xpm sync-pacman-db [--pacman-db PATH]Rewrite pacman's local database from xpm's database.
xpm check [--full] [PACKAGES]... (alias Qk)Verify installed files; --full also checks .MTREE hashes, modes and symlinks.
xpm mark (--as-deps|--as-explicit) <PACKAGES>... (alias D)Change the install reason of installed packages.
xpm deptest <DEP>... (alias T)Test dependency specifications against installed packages.
xpm groups [GROUP] [--local] [--names] [-q]List package groups (sync or local).
xpm list [REPO] [-q]List packages available in the sync repositories (-Sl form).
xpm clean [--all]Remove cached package files (-Sc/-Scc forms).
xpm file-db [-y] [-l] [-q] [--repo REPO] [TARGETS]...Query the sync .files databases (-F form).

usage — Built-in help

Shows detailed usage help for the whole tool or for a topic/command.

xpm usage                    # general overview
xpm usage commands           # list all commands
xpm usage config             # configuration file format
xpm usage repos              # repository management
xpm usage <command>          # help for a specific command (sync, install, remove, upgrade, ...)

xpm <command> --help also works through clap.

Pacman-style aliases

AliasMaps toPacman equivalent
Sysyncpacman -Sy
Sinstallpacman -S
Rremovepacman -R
Suupgradepacman -Su
Qquerypacman -Q
Sssearchpacman -Ss
Siinfopacman -Si
Qlfilespacman -Ql
Qkcheckpacman -Qk
Dmarkpacman -D
Tdeptestpacman -T

Typical workflow

xpm sync                       # refresh package databases
xpm install <package>          # install a package
xpm upgrade                    # upgrade installed packages (syncs first)
xpm query                      # list installed packages
xpm remove <package>           # remove a package

Non-interactive use (for scripts) needs --no-confirm. For isolated/rootless experiments use --config, --root, --dbpath, and --cachedir to point at temporary directories; when the installation root is not /, xpm enables shell integration and creates command shims in ~/.local/bin (with PATH export lines in ~/.bashrc and ~/.zshrc).

Environment variables and exit codes

RUST_LOG is honoured through tracing-subscriber's EnvFilter to control log verbosity. docs/CLI.md additionally documents XPM_CONFIG, XPM_CACHE_DIR, XPM_HOOKS_DIR, XPM_ALPM_HOOKS_DIRS, X_GEN_STATE, and NO_COLOR.

docs/CLI.md documents an exit-code matrix (0 success, 1 general error, 2 usage error, up to 7 database locked). Note that this matrix is documented intent rather than an enforced contract in the current code: in practice clap reports usage errors, anyhow reports runtime failures, and other documented codes are not yet emitted by main.rs. Verify against the code before relying on a specific code.

References

Edit this page on GitHub