[go: up one dir, main page]

Skip to content
/ AM Public
forked from ivan-hc/AM

AppImage package manager to install, update and manage ALL of them, system-wide or locally, thanks to its ever-growing AUR-inspired database listing 2000+ portable apps and programs for GNU/Linux. The first, real centralized repository to manage your AppImages with the ease of APT and the power of PacMan.

License

Notifications You must be signed in to change notification settings

lwhiteley/AM

 
 

Repository files navigation

"AM" Application Manager

Database & solutions for all AppImages and portable apps for GNU/Linux!

sandbox AppImages list available apps info about the apps
install applications query lists using keywords show the installed apps
create and restore snapshots update everything get rid of libfuse2

"AM"/"AppMan" is a set of scripts and modules for installing, updating, and managing AppImage packages and other portable formats, in the same way that APT manages DEBs packages, DNF the RPMs, and so on... using a large database of Shell scripts inspired by the Arch User Repository, each dedicated to an app or set of applications.

The engine of "AM"/"AppMan" is the "APP-MANAGER" script which, depending on how you install or rename it, allows you to install apps system-wide (for a single system administrator) or locally (for each user).

"AM"/"AppMan" aims to be the default package manager for all AppImage packages, giving them a home to stay.

You can consult the entire list of managed apps at portable-linux-apps.github.io/apps.


IMPORTANT!

"AM"/"AppMan" is just a tool to provide applications easily and quickly and is only responsible for integrating the AppImages into the system and installing the various programs available, respecting the following order (refer to the option "-d" to download the installation script without installing it):

  1. creation of the base directories and the removal script
  2. download of the package
  3. creation of the version file and the update script
  4. possibly, extraction of the icons and .desktop files*

*NOTE, aside from the references to downloading and updating apps (the "$version" variable), the installation scripts are mostly the same, especially for AppImages, and there may be slight variations in the final processes depending if the .desktop file has problems when it is extracted from the package and/or it fail in being added to the menu. If there are problems with updates or missing launchers, open an "issue" and I'll fix it ASAP.

That said, any malfunction related to individual applications is the responsibility of the related developer or packager.

Refer to the option "-a" to know the sources of each program listed here, so you can contact them to report the bug.


Main Index


Differences between "AM" and "AppMan"

What programs can be installed

How to update all programs, for real

Installation

Uninstall

Usage (all the available options)

Guides and tutorials

Instructions for Linux Distro Maintainers

Troubleshooting

Related projects


Differences between "AM" and "AppMan"

"AM" and "AppMan" differ in how they are installed, placed and renamed in the system and how/where they install apps:

  • "AM" is installed system-wide (requires sudo or doas) in /opt/am/ as "APP-MANAGER", with a symlink named "am" in /usr/local/bin.
  • "AppMan" is portable, you need just to rename the "APP-MANAGER" script as "appman" and put it wherewer you want. I recommend to place it in $HOME/.local/bin to be used in $PATH, to be managed from other tools (see below).

Both can be updated using "Topgrade".


Ownership

  • "AM" is owned by the user that have installed it, since other users have not read/write permissions in "/opt/am";
  • "AppMan" is for all users, since it works locally, everyone can have its own apps and configurations.

About "sudo" usage

  • "AppMan" can request the root password only in the very rare case in which you want to install a library;
  • "AM" requires the root password only to install, remove apps, enable a sandbox for an AppImage.

All options cannot be executed with "sudo"/"doas".


How apps are installed


  • "AM" installs apps system wide, in /opt (see Linux Standard Base), using the following structure:
/opt/$PROGRAM/
/opt/$PROGRAM/$PROGRAM
/opt/$PROGRAM/AM-updater
/opt/$PROGRAM/remove
/opt/$PROGRAM/icons/$ICON-NAME
/usr/local/bin/$PROGRAM
/usr/local/share/applications/$PROGRAM-AM.desktop

  • "AppMan" is more flexible, since it asks you where to install the apps. For example, suppose you want install everything in "Applicazioni" (the italian of "applications") and in your $HOME directory, this is the structure of what an installation scripts installs with "AppMan" instead:
~/Applicazioni/$PROGRAM/
~/Applicazioni/$PROGRAM/$PROGRAM
~/Applicazioni/$PROGRAM/AM-updater
~/Applicazioni/$PROGRAM/remove
~/Applicazioni/$PROGRAM/icons/$ICON-NAME
~/.local/bin/$PROGRAM
~/.local/share/applications/$PROGRAM-AM.desktop

The configuration file for AppMan is in ~/.config/appman and contains the path you indicated at first startup. Changing its contents will result in changing the paths for each subsequent operation carried out with "AppMan", the apps and modules stored in the old path will not be manageable.

At first startup you can indicate any directory or subdirectory you want.


How to use "AM" in non-privileged mode, like "AppMan"

As already mentioned above, at "Ownership" the user who installed "AM" is the sole owner, having write permissions for both /opt/am and for all installed apps.

However, every user of the same system is allowed to use the option --user or appman, to use "AM" as "AppMan" and to install apps locally and withour root privileges:

am --user

To switch "AM" back to "AM" from "AppMan Mode", use the always suggested option --system:

am --system

To perform a test and see if you are in "AppMan Mode" or not, run for example the command am -f to see the list of the installed apps.

In this video I'll install LXtask locally:

unprivileged-user.mp4

NOTE: non-privileged users can update their own local applications and modules, but cannot update /opt/am/APP-MANAGER.

It is therefore suggested to use pure "AppMan" instead of the "AppMan Mode" of "AM".


Install "AM"/"AppMan" Back to "Main Index"

What programs can be installed

"AM"/"AppMan" installs, removes, updates and manages only standalone programs, ie those programs that can be run from a single directory in which they are contained. The database aims to be a reference point where you can download all the AppImage packages scattered around the web, otherwise unobtainable, as you would expect from any package manager, through specific installation scripts for each application, as happens with the AUR PKGBUILDs, on Arch Linux. You can see all of them here, divided by architecture.

