How unpakt works¶
This page explains what unpakt does on your computer, in plain terms. You do not need to know any programming.
What happens when you run unpakt add https://github.com/owner/repo¶
- unpakt finds the app. It asks GitHub for the repository's latest release and looks at the files attached to it.
- It picks the right file. It ignores checksums, signatures and files for
other systems or processors (Windows, macOS, 32-bit, ARM). Among what is
left it prefers an AppImage built for x86_64 Linux, then a tarball, then a
.deb,.rpmor pacman package (one for your own distribution first). - It downloads the file to a temporary folder in
~/.cache/unpakt. - It looks inside, without running anything. unpakt reads the file to find the app's name, version, icon, launcher information and the program to start. Nothing from the download is executed at this point.
- It shows you a summary (name, version, where it came from, the command
it will create) and asks
Install? [y/N]. Nothing has been changed yet. You can see the same summary withunpakt inspect, which never installs. - It installs. The app goes into its own folder, a launcher entry and an
icon are added so it shows up in your applications menu, and a command is
placed in
~/.local/binso you can start it from a terminal.
If you give a download URL or a file instead, the steps are the same minus the GitHub lookup.
Installing a .deb, .rpm or pacman package¶
A package is made for one distribution and expects to be installed by its package manager, as root. unpakt does something different and safer:
- It reads the package without running anything. That includes the package's install scripts: unpakt reads them as text and never runs them.
- It checks whether the app can run here. It looks at every library the
program needs and checks that your system has it, in a new enough version.
It also looks for paths the app expects in
/optor/usr/share, files meant for system folders (services, device rules, kernel modules), and install scripts that would create user accounts or change kernel settings. - It tells you the result, one of three:
ok: the app is expected to run. Any notes are shown, but nothing is asked of you.risky: something may stop it from running. unpakt lists what, and installs only if you accept (--allow-risky, or Install anyway in the app). It remembers what you accepted, so a later update only asks again when something new turns up.needs-container: the app needs newer system libraries than your computer has. unpakt cannot fix that from your home folder, so it does not install it.- It unpacks the files into the app's own folder under
~/.local/share/unpakt/apps/, rewrites links that pointed at/optor/usrso they point inside that folder, and adds the launcher entry, icon and command as for any other app.
Nothing goes into /usr, /opt or /etc, and your package manager never
sees the app, so it cannot conflict with the system's own packages. If you do
want it installed system-wide, unpakt prints the apt, dnf or pacman
command for you to run yourself.
Where things go¶
Everything is inside your home directory.
| What | Where |
|---|---|
| The apps | ~/.local/share/unpakt/apps/<app>/<version>/ |
| unpakt's records | ~/.local/share/unpakt/db.sqlite |
| Menu entries | ~/.local/share/applications/unpakt-<app>.desktop |
| Icons | ~/.local/share/icons/hicolor/ |
| Terminal commands | ~/.local/bin/ |
| Temporary downloads | ~/.cache/unpakt/downloads/ |
~/.local/bin has to be on your PATH for the terminal command to work.
unpakt doctor tells you whether it is.
unpakt keeps a list of every file it created for each app. Removing an app
deletes exactly those files. Files that unpakt did not create are never
replaced unless you pass --force, and a command that would be hidden by
another program of the same name is refused.
Updates¶
unpakt never checks for updates by itself. When you run
unpakt update --check, it asks each app's source what the newest version is:
for a GitHub repo it compares release tags; for a download URL it compares the
file's ETag or Last-Modified header. Apps installed from a file on your
disk have nowhere to ask and are skipped.
unpakt update installs the new version next to the old one and only then
switches the app over. If anything fails or you press Ctrl-C part-way, the old
version stays exactly as it was. unpakt keeps the last three versions of each
app.
Rollbacks¶
unpakt rollback <app> switches the app back to the previous version. It is
quick, since the older version is still on disk, and it deletes nothing. The
menu entry and icon stay; only what they launch changes. Running
For a GitHub app, unpakt update afterwards moves forward again without
downloading that version a second time.
If the power goes out mid-install¶
Each install, update, rollback and removal writes a small journal of what it is about to do before it does it. If the computer loses power or the process is killed:
- You may see leftovers from the interrupted step, but the app that was working before still works, because the new version was never switched on.
- The next time you run a command that changes something (
add,update,rollbackorremove), unpakt reads the journal first. If the interrupted change had actually completed, it only cleans up. Otherwise it undoes the steps one by one. - If a journal is damaged or points somewhere unpakt does not manage, unpakt
stops and tells you which file to look at instead of guessing.
unpakt doctorlists such files.
Only one unpakt changes things at a time. If you start a second one (or use the GUI while a command is running), it waits for the first and then goes on.
What unpakt never touches¶
- It never asks for root and never uses
sudo. - It writes only under your home directory:
~/.local/share,~/.local/binand~/.cache. It does not touch/usr,/optor/etc. - It does not run the apps it installs, other than asking the desktop to
refresh its menu (
update-desktop-database, if you have it). - It never runs a package's install scripts.
- It does not run in the background and does not start with your session.
- It does not verify the signatures of the apps it installs yet, so install apps from sources you trust.
If you remove unpakt itself, the apps it installed stay and keep working. Use
unpakt self uninstall --purge if you want unpakt to remove them as well.