Gleam Installation

Setting up Gleam takes less than ten minutes on any major operating system. This topic walks you through installing Gleam, Erlang, and the tools you need to write and run your first Gleam program.

What You Need to Install

Gleam does not work in isolation. It needs two things on your machine:

Installation Stack
──────────────────────────────────
┌─────────────────────────────────┐
│        Your Gleam Code          │
├─────────────────────────────────┤
│     Gleam Compiler (gleam CLI)  │
├─────────────────────────────────┤
│   Erlang/OTP  (runs the code)   │
└─────────────────────────────────┘

Erlang/OTP is the virtual machine that runs your compiled Gleam code. The Gleam CLI is the tool that compiles, tests, and manages your projects. Both must be present before you write any code.

Installing on Windows

Step 1 — Install Erlang

Visit the official Erlang Solutions website and download the Windows installer for Erlang/OTP. Run the installer and follow the on-screen steps. Accept the default installation path.

After installation, open Command Prompt and verify the install:

erl -version

You should see an Erlang version number printed in the terminal.

Step 2 — Install Gleam via Winget

Windows 10 and 11 include winget, a built-in package manager. Open Command Prompt or PowerShell and run:

winget install gleam

Winget downloads and installs the Gleam CLI automatically. Alternatively, download the pre-built binary from the Gleam GitHub releases page and add it to your system PATH.

Step 3 — Verify the Gleam Install

gleam --version

A version string like gleam 1.x.x confirms a successful installation.

Installing on macOS

Using Homebrew (Recommended)

Homebrew is the most popular package manager for macOS. If you do not have it, visit brew.sh and follow the install instructions. Once Homebrew is ready, run:

brew install gleam

Homebrew automatically installs Erlang as a dependency, so you get everything in one command.

Verify the Install

gleam --version
erl -version

Both commands should return version numbers.

Installing on Linux

Ubuntu / Debian

First, install Erlang from the Erlang Solutions repository:

wget https://packages.erlang-solutions.com/erlang-solutions_2.0_all.deb
sudo dpkg -i erlang-solutions_2.0_all.deb
sudo apt-get update
sudo apt-get install erlang

Then install Gleam. Download the latest binary from the official Gleam GitHub releases page. Choose the file ending in -linux-amd64.tar.gz for most systems.

tar -xzf gleam-vX.X.X-linux-amd64.tar.gz
sudo mv gleam /usr/local/bin/

Fedora / RHEL

sudo dnf install erlang
# Then install Gleam binary as shown above

Using ASDF (All Linux Distros)

asdf is a version manager that handles multiple programming languages. Many developers prefer it because it lets you switch Gleam or Erlang versions per project.

asdf plugin add gleam
asdf plugin add erlang
asdf install erlang latest
asdf install gleam latest
asdf global gleam latest
asdf global erlang latest

Install a Code Editor

A good editor makes writing Gleam much more enjoyable. The Gleam team recommends Visual Studio Code with the official Gleam extension.

Editor Setup
──────────────────────────────────
VS Code
  └── Extensions panel
        └── Search: "Gleam"
              └── Install: Gleam (by Gleam team)

Features you get:
  ✓ Syntax highlighting
  ✓ Auto-complete
  ✓ Inline type information
  ✓ Error underlining
  ✓ Go to definition

Other editors with Gleam support include Neovim (via LSP), Zed, and Helix. All of them use the Gleam Language Server, which the Gleam CLI installs automatically.

Checking Your Full Setup

Run these three commands to confirm everything works:

gleam --version   # Should print: gleam 1.x.x
erl -version      # Should print: Erlang x.x
gleam new hello   # Should create a new project folder

If gleam new hello runs without errors and creates a folder named hello, your environment is ready.

Troubleshooting Common Issues

Problem: "gleam: command not found"

The Gleam binary is not on your system's PATH. On Linux and macOS, add this line to your shell configuration file (~/.bashrc, ~/.zshrc, or ~/.profile):

export PATH="$PATH:/usr/local/bin"

Restart your terminal and try again.

Problem: Erlang not found

Gleam needs Erlang to run programs. Install Erlang first using the steps above, then install Gleam. The order matters.

Problem: Wrong Erlang Version

Gleam requires Erlang/OTP 26 or later. Check your version with erl -version. If it shows an older version, uninstall the old Erlang and install the latest using the steps in this topic.

Optional: Install Rebar3

Rebar3 is the Erlang build tool. Some Gleam packages that wrap Erlang libraries require it. Install it with:

brew install rebar3        # macOS
sudo apt install rebar3   # Ubuntu

Most pure Gleam projects do not need Rebar3, so you can skip this step for now and install it later when a project requires it.

Setup Summary

Quick Checklist
──────────────────────────────────
[ ] Erlang/OTP installed
[ ] Gleam CLI installed
[ ] gleam --version returns a version
[ ] erl -version returns a version
[ ] VS Code + Gleam extension installed
[ ] gleam new test-project runs without error

Once all boxes are checked, you are ready to write Gleam programs. The next topic walks you through creating and running your first complete Gleam program.