NOTE that currently my work focuses on applications for x86_64 architecture, but it is possible to extend "AM" to all other available architectures. If you are interested, you can deliberately join this project to improve the available lists.

  1. PROGRAMS, they are taken:
  • from official sources (see Firefox, Thunderbird, Blender, NodeJS, Chromium Latest, Platform Tools...);
  • extracted from official .deb/tar/zip packages;
  • from the repositories and official sites of individual developers.
  1. APPIMAGES, they are taken:
  • from official sources (if the upstream developers provide them);
  • from AppImage recipes to be compiled on-the-fly with pkg2appimage and appimagetool;
  • from unofficial third-party developers, but only if an official release is not available.
  1. FIREFOX PROFILES to run as webapps, the ones with suffix "ffwa-" in the apps list.

  2. THIRD-PARTY LIBRARIES (see here) if they are not provided in your distribution's repositories. These are to be installed in truly exceptional cases.

You can consult basic information, links to sites and sources used through the related command am -a $PROGRAM or appman -a $PROGRAM, or visit portable-linux-apps.github.io/apps.


Back to "Main Index"

How to update all programs, for real

One of the reasons why many users hate Appimages is because they cannot be updated. Or at least not all.

This project was born to dispel this myth and to solve the problem. And the solution is much more trivial than you expect.

There are several methods to update apps, here are the most common ones, in order of priority:

  • the "comparison between versions" is the most widespread in the database, the version of the app installed is compared with the one present at the source, be it an official site or another site that tracks it;
  • if an AppImage package has a .zsync file, that will be used to download binary deltas (especially useful with large files, but not very popular among developers);
  • some portable apps are self-updatable (see Firefox and Thunderbird);
  • if an app or script is extremely small (a few kilobytes), it is downloaded directly from scratch;
  • in rare cases, if a file .zsync is broken, we use appimageupdatetool;
  • in some cases, the apps have a fixed version, both due to the developers' choices to abandon a portable package in favor of other more common platforms, and because a software is no longer developed.

NOTE, fixed versions will be listed with their build number (e.g. $PROGRAM-1.1.1) or will be added only upon request.

How to update all installed apps

Option -u or update updates all the installed apps and keeps "AM"/"AppMan" in sync with the latest version and all latest bug fixes.

update-and-sync.mp4
  1. To update only the programs, use am -u --apps / appman -u --apps
  2. To update just one program, use am -u $PROGRAM / appman -u $PROGRAM
  3. To update all the programs and "AM"/"AppMan" itself, just run the commandam -u / appman -u
  4. To update only "AM"/"AppMan" and the modules use the option -s instead, am -s / appman -s

NOTE, non-privileged users using "AM" in "AppMan Mode" cannot update /opt/am/APP-MANAGER (points 3 and 4). See "How to use AM in non-privileged mode, like AppMan".

How to update everything using "Topgrade"

Keeping your system up to date usually involves invoking multiple package managers. This results in big, non-portable shell one-liners saved in your shell. To remedy this, Topgrade detects which tools you use and runs the appropriate commands to update them.

Install the "topgrade" package using the command

am -i topgrade

or

appman -i topgrade

Visit github.com/topgrade-rs/topgrade to learn more.

NOTE, "AppMan" users must install appman in ~/.local/bin to allow updates via Topgrade. See "How to install AppMan".


Back to "Main Index"

Installation

This section explains how to install "AM" or "AppMan".

Core dependencies

Below are the essential system dependencies that you must install before proceeding:

  • "coreutils" (contains "cat", "chmod", "chown"...);

  • "curl", to check URLs;

  • "grep", to check files;

  • "less", to read the ever-longer lists;

  • "sed", to edit/adapt installed files;

  • "wget" to download all programs and update "AM"/"AppMan" itself.

  • "sudo" or "doas", required by "AM" only, to install/remove programs and sandbox AppImages.

Extra dependencies (recommended)

Click here to see the optional dependencies that some programs may require
  • "binutils", contains a series of basic commands, including "ar" which extracts .deb packages;
  • "unzip", to extract .zip packages;
  • "tar", to extract .tar* packages;
  • "torsocks", to connect to the TOR network;
  • "zsync", required by very few programs and AppImages (although it is mentioned in all installation scripts, it is often disabled because the managed .zsync files are often broken, especially for apps hosted on github.com).

Quick installation

Copy/paste the following one line command to download and run the "AM-INSTALLER" script

wget -q https://raw.githubusercontent.com/ivan-hc/AM/main/AM-INSTALLER && chmod a+x ./AM-INSTALLER && ./AM-INSTALLER

...below, the screenshot of what will appear

AM-INSTALLER

Type "1" to install "AM", "2" to install "AppMan". Any other key will abort the installation (please read "Differences between "AM" and "AppMan"" first).

Now you are ready to use this CLI.

For more details on how "AM" and "AppMan" are installed via the "AM-INSTALLER" script, see "Step by step installation", in the next paragraph.


Step by step installation

Do you prefer to install "AM" or "AppMan" without using the "AM-INSTALLER" script?

Also do you want to know in detail how they are installed in the system?

click here!

How to install "AM"

"AM" is ment to be installed at system level to manage apps.

The script "INSTALL" is the one that take care of this.

simplescreenrecorder-2024-08-04_16.58.52.mkv.mp4

Using "Wget"

wget https://raw.githubusercontent.com/ivan-hc/AM/main/INSTALL
chmod a+x ./INSTALL
sudo ./INSTALL

or directly

wget https://raw.githubusercontent.com/ivan-hc/AM/main/INSTALL && chmod a+x ./INSTALL && sudo ./INSTALL

Using "GIT"

git clone https://github.com/ivan-hc/AM.git
cd AM
chmod a+x INSTALL
sudo ./INSTALL

Structure of the "AM" installation

In both cases, the "INSTALL" script will create:

  • the script "/opt/am/APP-MANAGER"
  • the script "/opt/am/remove" (to remove "AM" using the command am -R am)
  • the directory "/opt/am/modules" (containing the .am modules for the non-core options)
  • the symlink "/usr/local/bin/am" for "/opt/am/APP-MANAGER"

all processes will been executed in $HOME/.cache/am, while application lists, keywords to use in bash/zsh completion and other files (for third party repos, betatesting, etcetera...) will be saved and updated in $HOME/.local/share/AM to be shared with "AppMan", if installed or you use "AM" in "AppMan Mode".

NOTE, if you don't feel comfortable having to always use root permissions, the installation method for "AppMan" is totally different. If you are interested, go to the next paragraph, else Back to "Main Index" or jump to "Usage (all the available options)".


How to install "AppMan"

"AppMan" can be used in different places, being it portable.

However, to be easily used its recommended to place it in your local "$PATH", in ~/.local/bin.

