How to Install and Use Gleam on Ubuntu 26.04 and 24.04

Share

To install Gleam on Ubuntu 26.04 or 24.04, use mise to install Gleam 1.19.2, Erlang/OTP 28 and rebar3 together. Alternatively, install the official Gleam binary after checking its SHA-256 checksum, while keeping a compatible Erlang runtime.

Gleam is a typed programming language that compiles to Erlang or JavaScript. It is useful for command-line tools and applications that can use the Erlang ecosystem. Below, you will create a project, add a package, run tests and export a build. If a step fails, leave a comment with the error or contact us.

Before you begin
  • Ubuntu 26.04 LTS or 24.04 LTS, internet access, a Bash terminal and sudo access for system dependencies.
  • The official Linux binaries used here support x86_64 and aarch64. Run uname -m to check.
  • Gleam 1.19 needs a supported OTP 28 or 29 runtime. Ubuntu 26.04 currently supplies OTP 27; Ubuntu 24.04 supplies OTP 25. The RabbitMQ Noble PPA currently supplies OTP 27, which also falls outside this support window.
  • Run mise, Gleam and project commands as your normal user. Choose one Gleam installation method to avoid conflicting executables.

The official compatibility reference lists OTP 28 and 29 for Gleam 1.18 and newer. A distribution package being available does not establish compatibility with this compiler.

1. Understand the Ubuntu Erlang Package Split

Gleam is not currently packaged in the Ubuntu APT archives for either release. Erlang is packaged, but its version matters:

System / route Erlang version What to choose
Ubuntu 26.04 LTS OTP 27 Native APT is too old for the Gleam 1.19 support window.
Ubuntu 24.04 LTS OTP 25 Native APT is too old. The RabbitMQ PPA supplies OTP 27, also outside that window.
Both releases: mise OTP 28 or 29 Use OTP 28 below with Gleam 1.19.2.

The official Ubuntu APT instructions allow Ubuntu 25.04 and newer, but the separate compiler compatibility table sets the newer requirement for Gleam 1.19. Check both before choosing a runtime.

APT routes for an older, compatible toolchain

Skip these commands for this Gleam 1.19.2 setup. They document the distribution split and are relevant only when an existing project deliberately uses an older compatible compiler. Gleam 1.11 through 1.17 supports OTP 27; older minor compiler releases generally do not receive current fixes. Prefer the current setup below for a new project.

Ubuntu 26.04: native APT installs OTP 27:

Ubuntu terminal
sudo apt update && sudo apt install -y erlang-dev erlang-nox rebar3

Ubuntu 24.04: adding the Team RabbitMQ PPA upgrades the system Erlang packages to its currently supplied OTP 27. It is a third-party repository and can affect existing Erlang applications, including RabbitMQ. Back up and check those applications before changing their runtime:

Ubuntu terminal
sudo apt install -y software-properties-common &&
sudo add-apt-repository -y ppa:rabbitmq/rabbitmq-erlang &&
sudo apt update &&
sudo apt install -y erlang-dev erlang-nox rebar3

erlang-nox selects the non-X Erlang bundle, but Ubuntu rebar3 recommends the full erlang metapackage and has further dependencies. These exact APT commands do not guarantee a GUI-free installation. Review APT’s package list; the mise source-build route below explicitly disables wxWidgets instead. The PPA version can change, so always verify the installed OTP release.

2. Install Gleam, OTP 28 and rebar3 with mise

Step 1: Install and activate mise

Follow our mise installation and shell setup guide first, including Bash activation. Then check:

Ubuntu terminal
mise --version
mise doctor
type -a gleam erl rebar3

Missing Gleam, Erlang or rebar3 commands are normal on a fresh system. If commands already exist, identify their installation source before proceeding. mise will set personal defaults; project-specific mise settings can still override them.

Step 2: Install the Erlang build dependencies

This route builds OTP 28 from source on both Ubuntu releases, avoiding differences in precompiled runtime detection and disabling GUI, Java and ODBC components:

