Installation

Parun is a terminal UI for Arch Linux package management. It works with local Pacman repositories, AUR helpers, and Nimble packages from one interface.

Install the binary

The installer downloads the latest GitHub release, validates that the downloaded file is a 64-bit ELF executable, and installs it into ~/.local/bin.

curl -sL gabrielcapilla.github.io/install | bash -s parun

Install via Nimble

Requirements:

  • Nim 2.2.0 or later
nimble install https://github.com/gabrielcapilla/parun.git@#head

Build from source

Clone the repository and build the release binary:

git clone https://github.com/gabrielcapilla/parun.git
cd parun
nimble build -d:release
cp "$(pwd)/parun" "$HOME/.local/bin/"

Release builds

Parun includes Nimble tasks for reproducible and local optimized builds:

# Deterministic release build
nimble release

# Host-optimized build for your own machine

nimble releaseNative

# Portable release check that rejects x86-64-v3/v4-only output

nimble releasePortable

Use releaseNative only for local use. Distribution builds should use release or releasePortable.

Quick Start

Run Parun without arguments to start in local Pacman mode:

parun

Type to search. The result list updates as you edit the query. Press ENTER to install the focused package, or select multiple packages with TAB and press ENTER to install the selected set.

Common launches

# Show help
parun --help

# Show version

parun --version

# Start with the details panel hidden

parun --noinfo

# Start with AUR enabled as the initial source

parun --aur

# Start with Nimble enabled as the initial source

parun --nimble

# Search across selected sources by default

parun --pacman --aur --nimble

Default behavior

By default, Parun enables Pacman, AUR, and Nimble indexes, but the initial view is local Pacman packages. Use search prefixes to switch sources without restarting:

aur/yay
nim/jester
installed/git

Explicit source filters

If you pass any source flag, the flags define the allowed source set. For example:

parun --aur --nimble

In that mode, Pacman is not enabled unless you include --pacman. Unprefixed search uses the combined selected sources when more than one source is enabled.

Package Sources

Parun can read from three package domains:

  • Pacman
    Local Arch repositories from `pacman -Sl`.
  • AUR
    AUR metadata from the official packages metadata feed.
  • Nimble
    Nim package metadata from the Nim packages index.

Source selection flags

Use flags to control which sources are available in a session:

# Local Pacman source
parun --pacman

# AUR source

parun --aur

# Nimble source

parun --nimble
parun --nim

# Combined source set

parun --pacman --aur --nimble

Source priority

When explicit filters are used, Parun chooses the initial source in this order:

  1. Pacman
  2. AUR
  3. Nimble

--pacman is not implied by --aur. If you want local repositories and AUR together, pass both:

parun --pacman --aur

System plugin detection

For system package transactions, Parun picks the first available tool in this order:

  1. paru
  2. yay
  3. pacman

The selected tool is used for install, uninstall, search/details support, and AUR-capable behavior when available.

Keyboard Controls

Parun is keyboard-first. All core actions can be performed without leaving the terminal UI.

Key Action
Esc Quit
F1 Toggle the details panel
Up or CTRL+K Move down the package list
Down or CTRL+J Move up the package list
Page Up Move down by one page
Page Down Move up by one page
TAB Select or deselect the focused package
CTRL+S Toggle selected-package review mode
ENTER Install focused package or selected packages
Ctrl+R Remove focused package or selected packages

Selection workflow

Use TAB to build a batch of packages:

  1. Search for a package.
  2. Move to the package with the arrow keys.
  3. Press TAB to select it.
  4. Repeat for additional packages.
  5. Press CTRL+S to review only selected packages.
  6. Press ENTER to install or CTRL+R to remove.

The status bar shows the selected count while packages are selected.

Install and Remove

Parun exits the alternate terminal UI before running install or remove transactions. This lets the underlying package manager show its normal prompts and output.

Install

Press ENTER to install:

  • The focused package, if nothing is selected
  • All selected packages, if one or more packages are selected

System packages are passed as repo/name targets when installing. Nimble packages are passed by package name.

Remove

Press CTRL+R to remove:

  • The focused package, if nothing is selected
  • All selected packages, if one or more packages are selected