Use "AppMan" in "$PATH"

To do so, you must first enable that "$PATH":

  • add export PATH="$PATH:$HOME/.local/bin" in the ~/.bashrc
  • create the directory ~/.local/bin if it is not available

To do all this quickly, simply copy/paste the following command:

mkdir -p ~/.local/bin && echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc && wget https://raw.githubusercontent.com/ivan-hc/AM/main/APP-MANAGER -O ~/.local/bin/appman && chmod a+x ~/.local/bin/appman

Use "AppMan" in "Portable Mode"

"AppMan" can run in any directory you download it, copy/paste the following command to download "APP-MANAGER", rename it to appman and make it executable:

wget https://raw.githubusercontent.com/ivan-hc/AM/main/APP-MANAGER -O appman && chmod a+x ./appman

Structure of the "AppMan" installation

Unlike "AM" which needs to be placed in specific locations, "AppMan" is portable. The modules and directories will be placed in the directory you chose:

  • the script "appman" is wherever you want
  • the directory "/path/to/your/custom/directory/modules" (containing the .am modules for the non-core options)
  • the configuration file "$HOME/.config/appman/appman-config" (the only fixed directory)

all processes will been executed in $HOME/.cache/appman, while application lists, keywords to use in bash/zsh completion and other files (for third party repos, betatesting, etcetera...) will be saved and updated in $HOME/.local/share/AM to be shared with "AM", if installed.


Back to "Main Index"

Uninstall

  • To uninstall "AM" just run the command am -R am
  • To uninstall "AppMan" just remove it and the directory $HOME/.config/appman

Note, before you remove your CLI, use the option -R to remove the apps installed using the following syntax:

am -R {PROGRAM1} {PROGRAM2} {PROGRAM3}...

or

appman -R {PROGRAM1} {PROGRAM2} {PROGRAM3}...

to have a list of the installed programs use the option -f or files (syntax am -f or appman -f).

See also "How to update or remove apps manually".


Back to "Main Index"

USAGE

 am {OPTION}

 am {OPTION} {ARGUMENT}
Click here to see the full list of options

OPTIONS:

about, -a

	-a {PROGRAM}

Description: Shows more info about one or more apps.

apikey

	apikey {Github Token}
	apikey delete

Description: Accede to github APIs using your personal access tokens. The file named "ghapikey.txt" will be saved in ~/.local/share/AM. Use "del" to remove it.

backup, -b

	-b {PROGRAM}

Description: Create a snapshot of the current version of an installed program.

clean, -c

	-c

Removes all the unnecessary files and folders.

config, -C, --config

	-C {PROGRAM}

Description: Set a dedicated $XDG_CONFIG_HOME for one or more AppImages.

downgrade, --rollback

	--rollback {PROGRAM}

Description: Download an older or specific app version.

download, -d

	-d {PROGRAM}
	-d --convert {PROGRAM}

Description: Download one or more installation scripts to your desktop or convert them to local installers for "AppMan" (the latter must be present).

extra, -e

	-e user/project {APPNAME}
	-e user/project {APPNAME} {KEYWORD}

Description: Install AppImages from github.com, outside the database. This allows you to install, update and manage them all like the others. Where "user/project" can be the whole URL to the github repository, give a name to the program so that it can be used from the command line. Optionally, add an "univoque" keyword if multiple AppImages are listed.

files, -f

	-f
	-f --byname
	-f --less

Description: Shows the list of all installed programs, with sizes. By default apps are sorted by size, use "--byname" to sort by name. With the option "--less" it shows only the number of installed apps.

help -h

	-h

Description: Prints this message.

home, -H, --home

	-H {PROGRAM}

Description: Set a dedicated $HOME directory for one or more AppImages.

icons, --icons

            --icons {PROGRAM}
            --icons --all

Description: Allow installed apps to use system icon themes. You can specify the name of the apps to change or use the "--all" flag to change all of them at once. This will remove the icon path from the .desktop file and add the symbolic link of all available icons in the $HOME/.local/share/icons/hicolor/scalable/apps directory.

install, -i

	-i {PROGRAM}
	-i --debug {PROGRAM}
	-i --force-latest {PROGRAM}

Description: Install one or more programs or libraries from the list. With the "--debug" option you can see log messages to debug the script. For more details on "--force-latest", see the dedicated option, below.

install-appimage, -ia

            -ia {PROGRAM}
            -ia --debug {PROGRAM}
            -ia --force-latest {PROGRAM}

Description: Same as "install" (see above) but for AppImages only.

lock

	lock {PROGRAM}

Description: Prevent an application being updated, if it has an"AM-updater" script.

list, -l

	-l
	-l --appimages

Description: Shows the list of all the apps available, or just the AppImages.

newrepo, neodb

	newrepo add {URL}\{PATH}
	newrepo select
	newrepo on\off
	newrepo purge
	newrepo info

Description: Set a new default repo, use "add" to append the path to a local directory or an online URL, then use "select" to use it by default, a message will warn you about the usage of this repo instead of the default one. Use "on"/"off" to enable/disable it. Use "purge" to remove all 3rd party repos. Use "info" to see the source from where installation scripts and lists are taken.

nolibfuse

	nolibfuse {PROGRAM}

Description: Convert old AppImages and get rid of "libfuse2" dependence.

overwrite, -o

	-o {PROGRAM}

Description: Overwrite apps with snapshots saved previously (see "-b").

query, -q

	-q {KEYWORD}
	-q --appimages {KEYWORD}
	-q --pkg {PROGRAM1} {PROGRAM2}

Description: Search for keywords in the list of available applications, add the "--appimages" option to list only the AppImages or add "--pkg" to list multiple programs at once.

remove, -r

	-r {PROGRAM}

Description: Removes one or more apps, requires confirmation.

-R

	-R {PROGRAM}

Description: Removes one or more apps without asking.

sandbox, --sandbox

	sandbox {PROGRAM}

Description: Run an AppImage in a sandbox using Aisap.

sync, -s

	-s

Description: Updates this script to the latest version hosted.

template, -t

	-t {PROGRAM}

Description: Generate a custom installation script.

unlock

	unlock {PROGRAM}

Description: Unlock updates for the selected program (nulls "lock").

update, -u, -U

	-u
	-u --apps
	-u {PROGRAM}

Description: Update everything. Add "--apps" to update oly the apps or write only the apps you want to update by adding their names.

