Skip to main content

Linux Bundle

Tauri applications for Linux are distributed either with a Debian bundle (.deb file) or an AppImage (.AppImage file). The Tauri CLI automatically bundles your application code in these formats by default. Please note that .deb and .AppImage bundles can only be created on Linux as cross-compilation doesn't work yet.

note

GUI apps on macOS and Linux do not inherit the $PATH from your shell dotfiles (.bashrc, .bash_profile, .zshrc, etc). Check out Tauri's fix-path-env-rs crate to fix this issue.

To build and bundle your Tauri application into a single executable simply run the following command:

npm run tauri build

It will build your frontend (if configured, see beforeBuildCommand), compile the Rust binary, collect all external binaries and resources and finally produce neat platform-specific bundles and installers.

Limitations​

Core libraries such as glibc frequently break compatibility with older systems. For this reason, you must build your Tauri application using the oldest base system you intend to support. A relatively old system such as Ubuntu 18.04 is more suited than Ubuntu 22.04, as the binary compiled on Ubuntu 22.04 will have a higher requirement of the glibc version, so when running on an older system, you will face a runtime error like /usr/lib/libc.so.6: version 'GLIBC_2.33' not found. We recommend using a Docker container or GitHub Actions to build your Tauri application for Linux.

See the issues tauri-apps/tauri#1355 and rust-lang/rust#57497, in addition to the AppImage guide for more information.

Debian​

The stock Debian package generated by the Tauri bundler has everything you need to ship your application to Debian-based Linux distributions, defining your application's icons, generating a Desktop file, and specifying the dependencies libwebkit2gtk-4.0-37 and libgtk-3-0, along with libappindicator3-1 if your app uses the system tray.

Custom Files​

Tauri exposes a few configurations for the Debian package in case you need more control.

If your app depends on additional system dependencies you can specify them in tauri.conf.json > tauri > bundle > deb > depends.

To include custom files in the Debian package, you can provide a list of files or folders in tauri.conf.json > tauri > bundle > deb > files. The configuration object maps the path in the Debian package to the path to the file on your filesystem, relative to the tauri.conf.json file. Here's an example configuration:

{
  "tauri": {
    "bundle": {
      "deb": {
        "files": {
          "/usr/share/README.md": "../README.md", // copies the README.md file to /usr/share/README.md
          "usr/share/assets": "../assets/" // copies the entire assets directory to /usr/share/assets
        }
      }
    }
  }
}

If you need to bundle files in a cross-platform way, check Tauri's resource and sidecar mechanisms.

AppImage​

AppImage is a distribution format that does not rely on the system installed packages and instead bundles all dependencies and files needed by the application. For this reason, the output file is larger but easier to distribute since it is supported on many Linux distributions and can be executed without installation. The user just needs to make the file executable (chmod a+x MyProject.AppImage) and can then run it (./MyProject.AppImage).

AppImages are convenient, simplifying the distribution process if you cannot make a package targeting the distribution's package manager. Still, you should carefully use it as the file size grows from the 2-6MBs range to 70+MBs.

caution

If your app plays audio/video you need to enable tauri.conf.json > tauri > bundle > appimage > bundleMediaFramework. This will increase the size of the AppImage bundle to include additional gstreamer files needed for media playback. This flag is currently only supported on Ubuntu build systems.

Cross-Compiling Tauri Applications for ARM-based Devices​

This guide explains how to cross-compile your Tauri application for ARM-based devices, such as the Raspberry Pi. Compiling directly on the device may not be feasible due to limited RAM, so we'll explore two methods: manual compilation using Linux or WSL on Windows and automatic cross-compilation using a GitHub Action.

Manual Compilation​

Manual compilation is suitable when you don't need to compile your application frequently and prefer a one-time setup. Follow the steps below:

Prerequisites​

danger

AppImages can only be built on ARM devices. To avoid Tauri from building it, you can customize tauri.conf.json in the src-tauri folder. Adjust the "targets" array to include only the desired platforms for your ARM-based device. For instance:

"targets": ["deb", "nsis", "msi", "app", "dmg", "updater"],

Alternatively you can use the --bundles flag when calling tauri build.

  • For Windows, install Debian on WSL using the wsl setup guide.
  • On Linux, the build machine requires GLIBC version equal to or older than the target device. Check using: ldd --version.
  • Use a Linux distribution based on Debian/Ubuntu for this guide, as the commands shown use the apt package manager and have been tested on Debian 11.