Ubuntu terminal
sudo apt update &&
sudo apt install -y curl ca-certificates git build-essential autoconf m4 pkg-config libncurses-dev libssl-dev libssh-dev

These packages supply the compiler tools, terminal and TLS headers. They do not install a full Erlang desktop bundle. Source compilation takes longer than downloading a binary; allow it to finish before continuing.

Step 3: Install a supported Erlang runtime

Run this from your home directory in the activated shell:

Ubuntu terminal
cd ~
MISE_ERLANG_COMPILE=true KERL_CONFIGURE_OPTIONS="--without-javac --without-wx --without-odbc" mise use --global erlang@28

mise uses kerl to build the newest matching OTP 28 patch release for your account. The environment settings apply to this command. Disabled optional applications are not needed for the examples; projects using wxWidgets, Java integration or ODBC need a build with their dependencies enabled. See the mise Erlang guide for binary selection and build options.

Step 4: Install the pinned compiler and rebar3

Use the mise registry name rebar; the installed command is rebar3:

Ubuntu terminal
mise use --global [email protected] rebar@3
gleam --version
rebar3 version
erl -eval 'erlang:display(erlang:system_info(otp_release)), halt().' -noshell

Expect gleam 1.19.2, a rebar3 version and “28” from Erlang. rebar3 builds native Erlang Hex dependencies; you do not need the system APT rebar3 package as well. Package-specific C extensions may need additional libraries. OTP 29 is also supported by Gleam 1.19, but this guide keeps one runtime choice throughout.

The shorter mise use --global erlang@28 [email protected] rebar@3 is suitable when you already have the runtime prerequisites and want mise to choose its default binary-or-source route. Pinning 1.19.2 keeps this walkthrough consistent; gleam@latest can later select a compiler with a different OTP support window.

3. Alternative: Install the Official Gleam Binary

Skip this section if mise already installed Gleam. For this standalone method, complete the mise setup for OTP 28 and rebar3 only, omitting the Gleam tool: use mise use --global rebar@3 after the OTP build. The standalone Gleam binary does not include Erlang or rebar3.

Step 1: Download and verify the matching archive

Run this complete block in Bash. It creates an isolated temporary directory, rejects unsupported architectures and stops before extraction if any download or checksum check fails:

Ubuntu terminal
(
  set -eu
  version="v1.19.2"
  arch="$(uname -m)"
  case "$arch" in
    x86_64|aarch64) ;;
    *) printf 'Unsupported architecture: %s\n' "$arch" >&2; exit 1 ;;
  esac
  workdir="$(mktemp -d)"
  cd "$workdir"
  archive="gleam-${version}-${arch}-unknown-linux-musl.tar.gz"
  base="https://github.com/gleam-lang/gleam/releases/download/${version}"
  curl -fL --retry 3 -o "$archive" "$base/$archive"
  curl -fL --retry 3 -o "$archive.sha256" "$base/$archive.sha256"
  sha256sum -c "$archive.sha256"
  tar -xzf "$archive" gleam
  mkdir -p "$HOME/.local/bin"
  install -m 0755 gleam "$HOME/.local/bin/gleam"
  printf 'Installed Gleam. Download files remain in: %s\n' "$workdir"
)

The checksum result must say OK. This installs ~/.local/bin/gleam and replaces a binary already at that exact path, so identify or back up an existing manual installation first. The musl build runs on Ubuntu without needing a Rust compiler. Download both files from the official v1.19.2 release; a same-source checksum detects corruption, but does not independently authenticate a compromised release account.

Step 2: Put the user binary on PATH

Set PATH for this terminal, then check the actual command selected:

Ubuntu terminal
export PATH="$HOME/.local/bin:$PATH"
type -a gleam
gleam --version

Expect gleam 1.19.2 from ~/.local/bin/gleam. If another executable takes precedence, resolve the earlier installation rather than keeping multiple active copies.

Step 3: Keep PATH in new Bash terminals