version, -v

	-v

Description: Shows the version.

--devmode-disable

	--devmode-disable

Description: Undo "--devmode-enable" (see below).

--devmode-enable

	--devmode-enable

Description: Use the development branch (at your own risk).

--disable-sandbox

	--disable-sandbox {PROGRAM}

Description: Disable the sandbox for the selected app.

--force-latest

	--force-latest {PROGRAM}

Description: Downgrades an installed app from pre-release to "latest".

--launcher

	--launcher /path/to/${APPIMAGE}

Description: Drag/drop one or more AppImages in the terminal and embed them in the apps menu and customize a command to use from the CLI.

--system

	--system

Description: Switch "AM" back to "AM" from "AppMan Mode" (see "--user").

--user, appman

	--user

Description: Made "AM" run in "AppMan Mode", locally, useful for unprivileged users. This option only works with "AM".



Install "AM"/"AppMan" Back to "Main Index"

Guides and tutorials

This section is committed to giving small demonstrations of each available option, with videos:


Install applications

The option -i or install is the one responsible of the installation of apps or libraries.

Install, normal behaviour

This is the normal syntax:

am -i $PROGRAM

or

appman -i $PROGRAM

in this video I'll install AnyDesk:

install-normally-2024-08-15_19.36.24.mkv.mp4

Install, debug an installation script

The "install.am" module contains some patches to disable long messages. You can see them with the suboption --debug:

am -i --debug $PROGRAM

or

appman -i --debug $PROGRAM

let test again the installation of AnyDesk using the --debug flag:

install-with-debug-messages-2024-08-15_19.36.51.mkv.mp4

Install the "latest" stable release instead of the latest "unstable"

By default, many installation scripts for apps hosted on github will point to the more recent generic release instead of "latest", which is normally used to indicate that the build is "stable". This is because upstream developers do not always guarantee a certain packaging format in "latest", sometimes they may only publish packages for Windows or macOS, so pointing to "latest" would not guarantee that any package for Linux will be installed.

On the other hand, if you know that the upstream developer will always guarantee a Linux package in "latest" and "AM" instead points to a potentially unstable development version (Alpha, Beta, RC...), this is the syntax to adopt:

am -i --force-latest $PROGRAM

or

appman -i --force-latest $PROGRAM

in this video I'll install "SqliteBrowser" using the --force-latest flag:

force-latest-release-if.exists-2024-08-15_19.39.08.mkv.mp4

See also "The script points to "releases" instead of downloading the latest stable".


Back to "Guides and tutorials" Back to "Main Index"


Install only AppImages

All suboptions for -i/install listed above can be used to install AppImages only, it is enough to use the option -ia/install-appimage:

am -ia {PROGRAM}
am -ia --debug {PROGRAM}
am -ia --force-latest {PROGRAM}

or

appman -ia {PROGRAM}
appman -ia --debug {PROGRAM}
appman -ia --force-latest {PROGRAM}

In this example, I'll run the script brave-appimage but running brave, that instead is the original upstream package:

install-appimage-2024-08-29_17.49.07.mkv.mp4

in the video above I first launch a "query" with the -q option to show you the difference between brave and brave-appimage, and then -q --appimages to show you only the appimages from the list. More details at "List and query all the applications available on the database".


Back to "Guides and tutorials" Back to "Main Index"


Install AppImages not listed in this database but available in other github repos

From version 7.2 its possible to install AppImages not listed in this database, thanks to the option -e or extra.

You need to add the URL to the github repo before the name you want to give to the AppImage (for command line usage, for example).

Optionally, you can add a "keyword" if more AppImages are listed in the same repo.

Usage:

am -e $USER/$PROJECT $PROGRAM
am -e $USER/$PROJECT $PROGRAM $KEYWORD

or

appman -e $USER/$PROJECT $PROGRAM
appman -e $USER/$PROJECT $PROGRAM $KEYWORD

You can give whatever name you want to the apps (as long as they does not overlap with commands already existing on your system, be careful).

In this video I'll install AnyDesk as "remote-desktop-client":

simplescreenrecorder-2024-07-12_01.38.51.mkv.mp4

In this other example, I'll install an obsolete version of WINE AppImage, from a repo that lists more versions of the same app:

  1. the first attempt is without a keyword, so that the script picks the first AppImage in the list (for Debian Buster)
  2. in the second attempt I'll use the keyword "arch" to pick the Arch-based AppImage
simplescreenrecorder-2024-07-12_02.00.18.mkv.mp4

As you can see, there are all the files needed by any app listed in this database, also if an installation script for them does not exists.

Apps installed this way will enjoy the same benefits as those that can already be installed from the database with the "-i" or "install" option mentioned above, including updates and sandboxing.


Back to "Guides and tutorials" Back to "Main Index"


List the installed applications

Option -f or files, it shows the installed apps, the version, the size and the type of application:

list-installed-apps.mp4

By default apps are sorted by size, use "--byname" to sort by name. With the option "--less" it shows only the number of installed apps.

am -f
am -f --byname
am -f --less

or

appman -f
appman -f --byname
appman -f --less

Back to "Guides and tutorials" Back to "Main Index"


List and query all the applications available on the database

Option -l or list shows the whole list of apps available in this repository.

This option uses less to show the list, so to exit its enough to press "Q".

If the option -l is followed by --appimages, you will be able to see only the available AppImages.

list-2024-08-13_02.35.34.mkv.mp4

Option -q or query shows search results from the list above.

If followed by --appimages, the search results will be only for the available AppImages.

If followed by --pkg, all keywords will be listed also if not on the same line. This is good if you are looking for multiple packages.

query-2024-08-13_02.36.07.mkv.mp4

Back to "Guides and tutorials" Back to "Main Index"


Update all

Option -u or update updates all the installed apps and keeps "AM"/"AppMan" in sync with the latest version and all latest bug fixes:

update-and-sync.mp4

See "How to update all programs, for real".


Back to "Guides and tutorials" Back to "Main Index"


Backup and restore installed apps using snapshots

Backup

Option -b or backup creates a copy of the installed app into a dedicated directory under $HOME/.am-snapshots.

  • by default, each snapshot is named with the date and time you have done the backup, just leave blank and press ENTER;
  • if you press "1", the snapshot version will be used as the name;
  • finally, you can simply write the name to give to the snapshot (spaces will be replaced with a "_").
backup-2024-10-16_19.02.42.mkv.mp4

