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

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)

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
  • O - Cycle through install options:
    • `` (none) - Default install
    • icons - Use system icon themes
    • sandbox - Run in sandboxed environment
    • icons,sandbox - Both options
  • 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
  • u - Update this app
  • C - Change AppImage to use system icons
  • a - Show "about" information from am/appman
  • S - Toggle sandbox mode (box/unbox)
  • b - Backup the app
  • o - Overwrite app from its backup (shows count of available backups)
  • t - Test the app by running it in a terminal

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.

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.1.7

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.1.7
File Size Uploaded Provenance Actions
vappman-2.1.7.tar.gz 18.0 MB Without provenance Details for vappman-2.1.7.tar.gz

Built distribution (wheel)

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

Total release size: 18.1 MB

Release files / vappman-2.1.7.tar.gz

Download URL vappman-2.1.7.tar.gz
Size 18.0 MB
Tags Source
SHA-256 checksum
How to use checksums
bf013fc0901d9510dad03687ff8a7ab7772893117f11d18351755852806c3c19
BLAKE2b-256 checksum
How to use checksums
1766e956c9e9671044cf1a8aa6d7b149e81083b821d8f0e05bc2aba7321a723f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via python-requests/2.32.5

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

Download URL vappman-2.1.7-py3-none-any.whl
Size 34.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
51f82585af88d4a9c15b088669530b28670ae109ef4a7831b4ffa13324e9c791
BLAKE2b-256 checksum
How to use checksums
29553bf31ade93c27daca063124e785c499ec3c313a0d01c2bb0ece1e19f8ab3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via python-requests/2.32.5

Security for vappman 2.1.7

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