Append this line to ~/.bashrc once if it does not already contain an equivalent entry:

Ubuntu terminal
grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' "$HOME/.bashrc" ||
  printf '%s\n' 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.bashrc"

Open a new terminal to verify the change. For Zsh, add the same export to ~/.zshrc instead; do not source Bash configuration from Zsh. A system-wide /usr/local/bin installation is possible, but this guide keeps one user-local location for updates and removal.

4. Create and Run Your First Gleam Project

Step 1: Use a snake_case name

Start outside any existing project. If hello_gleam already exists, choose a different new snake_case name:

Ubuntu terminal
cd ~
gleam new hello_gleam && cd hello_gleam && gleam run

Gleam package names use lowercase letters and underscores, with digits allowed after the first character. Use hello_gleam, not hello-gleam. The new command derives the package name from the directory. The first run resolves and downloads dependencies, compiles the code and prints the greeting below. Stop if project creation fails rather than working in a different directory.

Hello from hello_gleam!
Know which files to keep
  • gleam.toml records the package name, version, dependency ranges and development dependencies such as gleeunit.
  • manifest.toml is generated during dependency resolution and locks the selected dependency versions. Keep it in version control for this application; do not edit it by hand.
  • src/hello_gleam.gleam contains the program’s main function.
  • test/hello_gleam_test.gleam contains the generated gleeunit runner and a starter test.
  • build/ contains generated artifacts and downloaded project dependencies. It can be recreated.

Keep source files, tests, gleam.toml and manifest.toml together when backing up or sharing this application. See the gleam.toml reference for configuration options.

5. Add a Hex Package and Read Arguments

Step 1: Add argv

From ~/hello_gleam, add the cross-platform argument package from Hex:

Ubuntu terminal
gleam add argv@1

This updates gleam.toml and manifest.toml and downloads the selected package. The argv documentation shows how to read command-line arguments on Erlang and JavaScript.

Step 2: Replace the starter program

This overwrites src/hello_gleam.gleam in the practice project. Save any changes you want to keep first:

Ubuntu terminal
cat > src/hello_gleam.gleam <<'GLEAM'
import argv
import gleam/io

pub fn greeting(name: String) -> String {
  "Hello, " <> name <> "!"
}

pub fn main() {
  case argv.load().arguments {
    [name] -> io.println(greeting(name))
    _ -> io.println("Usage: gleam run -- <name>")
  }
}
GLEAM

greeting accepts a String and returns a String. The <> operator joins strings. The case expression matches a list with exactly one argument; any other list prints the usage message.

Step 3: Pass a name to the program

The -- separator sends the following argument to your program:

Ubuntu terminal
gleam run -- Ubuntu

The program should print:

Hello, Ubuntu!

Use gleam run -- "Ubuntu user" for a name containing spaces. Running without a name prints the usage message. Quoting keeps the name as one argument.

6. Test and Format the Code

Step 1: Test the actual greeting function

This replaces the generated starter test. It imports the application code so the test checks your function rather than a separate copied calculation:

Ubuntu terminal
cat > test/hello_gleam_test.gleam <<'GLEAM'
import gleeunit
import hello_gleam

pub fn main() -> Nil {
  gleeunit.main()
}

pub fn greeting_test() {
  assert hello_gleam.greeting("Ubuntu") == "Hello, Ubuntu!"
}
GLEAM
gleam test

gleeunit is already a development dependency in the generated project. It discovers public functions ending in _test. Expect one passing test; a failure reports the assertion or compilation error.

Step 2: Apply the formatter and check again

These commands format Gleam source files, check the formatting without rewriting, then run the test:

Ubuntu terminal
gleam format && gleam format --check && gleam test

gleam format rewrites source layout into the standard style. It does not repair a broken algorithm. Commit your work before broad formatting changes in an existing project.

7. Export an Erlang Build

Create the shipment

From the project directory, run:

Ubuntu terminal
gleam export erlang-shipment