To restore the application to a previous version, copy/paste the name of the snapshot when the -o option will prompt it.

Restore

Option -o or overwrite lists all the snapshots you have created with the option -o (see above), and allows you to overwrite the new one:

override-2024-10-16_19.03.15.mkv.mp4

See also "How to use multiple versions of the same application".


Back to "Guides and tutorials" Back to "Main Index"


Remove one or more applications

Option -R removes the selected apps without asking (to have a prompt, use -r or remove):

remove.mp4

Back to "Guides and tutorials" Back to "Main Index"


Convert Type2 AppImages requiring libfuse2 to New Generation AppImages

Option nolibfuse converts old Type2 AppImages asking for "libfuse2" into new generation AppImages:

am nolibfuse $PROGRAM

or

appman nolibfuse $PROGRAM

in this example, I'll convert Libreoffice and Kdenlive:

get-rid-of-libfuse2-2024-08-18_22.09.08.mkv.mp4

As you can see, the file sizes are also smaller than before.

This process only works for old AppImages that still depend on "libfuse2", other files will be ignored.

The original AppImage will be extracted using the --appimage-extract option, and then repackaged using appimagetool from https://github.com/AppImage/appimagetool

Updating converted AppImages

The nolibfuse option adds the following lines at the end of the AM-updater script

echo y | am nolibfuse $APP
notify-send "$APP has been converted too! "

or

echo y | appman nolibfuse $APP
notify-send "$APP has been converted too! "

so if an update happens through "comparison" of versions, the converted AppImage will be replaced by the upstream version and then the nolibfuse option will automatically start the conversion (prolonging the update time, depending on the size of the AppImage). In this example, I update all the apps, including the original Avidemux, that is an old Type2 AppImage:

update-converted-appimages-2024-08-18_21.09.53.mkv.mp4

Instead, if the installed AppImage can be updated via zsync, this may no longer be updatable, anyway a solution may be the use of appimageupdatetool, at https://github.com/AppImageCommunity/AppImageUpdate .

The nolibfuse option has been improved since version 7.8, so everyone can say goodbye to the old "libfuse2" dependence.

Anyway, I suggest anyone to contact the developers to update the packaging method of their AppImage! This is also a way to keep open source projects alive: your participation through feedback to the upstream.

The nolibfuse option is not intended to replace the work of the owners of these AppImage packages, but to encourage the use of AppImage packages on systems that do not have "libfuse2", a library that is now obsolete and in fact no longer available out-of-the-box by default in many distributions, first and foremost Ubuntu and Fedora.


Back to "Guides and tutorials" Back to "Main Index"


Integrate local AppImages into the menu by dragging and dropping them

If you are a user who is used to dragging your local AppImages scattered around the system and if you are a user who likes clutter and wants to place their packages in different places... this option is for you.

The option --launcher allows you to drag and drop a local AppImage to create a launcher to place in the menu, like any other classic AppImage helper would... but in SHELL.

This option also allows you to create a symbolic link with the name you prefer, in "~/.local/bin". Leave blank to let the option create a shell script that calls your AppImage, with extension ".appimage", lowercased.

How to create a launcher for a local AppImage
am --launcher /path/to/File.AppImage

or

appman --launcher /path/to/File.AppImage

In this video I'll integrade Brave AppImage, the first time without a name, and the second time by choosing "brave" (NOTE, the ".appimage" in $PATH is a little shell script that calls the AppImage, not the whole AppImage):

integrate-local-appimages.mp4

Now the binaries are "two", keep read to see how to remove them using "AM" and "AppMan".

How to remove the orphan launchers

In case you move your AppImages somewhere else or remove them, use the following otion -c or clean to get rid of all the orphaned launchers and dead symlinks and scripts you created earlier:

am -c

or

appman -c

In this video I'll remove the AppImage, and then I'll remove the launchers and items in $PATH created in the previous video (see above):

remove-orphan-launchers.mp4
AppImages from external media

Another peculiarity concerns the use of the -c option on launchers created on AppImage packages placed on removable devices:

  • if in the .desktop file belongs to an AppImage placed in /mnt or /media and none of the references are mounted, the option -c will not be able to remove it until you mount the exact device where it was placed in the moment you have created the launcher;
  • if you mount that same device and the AppImage is not where it was when you created the launcher, it will be removed.

This is very useful if you have large AppImage packages that you necessarily need to place in a different partition.


Back to "Guides and tutorials" Back to "Main Index"


Sandbox an AppImage

Since version 6.12, "AM"/"AppMan" uses Bubblewrap for sandboxing AppImage packages, thanks to "Aisap", a highly intuitive and configurable command line solution.

The option "--sandbox", which since version 5.3 was using Firejail, has taken on a completely different appearance and usability, thanks to the intense work of @Samueru-sama, who managed to extend and enhance "Aisap", making it extremely easy to use in our project, to the point of making us forget that we are using a command line utility.

Bubblewrap is an highly used sanboxing solution, used in multiple projects for GNU/Linux, including Flatpak.

In this sense, "Aisap" may be considered a reference point for the future of AppImages sandboxing!

How to enable a sandbox

This method works as follows:

am --sandbox $APP

or

appman --sandbox $APP

The "aisap" package installed is required, whether it is available system-wide ("AM") or locally ("AppMan"), the important thing is that the "aisap" command is in $PATH. If it is not present, "AM"/"AppMan" will ask you if it can proceed with the installation before continuing.

We will first compile the Aisap script in a non-privileged, easy-to-access directory, before being placed in $PATH (see step 2, below).

  1. Once started, you will be asked whether to enable the sandbox (default "Y") or not (type "N"):
  • the main XDG directories (Pictures, Videos, Documents...) will be listed, answer whether to authorize access (type "Y") or not ("N", default);
  • at the end, choose whether to specify some directories to access (default "N"), and if "Yes", write the path.
  1. Now that the script is complete, it should be placed in $PATH. "AM" users will need to authorize writing to /usr/local/bin by entering their password. "AppMan" users do not have these problems;
  2. To allow Aipman take care of the AppImage, the latter be set to "not executable" and the related AM-updater will also have its chmod command set from a+x to a-x.
  3. Now your AppImage is in a sandbox!

NOTE, the default location for the sandboxed homes is at $HOME/.local/am-sandboxes, but that location can be changed by setting the $SANDBOXDIR environemt variable.