Remove transactions pass package names without repository prefixes.

Transaction tools

Parun routes transactions by source. System plugin priority is paru, then yay, then pacman.

Source Tool
Pacman repositories paru, yay, or pacman
AUR paru, yay, or pacman plugin path, depending on detected tool
Nimble nimble

Indexes and Cache

Parun does not parse large package metadata on every keystroke. It builds compact runtime indexes and searches those indexes from memory-mapped files.

Cache directory

The default cache directory is:

~/.cache/parun

Set PARUN_CACHE_DIR to use another location:

PARUN_CACHE_DIR=/tmp/parun-cache parun

Runtime indexes

Parun creates .prix index files for enabled sources:

system.prix
aur.prix
nimble.prix
merged.system-aur-nimble.prix

Single-source sessions use the matching source index. Multi-source sessions can use a merged index so unprefixed search can cover the selected source set.

Metadata sources

Parun builds indexes from:

Source Metadata
Pacman pacman -Sl --color never
Installed system packages pacman -Q
AUR https://aur.archlinux.org/packages-meta-v1.json.gz
Nimble https://raw.githubusercontent.com/nim-lang/packages/refs/heads/master/packages.json
Installed Nimble packages nimble list -i --noColor

Refresh behavior

Missing or invalid indexes are rebuilt synchronously at startup. Stale but valid indexes can be used immediately while Parun starts a background refresh.

The default freshness window is one hour. Override it with:

PARUN_INDEX_MAX_AGE_SECONDS=300 parun

Use a positive integer value. Invalid or non-positive values fall back to the default.

Performance

Parun is written with a data-oriented design. The code separates hot search data from cold display data so filtering stays fast even with large package catalogs.

Search architecture

The runtime index stores package data in separate sections:

  • names and lowercased names for search
  • installed flags for filtering
  • repository and version data for rendering
  • first-byte buckets to narrow candidate scans

Search results are capped internally and score-sorted after filtering.

Details cache

The details panel uses a small bounded cache. Parun keeps only a limited number of detail payloads in memory and clears the cache when the byte budget is exceeded. Large detail payloads are truncated with a [truncated] marker.

Useful limits from the source:

Limit Value
Detail entries 8
Detail byte budget 128 KiB
Single detail payload cap 16 KiB

Performance snapshots

Use --perf-out=PATH to write runtime counters on graceful exit:

parun --perf-out=/tmp/parun-perf.json

The snapshot includes hot-path counters such as filter calls, candidate checks, score calls, installed checks, bucket lookups, and cold-path counters for row rendering, detail wrapping, cache hits, and cache misses.

Portable binaries

For public distribution, use:

nimble releasePortable

That task builds a release binary and fails if readelf reports an x86-64-v3 or x86-64-v4 ISA requirement.

Troubleshooting

parun: unknown option

Run:

parun --help

Supported public options are:

-h, --help
-v, --version
-n, --noinfo
--perf-out=PATH
--pacman
--aur
--nimble
--nim

No source selected

If explicit source flags are used but no source is enabled, Parun exits with:

parun: no package source selected; use --pacman, --aur, or --nimble.

Use at least one source flag:

parun --pacman
parun --aur
parun --nimble

AUR or Nimble source is disabled

If you started Parun with explicit filters, prefixes cannot access sources that were not enabled. For example:

parun --pacman

In that session, aur/foo shows a disabled-source status. Start with the required sources:

parun --pacman --aur --nimble

Index refresh fails

Parun needs working commands and network access for metadata refreshes:

  • pacman -Sl --color never
  • pacman -Q
  • curl
  • gunzip
  • nimble list -i --noColor when Nimble is enabled

If a cache looks stale or corrupt, remove the cache directory and restart:

rm -rf ~/.cache/parun
parun

Installer dependency errors

The install script checks for:

  • curl
  • file
  • sha256sum
  • xxd
  • readelf

On Arch Linux, xxd is commonly provided by vim or the xxd package, and readelf is provided by binutils.

~/.local/bin is not in PATH

The installer writes to ~/.local/bin. Add it to your shell profile:

export PATH="$HOME/.local/bin:$PATH"