Cross-Compiling​

Now, let's cross-compile the Tauri application for ARM:

  1. Install Rust targets for your desired architecture:

    • For ARMv7 (32-bit): rustup target add armv7-unknown-linux-gnueabihf
    • For ARMv8 (ARM64, 64-bit): rustup target add aarch64-unknown-linux-gnu

  2. Install the corresponding linker for your chosen architecture:

    • For ARMv7: sudo apt install gcc-arm-linux-gnueabihf
    • For ARMv8 (ARM64): sudo apt install gcc-aarch64-linux-gnu

  3. Open or create the file <project-root>/.cargo/config.toml and add the following configurations accordingly:

    [target.armv7-unknown-linux-gnueabihf]
    linker = "arm-linux-gnueabihf-gcc"

    [target.aarch64-unknown-linux-gnu]
    linker = "aarch64-linux-gnu-gcc"

  4. Enable the respective architecture in the package manager:

    • For ARMv7: sudo dpkg --add-architecture armhf
    • For ARMv8 (ARM64): sudo dpkg --add-architecture arm64

  5. Adjusting Package Sources

On Debian, this step should not be necessary, but on other distributions, you might need to edit /etc/apt/sources.list to include the ARM architecture variant. For example on Ubuntu 22.04 add these lines to the bottom of the file (Remember to replace jammy with the codename of your Ubuntu version):

deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy main restricted
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-updates main restricted
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy universe
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-updates universe
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy multiverse
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-updates multiverse
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-backports main restricted universe multiverse
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-security main restricted
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-security universe
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-security multiverse

Then, to prevent issues with the main packages, you have to add the correct main architecture to all other lines the file contained beforehand. For standard 64-bit systems you need to add [arch=amd64], the full file on Ubuntu 22.04 then looks similar to this:

Click to see the full example file for Ubuntu 22.04
# See http://help.ubuntu.com/community/UpgradeNotes for how to upgrade to
# newer versions of the distribution.
deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy main restricted
# deb-src http://archive.ubuntu.com/ubuntu/ jammy main restricted

## Major bug fix updates produced after the final release of the
## distribution.
deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted
# deb-src http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted

## N.B. software from this repository is ENTIRELY UNSUPPORTED by the Ubuntu
## team. Also, please note that software in universe WILL NOT receive any
## review or updates from the Ubuntu security team.
deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy universe
# deb-src http://archive.ubuntu.com/ubuntu/ jammy universe
deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy-updates universe
# deb-src http://archive.ubuntu.com/ubuntu/ jammy-updates universe

## N.B. software from this repository is ENTIRELY UNSUPPORTED by the Ubuntu
## team, and may not be under a free licence. Please satisfy yourself as to
## your rights to use the software. Also, please note that software in
## multiverse WILL NOT receive any review or updates from the Ubuntu
## security team.
deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy multiverse
# deb-src http://archive.ubuntu.com/ubuntu/ jammy multiverse
deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy-updates multiverse

## N.B. software from this repository may not have been tested as
## extensively as that contained in the main release, although it includes
## newer versions of some applications which may provide useful features.
## Also, please note that software in backports WILL NOT receive any review
## or updates from the Ubuntu security team.
deb [arch=amd64] http://archive.ubuntu.com/ubuntu/ jammy-backports main restricted universe multiverse
# deb-src http://archive.ubuntu.com/ubuntu/ jammy-backports main restricted universe multiverse

deb [arch=amd64] http://security.ubuntu.com/ubuntu/ jammy-security main restricted
# deb-src http://security.ubuntu.com/ubuntu/ jammy-security main restricted
deb [arch=amd64] http://security.ubuntu.com/ubuntu/ jammy-security universe
# deb-src http://security.ubuntu.com/ubuntu/ jammy-security universe
deb [arch=amd64] http://security.ubuntu.com/ubuntu/ jammy-security multiverse
# deb-src http://security.ubuntu.com/ubuntu/ jammy-security multiverse

deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy main restricted
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-updates main restricted
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy universe
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-updates universe
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy multiverse
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-updates multiverse
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-backports main restricted universe multiverse
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-security main restricted
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-security universe
deb [arch=armhf,arm64] http://ports.ubuntu.com/ubuntu-ports jammy-security multiverse