How to disable a sandbox

To remove the sandbox just run the command of the AppImage with the flag "--disable-sandbox", like this:

$APP --disable-sandbox

Sandboxing example

In the video below we will use "Baobab" (GTK3 version), a disk space analyzer, available in the database as "baobab-gtk3".

Among the XDG directories we will authorize "Images" (Pictures) and "Videos" (Videos), while manually we will authorize "Public". The test will be carried out in normal mode, then in sandbox and again without sandbox:

simplescreenrecorder-2024-06-21_17.25.05.mkv.mp4

About Aisap sandboxing

For more information about "Aisap", visit https://github.com/mgord9518/aisap

Available profiles are listed at https://github.com/mgord9518/aisap/tree/main/profiles

To learn more about permissions, see https://github.com/mgord9518/aisap/tree/main/permissions

EXTRA: The behavior of this option can be tested in a completely standalone way by consulting the repository of its creator, at Samueru-sama/aisap-am


Back to "Guides and tutorials" Back to "Main Index"


How to enable bash completion

From version 8, BASH/ZSH completion is enabled in "AM" and "AppMan" by default, and from version 8.1.1 a file in $HOME/.local/share/bash-completion/completions named "am" or "appman" (and no more $HOME/.bash_completion) will be created to read arguments from the related "list" of arguments, or other lists, to made it more extensible.

Before version 8, in "AM" were created a "/etc/bash_completion.d/am-completion.sh" using a dedicated option.

In case you still have it, run sudo rm -f /etc/bash_completion.d/am-completion.sh to remove it. Its no more necessary.


Back to "Guides and tutorials" Back to "Main Index"


How to update or remove apps manually

Inside each installed applications directory, there are two scripts called "AM-updater" and "remove", and their purpose is indicated in their name:

  • To update an app manually, run the AM-updater script.
  • To remove an application instead, run the "remove" script (with "sudo" or "doas" if you are an "AM" user).

Downgrade an installed app to a previous version

Use the --rollback option or downgrade in this way:

am --rollback ${PROGRAM}

This only works with the apps hosted on Github.

simplescreenrecorder-2024-06-11_19.39.19.mkv.mp4

Back to "Guides and tutorials" Back to "Main Index"


How to use multiple versions of the same application

Before you begin, you just need to know how to use snapshots via the -b and -o options (see "Backup and restore installed apps using snapshots") and how to downgrade applications where possible (see "Downgrade an installed app to a previous version").

You can use the -b option for snapshots, and where applicable, you can use the downgrade or --rollback option to install older versions of a program. This way, whenever you want to use a different version of the same program, you can use -o, using the snapshot you prefer.

For example, suppose you want to alternate "Kdenlive 24.08.1" (at the time of writing, it is the latest release available) with "Kdenlive 23.08" which still supports QT5, here's how to do it:

  1. do a backup with am -b kdenlive, press y and press 1, this will create the snapshot "24.08.1";
  2. run the command am downgrade kdenlive and select the version 23.08 from the list;
  3. run a backup again with am -b kdenlive, press y and press 1 to create the snapshot "23.08";
  4. from now on, to switch between them, just use am -o kdenlive and select between "24.08.1" and "23.08", from the list.

You can create as many snapshots as you want and switch them this way according to your needs!

And if it is an AppImage, you can dedicate its own .home and .config directories to it (option -H and -C, respectively, in uppercase).


Back to "Guides and tutorials" Back to "Main Index"


Create and test your own installation script

Option -t or template allows you to create an "AM" compatible installation script using a "templates" that can be used by both "AM" and "AppMan". In fact, all AppMan does is take the installation scripts from this database and patch them to make them compatible with a rootless installation.

The syntax to follow is this

am -t $PROGRAM

or

appman -t $PROGRAM

The available options are as follows:

  1. Create a script for an AppImage package
  2. Build an AppImage on the fly using appimagetool and pkg2appimage
  3. Download and unpack a generic archive (ZIP, TAR...)
  4. Create a custom Firefox profile

To learn more about a specific option, use the index below

Otherwise, go directly to the last paragraphs, which are

Istantanea_2024-06-17_21-35-26 png

Option Zero: "AppImages"

The easiest script to create is certainly the one relating to AppImages, the "Zero" option.

  1. Enter the URL of the site
    • if the AppImage is hosted on github, it will quickly detect the URL
    • if the AppImage is not hosted on github,it will ask you to add a description of the app
  2. Detecting the correct URL
    • if the app is hosted on github, it will ask you if you want to add/remove keywords to use in grep, to detect the correct URL, else press ENTER
    • if the app is not hosted on github, add a one-line command to detect the latest version of the app (advanced)

In this video I'll create 2 installation scripts:

  • the first one is for "gimp", detected as first reference, no extra prompts
  • the second one is for "baobab-gtk3", hosted on a repository with multiple packages, so I have to add a keyword ("baobab"), univoque for the URL I'm interested in
simplescreenrecorder-2024-06-18_01.27.23.mkv.mp4

Option One: "build AppImages on-the-fly"

This was one of the very first approaches used to create this project. Before I started building AppImage packages myself, they were first compiled just like using any AUR-helper.

From version 7.1, the installation script for the AppImages is used, with the only difference that it points only to the version, while a second script will be downloaded, published separately, at github.com/ivan-hc/AM/tree/main/appimage-bulder-scripts, which will have the task of assembling the AppImage in the directory on the fly "tmp", during the installation process. When the second script has created the .AppImage file, the first script will continue the installation treating the created AppImage as a ready-made one downloaded from the internet.

In this video we see how "calibre" is installed (note that a "calibre.sh" file is downloaded during the process):

calibre-installation-2024-07-10_01.46.59.mkv.mp4

In this video, I run the aforementioned "calibre.sh" script in a separate directory, in a completely standalone way:

calibre-standalone-2024-07-10_01.45.04.mkv.mp4

Two different operations (assembly and installation) require two different scripts.

Fun fact, up until version 7, this option included a unique template that installed and assembled the AppImage on the fly (see this video). This method has been replaced as it was too pretentious for a process, assembly, which may instead require many more steps, too many to be included in both an installation script and an update script (AM-updater).

Option Two: "Archives and other programs"

Option two is very similar to option zero. What changes is the number of questions, which allow you to customize both the application's .desktop file and the way a program should be extracted.

This script also supports extraction of *7z, tar and *zip files, if those archives are downloaded instead of a standalone binary.

