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:
Move the downloaded AppImage to your home directory, e.g.:
$ mv ~/Downloads/librelane-devshell-$(uname -m).AppImage ~
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.