Skip to main content

vappman

vappman presents a "visual" (or TUI) interface to appman/am.

Why use vappman? Browse 2000+ apps interactively with mouse/keyboard, filter by keywords or regex to rapidly find apps, and see installed vs. available at a glance. CLI option memorization is not required because context-sensitive keys guide you through the life cycle of your AppImages including installing, updating, and removing.

vappman demo

Prerequisites

Installation

  • Install vappman using pipx install vappman (recommended)
  • Run first time: vappman --prereq --doctor (check if system is ready)
  • Run normally: vappman

Key Features (Added in V2)

  • Dual Mode Support: Works with both am (system-wide) and appman (user-local). The (m) m-key toggles user (local install) and system (non-local install) modes when using am.
  • Multi-Database Support: Access all of am's app databases including:
    • am - Main AppImage database with 2000+ portable Linux applications
    • busybox - Minimal Unix utilities as binaries
    • appbundle - AppBundle format packages (portable application bundles)
    • python - Python interpreters (multiple versions available as AppImages)
    • soarpkg - Soar User Repository packages (portable, distro-independent binaries)
    • ALL - Combined view of all databases for comprehensive app browsing
  • Smart Backup Management:
    • Reports the number of backups when offering to restore (a.k.a., overwrite) installed apps
    • Automatically clean up superfluous backups with configurable retention (2, 1, or unlimited)
  • Flexible Install Options:
    • --icons - Use system icon themes instead of bundled icons
    • --sandbox - Run AppImage in sandboxed environment for security
    • Mix and match options per app
  • Incremental Search: Type-as-you-go filtering with instant feedback showing match effectiveness
  • Enhanced Display: For selected apps, shows full synopsis (if multi-line), current version, and app type
  • Persistent Preferences: Remembers your settings between sessions:
    • Default install options (--icons, --sandbox)
    • Preferred database selection
    • Maximum backups per application
  • Generally faster Although the number of offered apps has more than doubled with 3rd party database, the startup is faster (after the first time). The previous app list is used initially and then updated in the background.
  • AppImage Compatibility Checking: Automatic system checks for common AppImage issues (libfuse2, user namespaces, etc.) with distro-specific fix suggestions

Supported am/appman Operations

vappman covers many capabilities of am/appman:

  • (-f) files (or show installed), (-l) list available apps, and (-q) search the app list
  • (-i) installing uninstalled apps
  • (-r) removing installed apps
  • (-b) backup / (-o) overwrite of installed apps
  • (-a) about (i.e., more info) for all apps
  • (-c) clean to remove unneeded files and directories
  • (-u) update installed apps; and vappman offers:
    • U to update all installed apps
    • R to reinstall all apps with altered install scripts since last install

Not covered (use am/appman directly for these):

  • (-d) download install script
  • (-h) help or full help for appman
  • (-H) home or set $HOME directory for apps
  • (-t) template for custom install template
  • (-v) version of appman
  • --force-latest to get the most recent stable release AND all other options and unmentioned commands.

Usage

Run vappman from the command line. You will see a screen similar to this:

 m:AM-SYSTEM  [s]ync [c]lean [U]pd [R]eInst [q]uit ?:help  [d]b=ALL
  #:maxBkUp=1    [r]mv [u]pd C:icons [b]kup [a]bout S:unbox [t]est
─────────────────────────────────────────────────────────────────────────────────
>🔒─U onlyoffice ﹫am     Office Suite with full support for MS Windows formats
                     │    and cloud.
                     ╰── 🠞 9.2.0 appimage🔒
  ✔─U sas ﹫am            Tool to sandbox AppImages with bubblewrap easily.
  ✔─U signal ﹫am         Unofficial AppImage package for Signal (communication).
  ✔─U simplescreenrecorder ﹫am Unofficial. Feature-rich screen recorder supporti
  ✔─U ventoy ﹫am         Tool to create bootable USB drive for ISO/WIM/IMG/VHDx/
  ✔─U xnviewmp ﹫am       Graphic viewer, browser, converter.
  ✔─U zoom ﹫am           Unofficial. Video Conferencing and Web Conferencing Ser
    ◆ 0ad-prerelease @am  Unofficial. FOSS historical Real Time Strategy, RTS gam
    ◆ 0ad @am             Unofficial. FOSS historical Real Time Strategy, RTS gam
    ◆ 2ship @am           2 Ship 2 Harkinian game.
    ◆ 2to3 @soarpkg       Python2 to Python3 converter [python3].

Display Symbols Legend:

  • ✔ - Installed app (not sandboxed)
  • 🔒 - Installed app (sandboxed)
  • ◆ - Uninstalled/available app
  • S - Installed system-wide (requires root)
  • U - Installed in user space (local)
  • ﹫ - Database indicator (in multi-database view)
  • > - Currently selected app