By default, the install script does not have a launcher and icon. To create one, press "Y", otherwise, press "N" or leave it blank. This is useful if you want to load scripts or tools that can be used from the command line.

This option may be used also for AppImages, if you need to customize the launcher.

Tu add an icon, you need an URL to that, but if you don't have one, just leave blank. The script will download an icon from portable-linux-apps.github.io if it is hosted there, when running the installation script.

In this example, I'll use OBS Studio AppImage.

simplescreenrecorder-2024-06-21_06.19.31.mkv.mp4

Option Three: "Firefox profiles"

Option 3 creates a launcher that opens Firefox in a custom profile and on a specific page, such as in a WebApp. I created this option to counterbalance the amount of Electron/Chrome-based applications (and because I'm a firm Firefox's supporter).

How an installation script works

The structure of an installation script is designed for a system-wide installation, with "AM", since it is intended to be hosted in the database. But every path indicated within it is written so that "AppMan" can patch the essential parts, to hijack the installation at a local level and without root privileges:

  1. In the first step, the variables are indicated, such as the name of the application and a reference to the source of the app (mostly used in --rollback or downgrade);
  2. Create the directory of the application;
  3. The first file to be created is "remove", to quickly remove app's pieces in case of errors;
  4. Create the "tmp" directory, in which the app will be downloaded and, in the case of archives, extracted;
  5. Most scripts contain a "$version" variable, a command to intercept the URL to download the app. If the URL is linear and without univoque versions, "$version" can be used to detect a version number. Then save the value into a file "version" (this is important for the updates, see point 7);
  6. Downloading the application (and extract it in case of archive);
  7. Create the "AM-updater" file, the script used to update the app. It resumes points 4, 5 and 6, with the difference that the "$version" variable we have saved at point 5 is compared with a new value, hosted at the app's source;
  8. Creation/extract/download launcher and icon, the methods change depending on the type of application. For AppImages they are extracted from the package.

How to test an installation script

To install and test your script, use the command

am -i /path/to/your-script

or

appman -i /path/to/your-script

To debug the installation, add the option --debug, like this

am -i --debug /path/to/your-script

or

appman -i --debug /path/to/your-script

Third-party databases for applications (NeoDB)

Use the option newrepo or neodb to add new repositories to use instead of this one. This works for both online and offline repositories.

Set a new default repo, use "add" to append the path to a local directory or an online URL:

am newrepo add {URL}\{PATH}

or

appman newrepo add {URL}\{PATH}

then use "select" to use it by default:

am newrepo select

or

appman newrepo select

a message will warn you about the usage of this repo instead of the default one.

In the screenshot below, I'm adding an offline directory and an online "RAW" fork of "AM" Istantanea_2024-08-25_20-10-47

Use "on"/"off" to enable/disable it:

am newrepo on
am newrepo off

or

appman newrepo on
appman newrepo off

Use "purge" to remove all 3rd party repos:

am newrepo purge

or

appman newrepo purge

Use "info" to see the source from where installation scripts and lists are taken.

am newrepo info

or

appman newrepo info

if no third-party repo is in use, you will see the default URLs from this repo.

Istantanea_2024-08-25_20-07-54 png


Install "AM"/"AppMan" Back to "Guides and tutorials" Back to "Main Index"

Instructions for Linux Distro Maintainers

You can package "AM" for Debian, Fedora, Arch Linux, Gentoo and many more GNU/Linux distros using the following configuration:

/usr/bin/am
/usr/lib/am/modules

where "/usr/bin/am" is the script "APP-MANAGER" and "/usr/lib/am/modules" is the directory "modules" with all its content.

Applications will continue to be installed in /opt, as always.

What changes from the normal "AM" installation is the update of the CLI and modules, which will instead be completely managed by the package manager in use (APT, DNF, PacMan/YAY...).

As for "AppMan", there is no packaging, as it is a standalone or self-updating script, and needs to be in a read-write directory without root privileges. However, it is possible to use "AM" in "Appman Mode".


Install "AM"/"AppMan" Back to "Guides and tutorials" Back to "Main Index"

Troubleshooting


An application does not work, is old and unsupported

Use the -a option and go to the developer's site to report the problem. The task of "AM" is solely to install / remove / update the applications managed by it. Problems related to the failure of an installed program or any related bugs are attributable solely to its developers.


Cannot download or update an application

There can be many reasons:

  • check your internet connection;
  • if the app is hosted on github.com, you have probably exceeded the hourly limit of API calls;
  • the referring link may have been changed, try the --rollback option or downgrade;
  • the reference site has changed, report any changes at https://github.com/ivan-hc/AM/issues

Back to "Troubleshooting" Back to "Main Index"

Cannot mount and run AppImages

If by running it in the terminal you get an error message about "FUSE" or "libfuse"/"libfuse2" missing, take a look at the official documentation:

https://docs.appimage.org/user-guide/troubleshooting/fuse.html

If your distro does not provide libfuse2, you can install it using the command:

am -i libfuse2

or

appman -i libfuse2

NOTE, in AppMan you still need to use your password (sudo or doas) to install the library at system level, in /usr/local/lib

Alternatively you can use the "nolibfuse" option to "try" to convert old Type2 AppImages to a new generation one, so as not to depend on libfuse2. In most cases it works, but sometimes it can give errors, depending on how the package was manufactured.

However, I suggest contacting the upstream developers to convince them to upgrade their packages.


Back to "Troubleshooting" Back to "Main Index"

Failed to open squashfs image

When installing a script for an AppImage, you may see an error like this

This doesn't look like a squashfs image.
Failed to open squashfs image
sed: can't read ./appname.desktop: No such file or directory
mv: cannot stat './appname.desktop': No such file or directory

Basically, the installation process encounters errors while trying to extract the .deskto launcher and icon from the AppImage, and most likely, the entire application execution via terminal may fail, especially if installed locally, via AppMan.

Here's what you need to check:

  • the installation status via your distribution repositories of the "squashfs-tools" package;
  • the installation status of FUSE (whether it is version 2, 3 or higher);
  • whether AppImageLauncher is installed or present on the system, if so remove it.

In the case of AppImageLauncher, as I write (today September 20, 2024), the repository has not been updated for a couple of years and the runtime used in the AppImages has changed. AppImageLauncher uses mechanisms to identify the AppImages present in the system, asking you to integrate them if you launch one. It acts a bit like a system daemon in effect, and could cause problems while you tend to manage the AppImages with different tools, and therefore even the execution via terminal can be problematic.