Gleam writes compiled Erlang bytecode, configuration and a start script into build/erlang-shipment. This is a deployment directory, not a standalone native binary. The destination machine still needs a compatible Erlang runtime and any external libraries used by native dependencies. Test the shipment on its intended host before deploying a service.

Gleam also supports --target javascript with Node.js, Deno or Bun when the project’s dependencies support that target; our Deno guide for Ubuntu covers installing one of those runtimes. See the Gleam command reference for export and runtime options.

8. Update Gleam and Project Dependencies

mise installation: choose the next compiler deliberately

Check available changes first:

Ubuntu terminal
mise outdated

Before switching the compiler, read its compatibility reference and choose an OTP version it supports. To select the newest Gleam release after that review, use the following; latest may no longer mean 1.19.2:

Ubuntu terminal
mise use --global gleam@latest
gleam --version

For the standalone method, repeat the complete binary download-and-checksum block with version changed to the chosen release tag. Replace ~/.local/bin/gleam only after its checksum passes. There is no APT upgrade for this manual binary. Keep the previous verified archive if you need a rollback.

Update the application dependencies separately

From ~/hello_gleam, inspect and update within gleam.toml’s dependency ranges:

Ubuntu terminal
gleam deps outdated
gleam deps update && gleam test

Review manifest.toml changes and rerun the program. Updating dependencies does not update the Gleam compiler. If a new major package version is excluded by the manifest ranges, review its migration notes before changing the range.

9. Fix Common Installation Problems

Issue 1: gleam: command not found

For mise, run mise doctor and check that its shell activation is loaded. For the manual binary, try:

Ubuntu terminal
~/.local/bin/gleam --version
export PATH="$HOME/.local/bin:$PATH"
type -a gleam

If the direct path works, fix PATH in the startup file for your shell. If the file is absent, inspect the earlier download error; do not use sudo to create a second unrelated installation.

Issue 2: Erlang is too old

Check the runtime actually selected:

Ubuntu terminal
type -a erl
erl -eval 'erlang:display(erlang:system_info(otp_release)), halt().' -noshell
mise current

OTP 25 from Ubuntu 24.04 and OTP 27 from Ubuntu 26.04 or the RabbitMQ PPA fall outside Gleam 1.19’s OTP 28/29 window. Load mise activation, install OTP 28 as above and check whether a project-level mise configuration overrides your global setting. Seeing a working erl command is insufficient; read its version.

Issue 3: A package cannot find rebar3 or compile native code

Check rebar3 version and type -a rebar3. Install rebar@3 through mise if it is missing. Read the package’s own build requirements for C libraries or other dependencies. The OTP build prerequisites do not cover every Hex package. Fix the first reported error before deleting lockfiles.

Issue 4: Invalid project name

Use lowercase snake_case, such as hello_gleam. A name with a hyphen, uppercase initial or leading digit is unsuitable as the package name. Create the practice project with the exact name shown; changing it also changes the source module and test import names.

Issue 5: Checksum failure or interrupted download

Do not extract or install an archive whose checksum fails. Repeat the complete download block in a fresh temporary directory, confirm that the archive and checksum use the same release tag and architecture, and retry after resolving network errors. Do not disable certificate checks or bypass sha256sum.

Issue 6: OTP source build fails

Confirm that the prerequisite APT command completed, then read the mise/kerl build log for the first missing library or compiler error. Retry the same OTP build after fixing it. A low-memory machine may need a smaller build parallelism or a verified compatible precompiled runtime; the mise Erlang documentation explains the available choices.

10. Remove Gleam and Clean Up

mise installation: remove the selected tools

First inspect installed versions and global/project configuration:

Ubuntu terminal
mise ls
mise current

The following command removes the global Gleam request and prunes unused installed versions. mise keeps versions still needed by tracked configurations or tool stubs; check project settings before removing shared tools:

Ubuntu terminal
mise unuse --global gleam