After making these changes, verify that the armhf/arm64 architecture is still enabled in the package manager by re-running the command from Step 4.

  1. Update the package information: sudo apt-get update && sudo apt-get upgrade -y.

  2. Install the required webkitgtk library for your chosen architecture:

    • For ARMv7: sudo apt install libwebkit2gtk-4.0-dev:armhf
    • For ARMv8 (ARM64): sudo apt install libwebkit2gtk-4.0-dev:arm64

  3. Install OpenSSL or use a vendored version:

This is not always required so you may want to proceed first and check if you see errors like Failed to find OpenSSL development headers.

  • Either install the development headers system-wide:
    • For ARMv7: sudo apt install libssl-dev:armhf
    • For ARMv8 (ARM64): sudo apt install libssl-dev:arm64
  • Or enable the vendor feature for the OpenSSL Rust crate which will affect all other Rust dependencies using the same minor version. You can do so by adding this to the dependencies section in your Cargo.toml file:
openssl-sys = {version = "0.9", features = ["vendored"]}

  1. Set the PKG_CONFIG_SYSROOT_DIR to the appropriate directory based on your chosen architecture:

    • For ARMv7: export PKG_CONFIG_SYSROOT_DIR=/usr/arm-linux-gnueabihf/
    • For ARMv8 (ARM64): export PKG_CONFIG_SYSROOT_DIR=/usr/aarch64-linux-gnu/

  2. Build the app for your desired ARM version:

  • For ARMv7: cargo tauri build --target armv7-unknown-linux-gnueabihf
  • For ARMv8 (ARM64): cargo tauri build --target aarch64-unknown-linux-gnu

Choose the appropriate set of instructions based on whether you want to cross-compile your Tauri application for ARMv7 or ARMv8 (ARM64). Please note that the specific steps may vary depending on your Linux distribution and setup.

Experimental: Automatic Cross-Compilation using a GitHub Action​

For automated ARM executable builds on GitHub, we'll use the arm-runner-action created by Paul Guyot.

danger

AppImages can only be built on ARM devices. To avoid Tauri from building it, you can customize tauri.conf.json in the src-tauri folder. Adjust the "targets" array to include only the desired platforms for your ARM-based device. For instance:

"targets": ["deb", "nsis", "msi", "app", "dmg", "updater"],

Alternatively you can use the --bundles flag when calling tauri build.

Setup​

Follow the instructions in the arm-runner-action repository README to set up the GitHub Action. If you're new to GitHub Actions, read the GitHub Actions guide first.

Customize the last step in the GitHub Action YAML to generate a .deb file instead of an .img file:

name: Raspberry Pi compile
on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pguyot/arm-runner-action@v2.5.2
        with:
          base_image: https://dietpi.com/downloads/images/DietPi_RPi-ARMv8-Bullseye.img.xz
          cpu: cortex-a53
          bind_mount_repository: true
          image_additional_mb: 10240
          optimize_image: false
          commands: |
            # Rust complains (rightly) that $HOME doesn't match eid home
            export HOME=/root
            # Workaround to CI worker being stuck on Updating crates.io index
            export CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse
            # Install setup prerequisites
            apt-get update -y --allow-releaseinfo-change
            apt-get upgrade -y
            apt-get autoremove -y
            apt-get install curl
            curl https://sh.rustup.rs -sSf | sh -s -- -y
            . "$HOME/.cargo/env"
            curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash
            # Install framework specific packages
            apt-get install -y nodejs
            npm install next@latest react@latest react-dom@latest eslint-config-next@latest
            # Install build tools and tauri-cli requirements
            apt-get install -y libwebkit2gtk-4.0-dev build-essential wget libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev
            cargo install tauri-cli
            # Install frontend dependencies
            npm install
            # Build the application
            cargo tauri build
      - name: Upload deb bundle
        uses: actions/upload-artifact@v3
        with:
          name: Debian Bundle
          path: ${{ github.workspace }}/target/release/bundle/deb/tauri_1.4_arm64.deb

Adjust the path variable to match your application's version and name: ${{ github.workspace }}/target/release/bundle/deb/[name]_[version]_arm64.deb.