Remove AppImageLauncher and its files, then reboot the system (see also issues/955 and issues/107).


Back to "Troubleshooting" Back to "Main Index"

Spyware, malware and dangerous software

Before installing any application, try to know where it comes from first. This program provides you with two basic options for this purpose:

  • Option -a or about (medium safety), allows you to read a short description and know the links from the pages of the site https://portable-linux-apps.github.io locally, however these links may be inaccurate due to continuous updates of the initial scripts (you can provide additional info yourself by modifying the pages of the site, here, it is also open source);
  • Option -d or download (absolute safety), this allows you to get the installation script directly on your desktop, so you can read the mechanisms and how it performs the downloads from the sources (in most cases there is a header for each step that explains what the listed commands do).

“AM” and AppMan are just tools to easily install all listed programs, but what you choose to install is your complete responsibility. Use at your own risk!


Back to "Troubleshooting" Back to "Main Index"

Stop AppImage prompt to create its own launcher, desktop integration and doubled launchers

Some developers insist on creating Appimages that create their own launcher on first launch (like WALC and OpenShot). If the official solution proposed here doesn't work, you have two options to escape this trouble: "-H" and "--sandbox".

1. Option "-H" or "home": create a .home directory for the AppImage

Use the option -H, then launch the app and accept the request. Dotfiles and launcher will be saved in the $APP.home near the AppImage:

am -H $APP
$APP

or

appman -H $APP
$APP

you can also use the AppImage's builtin option --appimage-portable-home from the terminal:

$APP --appimage-portable-home

This method works in the 99% of cases.

2. Option "--sandbox": run the AppImage into a Aisap/bubblewrap sandbox

Use the option --sandbox, then launch the app and accept the request. Dotfiles and launcher will be saved in the dedicated sandbox:

am ---sandbox $APP
$APP

or

appman --sandbox $APP
$APP

This is the best method, since you decide wheter to allow the use of user's directories or not.

For more details, see "Sandbox an AppImage".


Back to "Troubleshooting" Back to "Main Index"

The script points to "releases" instead of downloading the latest stable

This is a choice I made as many developers have abandoned support for AppImage or GNU/Linux in general. My aim here is to introduce you to other developers' applications, then it's up to you to contact them, support them, help improve the software through forks and pull requests, opening issues and encouraging developers to keep the software in the format you prefer.

In case you are sure that the upstream developer will maintain the package for each stable release, you can fix this in several ways:

Method 1: Direct installation by combining -i and --force-latest options

am -i --force-latest $PROGRAM

Method 2: "Downgrade" the installed app to "latest"

Use the option --force-latest to patch the AM-updater and perform the "update"/"downgrade":

am --force-latest $PROGRAM

or do it manually:

sed -i 's#releases -O -#releases/latest -O -#g' /opt/$PROGRAM/AM-updater
am -u $PROGRAM

See also "Install the "latest" stable release instead of the latest "unstable"".


Back to "Troubleshooting" Back to "Main Index"

Ubuntu mess

As the author of this article states, "Ubuntu Desktop firmly places security at the forefront, and adheres to the principles of security by default". Bullsh*t!

User namespaces are a feature of the kernel. It's a feature which is supported by the Linux kernel. When a vulnerability is found, it's given a CVE and the code is fixed appropriately. If the kernel developers wanted to disable this feature by default, or restrict it, they could do so themselves.

Introducing namespace restrictions via AppArmor is an additional security layer, but not required, since we already have more flexible sandboxing systems in the Linux world, in particular "Bubblewrap", used mainly by Flatpak and othe projects, including this and my other one, "Archimage".

Canonical has only one interest in applying all these restrictions to Ubuntu: to enforce the use of Snap!

It's not that the Snapcraft database is that secure, it's not uncommon for some malicious user to have introduced malicious code into distributed applications. The reason they disable namespaces is due to some older privilege escalation bugs, but the problem with that is that it doesn't matter on desktop usage, any malware can just wait for you to enter your sudo password when updating, not to mention that it can already do everything the regular user can do, including deleting everything owned by the user.

But as expected, Ubuntu is a distribution that knows how to attract criticism and disapproval. I say this as a former user (I started with Ubuntu 9.04): Canonical doesn't give a damn about Ubuntu users!

There are two solutions to this problem, one simple and one a little more complex:

  1. The simple solution is to stop using Ubuntu, completely! Change distribution!
  2. The slightly more complex solution is to disable restrictions, via the command line. If you decide to adopt this one, see below.

How to disable Apparmor restrictions

If you chose number two and you feel happy with Ubuntu, follow these steps (as suggested here):

  1. run the following command to disable AppArmor restrictions (the file name is relative)
echo 'kernel.apparmor_restrict_unprivileged_userns = 0' | sudo tee /etc/sysctl.d/20-apparmor-mint.conf
  1. Reboot.

Back to "Troubleshooting" Back to "Main Index"

Wrong download link

The reasons may be two:


Back to "Troubleshooting" Back to "Main Index"

Related projects

External tools and forks used in this project

  • aisap, sandboxing solutions for AppImages
  • appimagetool, get rid of libfuse2 from your AppImages
  • pkg2appimage, create AppImages on the fly from existing .deb packages
  • repology, the encyclopedia of all software versions

My other projects

  • AppImaGen, easily create AppImages from Ubuntu PPAs or Debian using pkg2appimage and appimagetool;
  • ArchImage, create AppImages for all distributions using Arch Linux packages. Powered by JuNest;
  • Firefox for Linux scripts, easily install the official releases of Firefox for Linux;
  • My AppImage packages the complete list of packages managed by me and available in this database;
  • Snap2AppImage, try to convert Snap packages to AppImages.

You can support me and my work on ko-fi.com and PayPal.me. Thank you!

© 2020-present Ivan Alessandro Sala aka 'Ivan-HC' - I'm here just for fun!


ko-fi.com PayPal.me Install "AM"/"AppMan" "Main Index"

About

AppImage package manager to install, update and manage ALL of them, system-wide or locally, thanks to its ever-growing AUR-inspired database listing 2000+ portable apps and programs for GNU/Linux. The first, real centralized repository to manage your AppImages with the ease of APT and the power of PacMan.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Shell 100.0%