Linux

  • Minimum Requirements

    • Quad-core CPU running at 2.0 GHz+

    • 8 GiB of RAM

  • Recommended Requirements

    • 6th Gen Intel® Core CPU or later OR AMD Ryzen™ 1000-series or later

    • 16 GiB of RAM

For Ubuntu, only 22.04 and above are officially supported.

Installation of required packages

Update the package database and upgrade the packages to avoid version mismatches then install required packages as follows:

sudo apt-get update
sudo apt-get install -y build-essential python3 python3-venv python3-pip python3-tk curl make git

Downloading the LibreLane AppImage

Download the latest release from https://github.com/librelane/librelane/releases/latest using your browser.

Most people should download librelane-devshell-x86_64.AppImage, but those on ARM-based computers should download librelane-devshell-aarch64.AppImage.

In a terminal, do the following:

  1. Move the downloaded AppImage to your home directory, e.g.:

    $ mv ~/Downloads/librelane-devshell-$(uname -m).AppImage ~
    
  2. Give execution permissions for the LibreLane AppImage:

    $ chmod a+x ~/librelane-devshell-$(uname -m).AppImage
    

Entering the LibreLane Environment

From your terminal, simply type ~/librelane-devshell-$(uname -m).AppImage.

Your prompt should now look kind of like this:

[nix-shell:~]$ 

That’s it! You are now inside the LibreLane environment and can run any of the included tools.

You can test that LibreLane works correctly by running librelane --smoke-test.

Troubleshooting

Launching fails with cannot write uid_map: Operation not permitted

From our testing, this is usually an issue on Ubuntu. You may unfortunately need root privileges to enable running the LibreLane AppImage.

First of all, ensure that the uidmap package is installed. On Debian-based distributions (like Ubuntu), that’s:

$ sudo apt update
$ sudo apt-get install -y uidmap

Furthermore, starting Ubuntu 24.04, if AppArmor is enabled, you may need to take additional steps. First, run the following command:

$ sysctl kernel.apparmor_restrict_unprivileged_userns

If the output is kernel.apparmor_restrict_unprivileged_userns = 1, you will need to disable the restriction on unprivileged user namespaces. You can do this using this one-liner:

$ echo "kernel.apparmor_restrict_unprivileged_userns = 0" | sudo tee /etc/sysctl.d/99-userns.conf && sudo sysctl --system

warning: setlocale: cannot change locale (en_US.UTF-8)

This usually indicates either en_US.UTF-8 is missing or the entire locale archive is missing. For consistency, LibreLane uses the American English UTF-8 locale exclusively.

We are currently investigating a platform-agnostic solution, but in the meantime, the fix is as follows:

The archive is typically located in /usr/lib/locale/locale-archive. If it exists, the fix can be as simple as export LOCALE_ARCHIVE=/usr/lib/locale/locale-archive before starting LibreLane.

Note

Make sure you run any of the commands in this section outside of the LibreLane environment.

You can check if it exists at all using this command:

$ [ -f /usr/lib/locale/locale-archive ] && echo 'Exists' || echo 'Not found'

If it either doesn’t exist at all or does exist but the error still occurs, here is how to fix it on some major distributions:

Fixing missing archive or locale on Debian/Ubuntu

$ sudo dpkg-reconfigure locales

Follow the on-screen instructions: make sure en_US.UTF-8 UTF-8 is checked.

You should also include any locales you use.

Afterwards, run this command to ensure the archive exists:

$ sudo locale-gen

Depending on your setup, you may still need to export LOCALE_ARCHIVE=/usr/lib/locale/locale-archive before entering the LibreLane environment.

Fixing missing archive or locale on RHEL derivatives or Fedora

We found that this command works on the latest version of Fedora.

$ sudo localedef --add-to-archive /usr/lib/locale/en_US.utf8

Depending on your setup, you may still need to export LOCALE_ARCHIVE=/usr/lib/locale/locale-archive before entering the LibreLane environment.