Colour reinforces these symbols, never replaces them: installed rows are tinted with the HOTSWAP role and the inline install/remove prompts with DANGER. On a terminal without colour the roles fall back to bold/reverse attributes, so every state remains readable.

Press T to open the theme picker; t there cycles through the available themes and mono (no colour at all). The choice is remembered for the next run. --theme NAME and --no-color override it for a single run.

Global Keys (Top Line)

  • m - Switch mode if using am, toggling between SYSTEM and USER mode
  • s - Sync (update appman itself)
  • c - Clean up (remove unnecessary files and folders)
  • U - Update ALL installed apps
  • R - Reinstall ALL apps with changed installation scripts (am database only)
  • q or x - Quit vappman
  • ? - Show help screen with all keys including navigation keys
  • d - Cycle through app database choices; ALL shows all databases in a combined view
  • / - Start incremental search filter for apps
  • ESC - Clear filter and jump to top of listing
  • _ - Toggle fancy header mode (Underline/Reverse/Off)
  • * - Toggle demo mode
  • # - Change number of backups to keep (2, 1, or -1 for infinite)
  • T - Open the colour-theme picker (t cycles there; mono disables colour)

Navigation Keys

Press ? to see full navigation help. Common keys include:

  • Arrow keys, Page Up/Down, Home/End - Navigate the app list
  • Mouse wheel - Scroll through apps
  • Vi-like keys: j/k (down/up), g/G (top/bottom), Ctrl-f/Ctrl-b (page down/up)
  • The selection follows the app: after you install, remove, update, or switch mode/database, the cursor stays on the same app — or the nearest row if it's gone
  • ENTER - Context-sensitive action:
    • On uninstalled app: Install it
    • On installed app: Uninstall it
    • In help screen: Return to main menu

Search/Filter Syntax

Press / to start filtering. The filter supports two modes:

Plain Word Matching (default for simple text):

  • Words must match the start of words in the app line (in order, but not contiguously)
  • Example: /bit fight matches bitfighter
  • Example: /term edit matches "terminal editor"

Regular Expression Mode (detected automatically):

  • Use Python regex syntax for advanced patterns
  • ^ - Match line starting with app name
  • \b - Match word boundary
  • Example: /^vim - Apps starting with "vim"
  • Example: /\bweb\b - Apps with whole word "web"

Filter Controls:

  • ENTER - Accept filter and return to browsing
  • ESC - Cancel filter edit (restores previous filter)
  • Typing updates results in real-time
  • While you are typing, no line is shown as selected (the selection highlight is hidden until you press ENTER or ESC), so the pattern being entered is unambiguous
  • Your selection follows the app, not the row: if the app you had selected still matches after the filter changes — even if it moved position — it is re-selected on ENTER/ESC. If it no longer matches, the top of the list is selected

App-Specific Keys (Second Line)

For UNINSTALLED apps:

  • i or ENTER - Install the app. A prompt appears below the entry's rows (so the synopsis stays readable), followed by the install-type menu:
        ⚠️  Install <app>?
        *n:none s:sandbox c:icons b:both y:last ESC
    
    • n - plain install
    • s - sandboxed
    • c - system icon themes
    • b - both icons and sandbox
    • y - reuse the starred (last-used) choice
    • ESC - cancel the install
    • The * marks the options used by the last confirmed install; that choice is remembered across sessions. The confirmed command is run with -y, so am/appman does not ask again
  • Note: If an app with the same name is installed from another database, you'll see a conflict warning instead of install keys

For INSTALLED apps:

  • r or ENTER - Remove the app
  • C - Change AppImage to use system icons
  • S - Toggle sandbox mode (box/unbox)
  • b - Backup the app
  • u - Update this app
  • a - Show "about" information from am/appman
  • o - Overwrite app from its backup (shows count of available backups)
  • t - Test the app by running it in a terminal

For r, C, S and b, a prompt appears below the entry's rows (synopsis and version/type remain visible), e.g. ⚠️ Remove <app>? Press y or ESC; y confirms, ESC cancels, and all other keys are ignored until you answer. The confirmed command is run with -y, so am/appman does not ask again.

Note on sandboxing: AM's -y also accepts its directory-access questions for --sandbox, which grants the sandboxed app access to the XDG user folders (Desktop, Documents, Downloads, etc.). Run am --sandbox <app> manually after if you want to choose those folders yourself.

App List Display

The main screen shows installed apps first (marked with ✔ or 🔒), followed by available/uninstalled apps (marked with ◆).

