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:
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:
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:
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:
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:
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:
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:
(
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
~/.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:
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:
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:
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:
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.
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:
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:
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:
sudo apt purge --simulate erlang-dev erlang-nox rebar3
Review the list, then remove only when appropriate:
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
Views: 88