Only if no other project needs the managed runtime or builder, use mise unuse --global erlang rebar too. Check project-level configurations before deleting shared versions. This does not remove APT Erlang packages or your source directories.

Manual installation: delete only its binary

If you chose ~/.local/bin rather than mise, remove that exact file:

Ubuntu terminal
rm -f -- "$HOME/.local/bin/gleam"
hash -r

Keep ~/.local/bin and its PATH entry if other programs use them. If you deliberately installed elsewhere, confirm that path and installation owner before removing it.

Optional caches: inspect before deleting

Close running builds first. Gleam normally uses ~/.cache/gleam, or $XDG_CACHE_HOME/gleam when configured. That directory can also contain Hex authentication data. ~/.hex and ~/.cache/rebar3 may be shared with other Erlang or Elixir projects and may contain configuration or credentials, not just disposable downloads.

Ubuntu terminal
ls -ld -- "${XDG_CACHE_HOME:-$HOME/.cache}/gleam" "$HOME/.hex" "$HOME/.cache/rebar3"

Missing-directory messages are harmless. Only after confirming these locations are expendable, remove the selected directories through Files or run this optional command, which permanently removes all three:

Ubuntu terminal
rm -rf -- "${XDG_CACHE_HOME:-$HOME/.cache}/gleam" "$HOME/.hex" "$HOME/.cache/rebar3"

Back up configuration or credentials you need first. This does not delete ~/hello_gleam. To remove only generated project files, run gleam clean while Gleam is still installed.

Only if you used the optional APT/PPA route

Skip this for the mise setup. On Ubuntu 24.04, ppa-purge disables the RabbitMQ PPA and attempts to downgrade its packages to Ubuntu versions. That can downgrade other Erlang-related packages and interrupt applications. Review its proposed changes; do not use it on a shared RabbitMQ server without a maintenance and recovery plan:

Ubuntu terminal
sudo apt update && sudo apt install -y ppa-purge
sudo ppa-purge ppa:rabbitmq/rabbitmq-erlang

On either release, if no other software needs the APT packages, preview removal first:

Ubuntu terminal
sudo apt purge --simulate erlang-dev erlang-nox rebar3

Review the list, then remove only when appropriate:

Ubuntu terminal
sudo apt purge erlang-dev erlang-nox rebar3
sudo apt autoremove --dry-run

Removing these top-level packages can leave other Erlang components. The final command only previews orphan cleanup. Review it carefully before choosing to run autoremove without --dry-run; never blindly purge every package matching erlang*.

Frequently Asked Questions

Can I install Gleam 1.19 using only Ubuntu APT?

No. Gleam is not currently in the Ubuntu 24.04 or 26.04 APT archives. Their Erlang packages are also outside Gleam 1.19’s supported OTP 28/29 window. Use a compatible runtime and install Gleam separately or through mise.

Does the RabbitMQ PPA make Ubuntu 24.04 ready for Gleam 1.19?

The PPA currently supplies OTP 27 for Noble. That is newer than Ubuntu 24.04’s default OTP 25, but still outside Gleam 1.19’s supported OTP 28/29 window.

Why does hello-gleam fail as a project name?

Gleam package names use lowercase snake_case, such as hello_gleam. Hyphens are not valid in the package name. Use the same package name in the source module and test imports.

Does the Gleam binary include Erlang?

No. The compiler is a separate executable. Erlang-target programs need a compatible Erlang runtime, and native Erlang Hex dependencies may also need rebar3 and package-specific build tools.

What is the difference between gleam.toml and manifest.toml?

gleam.toml declares your project settings and dependency ranges. manifest.toml is generated during dependency resolution and locks selected versions. Keep both with this application and do not edit the generated lockfile by hand.

Is an Erlang shipment a standalone executable?

No. It is a directory containing compiled bytecode, configuration and a start script. The destination machine still needs a compatible Erlang runtime and any external native libraries used by dependencies.

More Ubuntu development guides: Set up Visual Studio Code · Use curl for downloads and checks