"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.
Differences between "AM" and "AppMan"
- Ownership
- About "sudo" usage
- How apps are installed
- How to use "AM" in non-privileged mode, like "AppMan"
What programs can be installed
How to update all programs, for real
Usage (all the available options)
- Install applications
- List the installed applications
- List and query all the applications available on the database
- Update all
- Backup and restore installed apps using snapshots
- Remove one or more applications
- Convert Type2 AppImages requiring libfuse2 to Type3 AppImages
- Integrate local AppImages into the menu by dragging and dropping them
- How to use "AM" in non-privileged mode, like "AppMan"
- Sandbox an AppImage
- How to enable bash completion
- How to update or remove apps manually
- Downgrade an installed app to a previous version
- Create and test your own installation script
- Third-party databases for applications (NeoDB)
- An application does not work, is old and unsupported
- Cannot download or update an application
- Cannot mount and run AppImages
- Spyware, malware and dangerous software
- Stop AppImage prompt to create its own launcher, desktop integration and doubled launchers
- The script points to "releases" instead of downloading the latest stable
- Wrong download link
"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) 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/binto be used in $PATH, to be managed from other tools (see below).
Both can be updated using "Topgrade".
- "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.
- "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, or enable/disable bash completion.
All options cannot be executed with "sudo".
- "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/share/applications/AM-$PROGRAM.desktop
If the distro is immutable or have read-only mount points instead, the path of the launcher (the last line above) will change like this:
/usr/local/share/applications/AM-$PROGRAM.desktop
NOTE, all installation scripts created or updated after June 28, 2024 will install launchers in /usr/local/share/applications with the "-AM.desktop" extension instead of the "AM-" suffix, like this:
/usr/local/share/applications/$PROGRAM-AM.desktop
- "AppMan" is more flexible, since it asks you where to install the apps in your $HOME directory. For example, suppose you want install everything in "Applicazioni" (the italian of "applications"), 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/AM-$PROGRAM.desktop
NOTE, all installation scripts created or updated after June 28, 2024 will install launchers with the "-AM.desktop" extension instead of the "AM-" suffix, like this:
~/.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, as long as it is in your $HOME.
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" |
|---|
"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.
- 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.
- 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.
-
FIREFOX PROFILES to run as webapps, the ones with suffix "ffwa-" in the apps list.
-
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" |
|---|
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.
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
- To update only the programs, use
am -u --apps/appman -u --apps - To update just one program, use
am -u $PROGRAM/appman -u $PROGRAM - To update all the programs and "AM"/"AppMan" itself, just run the command
am -u/appman -u - To update only "AM"/"AppMan" and the modules use the option
-sinstead,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".
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" |
|---|
This section explains how to install "AM" or "AppMan".
If you don't know the difference, please read "Differences between "AM" and "AppMan"" first.
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; - "
sed", to edit/adapt installed files; - "
wget" to download all programs and update "AM"/"AppMan" itself.
- "
sudo", required by "AM" to install/remove programs, sandbox AppImages and enable/disable bash-completion.
NOTE: use "AppMan" for non privileged use or if you prefer to gain administration privileges using alternative commands such as doas or similar.
The following are 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; - "
zsync", about 10% of AppImages depend on this to be updated.
"AM" is ment to be installed at system level to manage apps.
The script "INSTALL" is the one that take care of this.
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
git clone https://github.com/ivan-hc/AM.git
cd AM
chmod a+x INSTALL
sudo ./INSTALL
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/.cache" (where all processes will been executed)
- 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"
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)".
"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.
To do so, you must first enable that "$PATH":
- add
export PATH=$PATH:$(xdg-user-dir USER)/.local/binin the~/.bashrc - create the directory
~/.local/binif it is not available
To do all this quickly, simply copy/paste the following command:
mkdir -p ~/.local/bin && echo 'export PATH=$PATH:$(xdg-user-dir USER)/.local/bin' >> ~/.bashrc && wget https://raw.githubusercontent.com/ivan-hc/AM/main/APP-MANAGER -O appman && chmod a+x ./appman && mv ./appman ~/.local/bin/appman
"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
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 "$HOME/path/to/your/custom/directory/.cache" (where all processes will been executed)
- the directory "$HOME/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)
| Back to "Main Index" |
|---|
- 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" |
|---|
am {OPTION}
am {OPTION} {ARGUMENT}
Click here to see the full list of options
(standard, for both "AM" and "APPMAN")
-a, about
SYNOPSIS:
-a {PROGRAM}
DESCRIPTION: Shows more info about one or more apps, all the pages are downloaded from https://portable-linux-apps.github.io
-b, backup
SYNOPSIS:
-b {PROGRAM}
DESCRIPTION: Save the current version of one or more apps, each snapshot is stored into a dedicated directory, under $HOME/.am-snapshots/$PROGRAM
To restore the snapshots see the "-o" option.
-c, clean
SYNOPSIS:
-c
DESCRIPTION: Removes all the unnecessary files and folders.
-d, download
SYNOPSIS:
-d {PROGRAM}
-d --convert {PROGRAM}
DESCRIPTION: Download one or more installation scripts to your desktop. With the option "--convert" its converted to a standalone local installer, but AM requires AppMan to be installed to add custom directory settings.
-f, files
SYNOPSIS:
-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.
-h, help
SYNOPSIS:
-h
DESCRIPTION: Prints this message.
-H, --home
SYNOPSIS:
-H {PROGRAM}
DESCRIPTION: Set a dedicated $HOME directory for one or more AppImages.
-i, install
SYNOPSIS:
-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.
-l, list
SYNOPSIS:
-l
DESCRIPTION: Shows the list of all the apps available in the repository.
-o, overwrite
SYNOPSIS:
-o {PROGRAM}
DESCRIPTION: Overwrite the existing version of the app with a snapshot saved previously (see the option "-b", above).
-q, query
SYNOPSIS:
-q {KEYWORD}
-q --pkg {PROGRAM1} {PROGRAM2}
DESCRIPTION: Can be used to search for keywords and terms in the list of available applications packages to display matches. This can be useful if you are looking for applications having a specific feature. Add the suboption "--pkg" to search only the names of one or more apps.
-r, remove
SYNOPSIS:
-r {PROGRAM}
DESCRIPTION: Removes one or more apps, requires confirmation.
-R
SYNOPSIS:
-R {PROGRAM}
DESCRIPTION: Removes one or more apps without asking.
-s, sync
SYNOPSIS:
-s
DESCRIPTION: Updates this script to the latest version hosted.
-t, template
SYNOPSIS:
-t {PROGRAM}
DESCRIPTION: This option allows you to generate a custom script from a list of different templates that may be vary according to the kind of app you want to upload to the "AM" repo, and the source where it is available. You can install it using the am test /path/to/your-script command.
-u, -U, update
SYNOPSIS:
-u
-u apps
-u {PROGRAM}
DESCRIPTION: Update all the apps (and "am" itself) or just one. If you add the "--apps" suboption you only update apps.
-v, version
SYNOPSIS:
-v
DESCRIPTION: Shows the version.
--disable-completion
SYNOPSIS:
--disable-completion
DESCRIPTION: Disable bash-completion.
--disable-sandbox
SYNOPSIS:
--disable-sandbox {PROGRAM}
DESCRIPTION: Disable the sandbox for the selected app.
--enable-completion
SYNOPSIS:
--enable-completion
DESCRIPTION: Enable bash-completion to complete a keyword with the "TAB" key, using the names of all installable applications available.
--force-latest
SYNOPSIS:
--force-latest {PROGRAM}
-i --force-latest {PROGRAM}
DESCRIPTION: Downgrades an installed app from pre-release to "latest". This can be used with "-i" to force the installation of apps from "latest". Many scripts point to "releases" to find the latest build for GNU/Linux if the developer has not uploaded one in "latest".
--launcher
SYNOPSIS:
--launcher /path/to/${APPIMAGE}
DESCRIPTION: Embed one or more local AppImages in the applications menu. I suggest dragging the files into the terminal to get the desired effect. Launchers are located in ~/.local/share/applications/AppImages by default.
--rollback, downgrade
SYNOPSIS:
--rollback {PROGRAM}
DESCRIPTION: Download an older or specific version of the software you are interested in (only works with Github).
--sandbox
SYNOPSIS:
--sandbox {PROGRAM}
DESCRIPTION: Run an AppImage in a sandbox using Aisap.
apikey
SYNOPSIS:
apikey {Github Token}
apikey delete
DESCRIPTION: Get unlimited access to https://api.github.com using your personal access tokens. The configuration file named "ghapikey.txt" will be saved in '$AMPATH' . Use the command "'$AMCLI' apikey delete/del/remove" to remove the file.
dev, devmode
SYNOPSIS:
dev off
dev on
DESCRIPTION: View the installer output during installation, use "on". It can be disabled with "off" or with the "-s" and "-u" options.
lock
SYNOPSIS:
lock {PROGRAM}
DESCRIPTION: Lock the selected app to the current version installed, this only works if exists a dedicated "AM-updater" installed with the app.
neodb
SYNOPSIS:
neodb
neodb --silent
DESCRIPTION: Add third-party repos to extend the existing database. Use "--silent" to hide messages about third-party repos in use.
newrepo
SYNOPSIS:
newrepo {URL}
newrepo off
newrepo on
DESCRIPTION: Set the variable "$AMREPO" to a new custom repository. Use "off" to restore the default one or overwrite it with a new one.
nolibfuse
SYNOPSIS:
nolibfuse {PROGRAM}
DESCRIPTION: Convert an installed Type2 AppImage to a Type3 AppImage. Type3 AppImages does not require libfuse2 installed.
unlock
SYNOPSIS:
unlock {PROGRAM}
DESCRIPTION: Unlock updates for the selected program. This option nulls the option "lock" (see above).
--system
SYNOPSIS:
--system
DESCRIPTION: Switch "AM" back to "AM" from "AppMan Mode" (see --user).
--user, appman (only available for "AM")
SYNOPSIS:
--user
DESCRIPTION: Run "AM" as an unprivileged user making it act as "AppMan".
| Install "AM"/"AppMan" | Back to "Main Index" |
|---|
This section is committed to giving small demonstrations of each available option, with videos:
- Install applications
- List the installed applications
- List and query all the applications available on the database
- Update all
- Backup and restore installed apps using snapshots
- Remove one or more applications
- Convert Type2 AppImages requiring libfuse2 to Type3 AppImages
- Integrate local AppImages into the menu by dragging and dropping them
- How to use "AM" in non-privileged mode, like "AppMan"
- Sandbox an AppImage
- How to enable bash completion
- How to update or remove apps manually
- Downgrade an installed app to a previous version
- Create and test your own installation script
- Third-party databases for applications (NeoDB)
Option -i or install, usage:
am -i $PROGRAM
or
appman -i $PROGRAM
in this video I'll install AnyDesk and LXtask:
install.mp4
| Back to "Guides and tutorials" | Back to "Main Index" |
|---|
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" |
|---|
Options -l or list shows the whole list of apps available in this repository.
Option -q or query shows search results from the list above.
list-and-query.mp4
| Back to "Guides and tutorials" | Back to "Main Index" |
|---|
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" |
|---|
Option -b or backup creates a copy of the installed app into a dedicated directory under $HOME/.am-snapshots:
backup.mp4
Each snapshot is named with the date and time you have done the backup. To restore the application to a previous version, copy/paste the name of the snapshot when the -o option will prompt it.
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:
overwrite.mp4
| Back to "Guides and tutorials" | Back to "Main Index" |
|---|
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" |
|---|
Option nolibfuse "just tries" to convert old Type2 AppImages asking for "libfuse2" into new Type3 AppImages:
convert-from-type2-to-type3-appimages.mp4
First the selected program type is checked, if it is a Type2 AppImage, it will be extracted and repackaged using the new version of appimagetool from https://github.com/probonopd/go-appimage :
- if the update occurs through "comparison" of versions, the converted AppImage will be replaced by the upstream version and the command is added within the application's AM-updater script, so as to automatically start the conversion at each update (prolonging the update time, depending on the size of the AppImage);
- instead, if the installed AppImage can be updated via
zsync, this may no longer be updatable.
I suggest anyone to contact the developers to update the packaging method of their AppImage!
NOTE, the conversion is not always successful, a lot depends on how the program is packaged. The conversion occurs in two steps:
- if in the first case it succeeds without problems, the package will be repackaged as it was, but of Type 3;
- if the script encounters problems (due to Appstream validation), it will attempt to delete the contents of the /usr/share/metainfo directory inside the AppImage, as a workaround.
If also the second step does not succeed either, the process will end with an error and the AppImage will remain Type2.
| Back to "Guides and tutorials" | Back to "Main Index" |
|---|
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 or a shell script that calls your AppImage, to place in "~/.local/bin", so that you can call it from the terminal:
- if you choose Y or ENTER, you can choose the name to use in $PATH
- if you choose N, the option will take care of the name to give to a script with ".appimage" extension (in lower case)
am --launcher /path/to/File.AppImage
or
appman --launcher /path/to/File.AppImage
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 the first video it shows three AppImages first positioned in one directory and then moved to another, in order to show you both how launchers are created (option "--launcher") and how to remove them (option "-c" , started first with the AppImage packages in the starting directory and then with the aforementioned moved elsewhere). The second video is a close-up on the terminal, to see in detail how the "--launcher" option works:
simplescreenrecorder-2024-06-18_04.30.21_edit.mkv.mp4
launcher-and-lynk-for-local-appimages.mkv.mp4
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
-cwill 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" |
|---|
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!
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).
- 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.
- 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;
- To allow Aipman take care of the AppImage, the latter be set to "not executable" and the related AM-updater will also have its
chmodcommand set froma+xtoa-x. - 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.
To remove the sandbox just run the command of the AppImage with the flag "--disable-sandbox", like this:
$APP --disable-sandbox
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
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" |
|---|
Bash completion is enabled in "AM" on first installation, while the "AppMan" one requires to be enabled manually.
For both there are two options:
--enabe-completionto enable it;--disable-completionto disable it.
The file used by "AM" is "/etc/bash_completion.d/am-completion.sh", so the root password is required to use the options. The file used by "AppMan" instead is "$HOME/.bash_completion".
Both use the keywords to be completed listed within the "list" file, generated from the options list and the applications list.
Enable.or.Disable.BASH.completion.in.AM.mp4
A more detailed guide on how to create your own bash completion script for your project is available here.
| Back to "Guides and tutorials" | Back to "Main Index" |
|---|
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" if you are an "AM" user).
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" |
|---|
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:
- Create a script for an AppImage package
- Build an AppImage on the fly using appimagetool and pkg2appimage
- Download and unpack a generic archive (ZIP, TAR...)
- Create a custom Firefox profile
To learn more about a specific option, use the index below
- Option Zero: "AppImages"
- Option One: "build AppImages on-the-fly"
- Option Two: "Archives and other programs"
- Option Three: "Firefox profiles"
Otherwise, go directly to the last paragraphs, which are
The easiest script to create is certainly the one relating to AppImages, the "Zero" option.
- 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
- 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)
- if the app is hosted on github, it will ask you if you want to add/remove keywords to use in
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
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.
The syntax seems simple, but you have to know what you're building.
You'll need to decide what kind of AppImage you want to build on the fly, whether to include a custom AppRun, "libunionpreload", and detect system libraries.
It will be used as the Debian base, but you can manually modify the script to suit your needs.
In this example I'll create the script for Abiword with "AM" and I'll install it using AppMan:
simplescreenrecorder-2024-06-20_17.16.53_edit.mkv.mp4
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 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).
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:
- 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
--rollbackordowngrade); - Create the directory of the application;
- The first file to be created is "
remove", to quickly remove app's pieces in case of errors; - Create the "tmp" directory, in which the app will be downloaded and, in the case of archives, extracted;
- 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);
- Downloading the application (and extract it in case of archive);
- 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;
- Creation/extract/download launcher and icon, the methods change depending on the type of application. For AppImages they are extracted from the package.
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
"AM"/"AppMan" can be extended by adding new application databases using a configuration file named "neodb".
For more details, see the full guide at https://github.com/ivan-hc/neodb
| Install "AM"/"AppMan" | Back to "Guides and tutorials" | Back to "Main Index" |
|---|
- An application does not work, is old and unsupported
- Cannot download or update an application
- Cannot mount and run AppImages
- Spyware, malware and dangerous software
- Stop AppImage prompt to create its own launcher, desktop integration and doubled launchers
- The script points to "releases" instead of downloading the latest stable
- Wrong download link
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.
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
--rollbackoption ordowngrade; - the reference site has changed, report any changes at https://github.com/ivan-hc/AM/issues
| Back to "Troubleshooting" | Back to "Main Index" |
|---|
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) 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 Type3, 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 to Type3.
- If you cannot run some AppImages on Ubuntu 23.10+ or its derivatives, then refer to Restricted unprivileged user namespaces are coming to Ubuntu 23.10 | Ubuntu for possible causes and remedies.
- If you cannot run chrome/chromium/electron-based AppImages, then refer to Troubleshooting/Electron-sandboxing for possible causes and remedies.
| Back to "Troubleshooting" | Back to "Main Index" |
|---|
Before installing any application, try to know where it comes from first. This program provides you with two basic options for this purpose:
- Option
-aorabout(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
-dordownload(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" |
|---|
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" |
|---|
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:
am -d $PROGRAM
sed -i 's#releases -O -#releases/latest -O -#g' $(xdg-user-dir DESKTOP)/$PROGRAM
am -i $(xdg-user-dir DESKTOP)/$PROGRAM
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
The reasons may be two:
- the referring link may have been changed, try the
--rollbackoption ordowngrade; - the reference site has changed, report any changes at https://github.com/ivan-hc/AM/issues
| Back to "Troubleshooting" | Back to "Main Index" |
|---|
- AppImaGen, a script that generates AppImages from Debian or from a PPA for the previous Ubuntu LTS;
- ArchImage, build AppImage packages for all distributions but including Arch Linux packages. Powered by JuNest;
- Firefox for Linux scripts, easily install the official releases of Firefox for Linux.
- My AppImage packages
© 2020-present Ivan Alessandro Sala aka 'Ivan-HC' - I'm here just for fun!
| ko-fi.com | PayPal.me | Install "AM"/"AppMan" | "Main Index" |
|---|