When you install or remove an app, vappman temporarily exits the TUI, runs the am/appman command so you can see the result, then prompts you to press ENTER to return. Install and remove commands confirmed in the TUI are passed -y, so the single confirmation is vappman's inline prompt.

Testing Apps

Use t to test an installed app. This launches a terminal emulator and runs the app so you can see any console output or errors. Useful for go/no-go check after installation.

Supported terminal emulators (searched in this order): konsole, gnome-terminal, xfce4-terminal, lxterminal, alacritty, guake, tilix, sakura, terminator, kitty


Checking AppImage Compatibility

vappman automatically checks your system for common AppImage compatibility issues on startup. If critical issues are found, it displays them before launching the TUI and pauses for 3 seconds so you can read the warnings. You'll see something like:

AppImage compatibility check:
  ✓ libfuse2: OK
  ✓ user namespaces: OK
  ✓ /tmp noexec: OK
  ✓ AppArmor: OK

Run Detailed Check Run vappman --doctor for these checks:

  1. libfuse2 - Required library for most AppImages (critical)
    • Ubuntu 22.04+ doesn't include this by default
    • Fix: sudo apt install libfuse2 (Ubuntu/Debian)
  2. User namespaces - Needed for sandboxed AppImages (warning)
    • Sometimes disabled for security on Ubuntu-based systems
    • Fix: sudo sysctl -w kernel.unprivileged_userns_clone=1
  3. /tmp noexec - Prevents AppImages from executing (critical)
    • Some systems mount /tmp with noexec flag
    • Fix: sudo mount -o remount,exec /tmp or set TMPDIR=$HOME/tmp
  4. AppArmor - May block some AppImages (info, Ubuntu/Debian)
    • Active AppArmor profiles can restrict AppImage execution
    • Check logs if AppImages fail: sudo dmesg | grep -i apparmor
  5. SELinux - May block AppImages (warning, Fedora/RHEL/CentOS)
    • Enforcing mode can prevent AppImage execution or resource access
    • Check logs: sudo ausearch -m avc -ts recent
    • Temporary fix: sudo setenforce 0

Command-line options:

vappman --check-appimage  # Run detailed system check
vappman --doctor          # Alias for --check-appimage
vappman --no-startup-check  # Skip automatic check on startup
vappman --help            # Show all options

Example output when issues are found:

AppImage Compatibility Check (Ubuntu 24.04 LTS)
============================================================
  ✗ libfuse2: libfuse2 is not installed (required for most AppImages)
    Fix: sudo apt install libfuse2
  ⚠ user namespaces: Unprivileged user namespaces are disabled
  ✓ /tmp noexec: OK
  ✓ AppArmor: OK

Detailed Information:
------------------------------------------------------------

✗ libfuse2:
  libfuse2 is not installed (required for most AppImages)
  Fix: sudo apt install libfuse2

⚠ user_namespaces:
  Unprivileged user namespaces are disabled (sandboxed AppImages will fail)
  Suggestion: sudo sysctl -w kernel.unprivileged_userns_clone=1
  To make permanent: echo "kernel.unprivileged_userns_clone=1" | sudo tee /etc/sysctl.d/00-local-userns.conf

The compatibility checker is distro-aware and provides appropriate fix commands for:

  • Ubuntu/Debian (apt)
  • Fedora/RHEL (dnf)
  • Arch/Manjaro (pacman)
  • openSUSE (zypper)
  • And more

Metadata

Release files for vappman 2.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vappman 2.2.2
File Size Uploaded Provenance Actions
vappman-2.2.2.tar.gz 43.9 kB Without provenance Details for vappman-2.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vappman 2.2.2
File Interpreter ABI Platform Actions
vappman-2.2.2-py3-none-any.whl Python 3 none any Details for vappman-2.2.2-py3-none-any.whl

Total release size: 85.7 kB

Release files / vappman-2.2.2.tar.gz

Download URL vappman-2.2.2.tar.gz
Size 43.9 kB
Tags Source
SHA-256 checksum
How to use checksums
91a5b11dc8fa42a56ce6c23555eefdcfea1fb516fc7eb9307be80545ad7d333e
BLAKE2b-256 checksum
How to use checksums
e7847734953f59d0c50a216573cb16201978dd4942f3dfa95c5a1e61adea57f2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / vappman-2.2.2-py3-none-any.whl

Download URL vappman-2.2.2-py3-none-any.whl
Size 41.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e977840178e77ea7ac614522c3efb57d5b5342abad3caef0091ea27f4df7285
BLAKE2b-256 checksum
How to use checksums
ce74baeff3c005e1812469c5f431566e5c80cd40f75057a52b09e8f0c9e93892
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for vappman 2.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page