Installing Alpagua on Linux, from the archive

For Arch Linux, Fedora, openSUSE and any other distribution without a package for Alpagua. On Debian, Ubuntu, Linux Mint and the other systems based on Debian, take the package instead, which apt keeps track of: see INSTALL.debian.md. Don't install both: they share /opt/alpagua.

Alpagua-<version>-linux-x64.tar.gz is extracted at the root of the system, and puts:

• the app in /opt/alpagua, with its own libraries;
• the command /usr/local/bin/alpagua;
• the menu entry, the icons, the type of the .alpagua archives and the manual page in /usr/local/share.

Nothing outside /opt/alpagua and /usr/local, where your package manager never writes.

What the system needs

• An x86-64 PC (the archive is built for x64 only).
• A recent C library: the archive is built on Debian 13 (glibc 2.41). A system of 2025 or later has it; on an older one, the program stops at once with version 'GLIBC_2.xx' not found. ldd --version tells which one you have.
• GTK 3 and libsecret, as any Flutter app.
• A Secret Service, where Alpagua keeps the API keys: GNOME Keyring, KWallet (Plasma 6) or KeePassXC with its Secret Service integration turned on. Without one, Alpagua runs but cannot remember a key.

On Arch Linux:

sudo pacman -S --needed gtk3 libsecret gnome-keyring xdg-utils

xdg-utils gives xdg-open, with which Alpagua opens links and the browser of an OAuth sign-in. On Plasma, leave gnome-keyring out: KWallet answers already. On Fedora: sudo dnf install gtk3 libsecret gnome-keyring xdg-utils; on openSUSE: sudo zypper install gtk3 libsecret-1-0 gnome-keyring xdg-utils. A GNOME or Plasma desktop has nearly all of it already.

Installing

In the folder of the download:

sudo tar -xzf Alpagua-<version>-linux-x64.tar.gz -C /

Alpagua is then in the menu, under Internet (at once, or after logging in again), and alpagua starts it from a terminal. man alpagua describes the command.

For a double click on an .alpagua export archive to start its import, the desktop must learn their type, once:

sudo update-mime-database /usr/local/share/mime

tar -tzf Alpagua-<version>-linux-x64.tar.gz lists what the archive holds, before or after.

Updating

Quit Alpagua, then remove the previous version's folder before extracting the new archive, so that no file of the old one stays:

sudo rm -rf /opt/alpagua
sudo tar -xzf Alpagua-<version>-linux-x64.tar.gz -C /

Your conversations and settings are elsewhere (below), untouched.

Checking a download

On alpagua.com, the SHA-256 link under the download gives its checksum, <file>.sha256. Downloaded next to the file, it shows that the download is whole:

sha256sum -c Alpagua-<version>-linux-x64.tar.gz.sha256

which answers OK (or Réussi…, in the system's language).

Where your data is

• ~/.local/share/com.alpagua.app/: the database (conversations, settings), the imports.
• ~/Alpagua/: your notes, documents and skills, plain files you can open with other apps; the attachments in ~/Alpagua/.attachments.
• The API keys and tokens: in the Secret Service (Passwords and Keys, KWalletManager or KeePassXC show them).

Uninstalling

sudo rm -rf /opt/alpagua
sudo rm -f /usr/local/bin/alpagua \
  /usr/local/share/applications/com.alpagua.app.desktop \
  /usr/local/share/icons/hicolor/*/apps/com.alpagua.app.png \
  /usr/local/share/mime/packages/com.alpagua.app.xml \
  /usr/local/share/man/man1/alpagua.1.gz
sudo update-mime-database /usr/local/share/mime

That leaves your data. To remove it too, after an export if you may want it back: rm -rf ~/.local/share/com.alpagua.app ~/Alpagua.

When it does not start

Run /opt/alpagua/alpagua in a terminal and read what it says:

• version 'GLIBC_2.xx' not found: the system is older than the archive allows (see What the system needs).
• error while loading shared libraries: libgtk-3.so.0 (or libsecret-1.so.0): install GTK 3 or libsecret.
• The keys are forgotten at each start, or saving one fails: no Secret Service is running, or its keyring is locked. Install GNOME Keyring (or turn on KeePassXC's integration), log out and in again.
• No Alpagua in the menu: your desktop does not read /usr/local/share. echo $XDG_DATA_DIRS should list it, or be empty (which means /usr/local/share:/usr/share).

← Back to the downloads