Skip to main content

Hello World (first programs) · Beginner · 15 min

Hello World in Gleam: a type-safe language for the BEAM

By Padding · Updated 18 Nov 2026
Gleam 1.19.2 · Erlang/OTP 29.1.2 · ghcr.io/gleam-lang/gleam:v1.19.2-erlang

You will install Gleam 1.19 and Erlang, create and run a Gleam project, write functions with labelled arguments and pattern matching, pass gleam test, and compile the same code to JavaScript.

On this page

Gleam is a statically typed functional language that compiles to Erlang or to JavaScript. When it compiles to Erlang, your program runs on the BEAM, the same virtual machine as Erlang and Elixir, with its lightweight processes and its long record of running systems that stay up for years. When it compiles to JavaScript, the same code runs in Node.js or in a browser.

What sets Gleam apart from its BEAM neighbours is the type checker. Every value has a type the compiler knows before the program runs, and there is no null: a value that might be missing has a type that says so, and the compiler makes you handle both cases. Gleam also has no exceptions for ordinary failures. A function that can fail returns a Result, which is either Ok(value) or Error(reason), and you deal with it like any other value. The compiler's error messages are written to be read by people: they point at the line, explain the problem in plain words and often suggest the fix.

Louis Pilfold started Gleam in 2016, and version 1.0 was released in March 2024. It is used for web back ends on the BEAM (with libraries such as Wisp and Mist) and for front ends in the browser with Lustre, a framework in the style of Elm. In this tutorial you install Gleam and Erlang, create a project, read what the project generator made, write functions with labelled arguments and pattern matching, run the tests, and then compile the same code to JavaScript.

Step 1 · Install Gleam and Erlang

Gleam is one program, gleam, that contains the compiler, the build tool, the package manager, the code formatter and the test runner. To run code on the BEAM you also need Erlang/OTP. Gleam 1.19 supports Erlang/OTP 28 and 29. Older releases such as OTP 27 are no longer on Gleam's supported list, so neither the compiler team nor most package authors test against them.

  • Ubuntu 26.04: download the ready-built gleam binary from the Gleam releases on GitHub, check it against its published checksum, and put it in ~/.local/bin. The files keep their original names, because the checksum file refers to the archive by that name.
Bash
url=https://github.com/gleam-lang/gleam/releases/download/v1.19.2/gleam-v1.19.2-x86_64-unknown-linux-musl.tar.gz
curl -fLO "$url"
curl -fLO "$url.sha256"
sha256sum -c gleam-v1.19.2-x86_64-unknown-linux-musl.tar.gz.sha256
tar xf gleam-v1.19.2-x86_64-unknown-linux-musl.tar.gz
mkdir -p ~/.local/bin
mv gleam ~/.local/bin/
rm gleam-v1.19.2-x86_64-unknown-linux-musl.tar.gz gleam-v1.19.2-x86_64-unknown-linux-musl.tar.gz.sha256

sha256sum -c must print gleam-v1.19.2-x86_64-unknown-linux-musl.tar.gz: OK. If it prints FAILED or a warning instead, delete both files and download them again. On an ARM machine (a Raspberry Pi or an ARM laptop), replace x86_64 with aarch64 everywhere it appears in the block, including the file names in the last four commands.

Next, Erlang. Do not use sudo apt install erlang here: Ubuntu 26.04's own package is Erlang/OTP 27, which is too old for Gleam 1.19. Instead, download a ready-built OTP 29 from builds.hex.pm, the build service run by Hex (the BEAM package registry), check it, and install it in your home folder. The download is about 75 MB, so use Wi-Fi if you are on prepaid mobile data.

Bash
cd ~
curl -fLO https://builds.hex.pm/builds/otp/amd64/ubuntu-26.04/OTP-29.1.2.tar.gz
curl -fsS https://builds.hex.pm/builds/otp/amd64/ubuntu-26.04/builds.txt | awk '$1 == "OTP-29.1.2" {print $4 "  OTP-29.1.2.tar.gz"}' | sha256sum -c
mkdir -p ~/.local/otp ~/.local/bin
tar xf OTP-29.1.2.tar.gz -C ~/.local/otp
~/.local/otp/OTP-29.1.2/Install -minimal ~/.local/otp/OTP-29.1.2
ln -sf ~/.local/otp/OTP-29.1.2/bin/* ~/.local/bin/
rm OTP-29.1.2.tar.gz

Line by line: the first curl downloads the build. The second fetches builds.txt, the list of builds with their checksums; awk picks the line for OTP-29.1.2 and sha256sum -c compares it with your download, printing OTP-29.1.2.tar.gz: OK. tar unpacks it into ~/.local/otp, Install -minimal points Erlang's start-up scripts at the folder it now lives in, and ln -sf puts links to erl, erlc and escript in ~/.local/bin, where Gleam will find them. On an ARM machine, replace amd64 with arm64 in both URLs.

You do not need rebar3 (an Erlang build tool) for this tutorial; Gleam only uses it for packages that contain Erlang code built with rebar3.

Ubuntu adds ~/.local/bin to your PATH when you log in, if the folder exists. If gleam or erl is not found in the next check, log out and back in, or open a new terminal. Programs installed this way get no apt security updates: to upgrade, repeat the downloads with the newer version numbers from the Gleam releases page and builds.hex.pm.

  • macOS: with Homebrew, run brew install gleam. If the erl check below says command not found, also run brew install erlang rebar3.
  • Windows: in PowerShell, run winget install --id Gleam.Gleam, then install Erlang/OTP 29 from the installer on erlang.org.
  • Android: the Gleam install page has instructions for Termux, so you can follow this tutorial on a phone. It works on modest hardware; the compiler is a single native program.

Now check both are on your PATH:

Bash
gleam --version
erl -noshell -eval 'io:format("OTP ~s~n", [erlang:system_info(otp_release)]), halt().'

Check it worked

gleam --version prints gleam 1.19.2. The erl command starts Erlang, prints its major version, such as OTP 29, and exits. If it shows a number lower than 28, an older Erlang is earlier on your PATH (on Ubuntu, often one installed with apt): remove it with sudo apt remove erlang-base, or follow the Ubuntu steps above, before you go on.

Step 2 · Create a project with gleam new

Gleam code always lives in a project, so there is no separate script mode to learn. Make a practice folder and create a project in it:

Bash
mkdir -p ~/hello-gleam-demo
cd ~/hello-gleam-demo
gleam new hello_gleam
cd hello_gleam
ls

Project names use lowercase letters, digits and underscores, because the name becomes a module name. gleam new creates:

  • gleam.toml, the project file: its name, version and dependencies.
  • src/hello_gleam.gleam, the main module. Every .gleam file under src/ is a module, named after its path.
  • test/hello_gleam_test.gleam, a first test.
  • README.md, a .gitignore and a .github folder with a ready-made workflow that runs your tests on GitHub.

Open gleam.toml. It looks something like this:

TOML
name = "hello_gleam"
version = "1.0.0"

[dependencies]
gleam_stdlib = ">= 0.44.0 and < 2.0.0"

[dev-dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"

[dependencies] lists the packages your code needs. gleam_stdlib is the standard library. Gleam's language itself is very small, so even printing text comes from a package. [dev-dependencies] are packages needed only while you develop, here gleeunit, the test runner. Each version range means "any release from the lower version up to, but not including, 2.0.0".

Check it worked

ls shows README.md, gleam.toml, src and test. gleam.toml starts with name = "hello_gleam" and lists gleam_stdlib and gleeunit.

Step 3 · Write and run Hello World

Replace src/hello_gleam.gleam with this, so you know exactly what is in it. On Windows, open the file in your editor and paste the five lines between the GLEAM markers.

Bash
cat > src/hello_gleam.gleam <<'GLEAM'
import gleam/io

pub fn main() -> Nil {
  io.println("Hello, world")
}
GLEAM
gleam run

Line by line:

  • import gleam/io makes the gleam/io module from gleam_stdlib available. You then refer to its functions by the last part of the name, io.
  • pub fn main() -> Nil { defines a function called main. pub makes it public, so code outside this module (here, gleam run) can call it. () means it takes no arguments, and -> Nil says it returns Nil, Gleam's value for "nothing useful". The type after -> is optional, because the compiler can work it out, but writing it on public functions helps readers.
  • io.println("Hello, world") prints the string and a new line. Strings in Gleam always use double quotes. io.println returns Nil, and a function returns the value of its last expression, so main returns Nil as promised. There is no return keyword.
  • } closes the function. Gleam uses braces, not indentation, to mark blocks, and gleam format lays the code out for you.

The first gleam run downloads gleam_stdlib and gleeunit from Hex, the package registry the BEAM languages share, and then compiles them along with your code. The download is small, and later runs use the copies already on disk, which helps on prepaid data. It then prints something like Compiled in 1.20s and Running hello_gleam.main, followed by your output.

Gleam compiled your module to Erlang, and Erlang compiled that to BEAM bytecode, the instructions the virtual machine runs. You can see the compiled module:

Bash
find build -name 'hello_gleam.beam'

Check it worked

gleam run ends with Hello, world. A build folder and a manifest.toml file have appeared. manifest.toml records the exact package versions that were downloaded, so the project builds the same way on another machine. find prints a path ending in ebin/hello_gleam.beam: the bytecode file the BEAM loaded to run your main function.

Step 4 · Add labelled arguments and pattern matching

Now write a module with two functions that show how Gleam code reads. Replace src/hello_gleam.gleam again:

Bash
cat > src/hello_gleam.gleam <<'GLEAM'
import gleam/int
import gleam/io
import gleam/string

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

pub fn describe(name: String) -> String {
  case name {
    "" -> "You did not give a name."
    "Ada" -> "Ada, like Ada Lovelace."
    "Dr " <> rest -> "A doctor called " <> rest <> "."
    _ -> name <> " has " <> int.to_string(string.length(name)) <> " letters."
  }
}

pub fn main() -> Nil {
  io.println(greet(greeting: "Good morning", name: "Ada"))
  io.println(describe("Ada"))
  io.println(describe("Dr Okafor"))
  io.println(describe("Adébáyọ̀"))
  io.println(describe(""))
}
GLEAM
gleam run

Line by line:

  • import gleam/int and import gleam/string bring in functions for whole numbers and strings.
  • pub fn greet(name name: String, greeting greeting: String) -> String defines a function with two labelled arguments. In name name: String, the first name is the label callers use and the second is the variable inside the function. Both arguments are String, and the function returns a String.
  • greeting <> ", " <> name joins strings. <> is Gleam's string join operator; + only works on integers, so "a" + "b" is a compile error.
  • greet(greeting: "Good morning", name: "Ada") calls the function with labels. Because each argument is labelled, the order does not matter and nobody can mix up the name and the greeting.
  • case name { ... } compares name against each pattern, top to bottom, and uses the first that matches. Each line is pattern -> result.
  • "" and "Ada" match those exact strings.
  • "Dr " <> rest matches any string that starts with Dr ` and binds the rest of it to `rest, so "Dr Okafor" gives rest the value "Okafor".
  • _ matches anything. The compiler checks that your patterns cover every possible value, so without this last line the code would not compile. You will see that error later.
  • string.length(name) counts letters as a reader sees them (graphemes), not bytes. Adébáyọ̀ has tone marks stored as extra characters, but it still counts as 7 letters. int.to_string turns the number into text, because Gleam never converts types for you.

Check it worked

gleam run prints five lines: Good morning, Ada, Ada, like Ada Lovelace., A doctor called Okafor., Adébáyọ̀ has 7 letters. and You did not give a name. Each describe call took a different branch of the case.

Step 5 · Handle a failure without exceptions

Converting text to a number can fail: "forty" is not a number. Many languages throw an exception for this. In Gleam, int.parse returns a Result: Ok(number) when it works and Error(Nil) when it does not. The type is Result(Int, Nil), and you cannot use the number until you have handled the error case.

Add a function to the end of src/hello_gleam.gleam, and a new main that uses it. To keep the file exact, write the whole module again:

Bash
cat > src/hello_gleam.gleam <<'GLEAM'
import gleam/int
import gleam/io
import gleam/string

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

pub fn describe(name: String) -> String {
  case name {
    "" -> "You did not give a name."
    "Ada" -> "Ada, like Ada Lovelace."
    "Dr " <> rest -> "A doctor called " <> rest <> "."
    _ -> name <> " has " <> int.to_string(string.length(name)) <> " letters."
  }
}

pub fn next_year(age_text: String) -> String {
  case int.parse(age_text) {
    Ok(age) -> "Next year you will be " <> int.to_string(age + 1) <> "."
    Error(Nil) -> "\"" <> age_text <> "\" is not a whole number."
  }
}

pub fn main() -> Nil {
  io.println(greet(greeting: "Good morning", name: "Ada"))
  io.println(next_year("41"))
  io.println(next_year("forty"))
}
GLEAM
gleam run

What is new:

  • case int.parse(age_text) { ... } matches on the Result. Ok(age) matches a success and binds the number inside to age. Error(Nil) matches a failure.
  • age + 1 works because age is an Int. If you tried age_text + 1, the compiler would stop you: age_text is a String.
  • "\"" is a string holding one double quote. The backslash means "this quote is part of the text".

Check it worked

The output ends with Next year you will be 42. and "forty" is not a whole number. The program did not crash on bad input, because the failure was an ordinary value it had to handle.

Step 6 · Run the tests with gleam test

Replace the generated test with tests for your functions:

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

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

pub fn greet_test() {
  assert hello_gleam.greet(name: "Ada", greeting: "Hello") == "Hello, Ada"
}

pub fn describe_doctor_test() {
  assert hello_gleam.describe("Dr Okafor") == "A doctor called Okafor."
}

pub fn next_year_rejects_words_test() {
  assert hello_gleam.next_year("forty") == "\"forty\" is not a whole number."
}
GLEAM
gleam test

Line by line:

  • import gleeunit brings in the test runner, and import hello_gleam brings in your module from src/.
  • pub fn main() -> Nil { gleeunit.main() } is the entry point gleam test calls. gleeunit.main() finds and runs every public function in the test folder whose name ends in _test.
  • assert ... == ... checks that the expression is True. If it is False, the test fails and gleeunit reports which assertion failed and the values it compared.

Now see a failure. Change the expected greeting so the test is wrong, and run the tests again:

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

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

pub fn greet_test() {
  assert hello_gleam.greet(name: "Ada", greeting: "Hello") == "Hello Ada"
}
GLEAM
Bash
gleam test

Put the correct tests back:

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

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

pub fn greet_test() {
  assert hello_gleam.greet(name: "Ada", greeting: "Hello") == "Hello, Ada"
}

pub fn describe_doctor_test() {
  assert hello_gleam.describe("Dr Okafor") == "A doctor called Okafor."
}

pub fn next_year_rejects_words_test() {
  assert hello_gleam.next_year("forty") == "\"forty\" is not a whole number."
}
GLEAM
gleam test

Check it worked

The first and last gleam test runs end with a short summary showing 3 tests and no failures. The run with "Hello Ada" fails and names greet_test, showing that the function really returned "Hello, Ada".

Step 7 · Compile to JavaScript (optional)

The same project can compile to JavaScript instead of Erlang. Running the result needs Node.js, which you may not have yet. On Ubuntu, install it from the Ubuntu packages (or use an installer from nodejs.org on macOS and Windows):

Bash
sudo apt update
sudo apt install -y nodejs
node --version

Then run your project on the JavaScript target:

Bash
gleam run --target javascript
find build -name 'hello_gleam.mjs'

--target javascript tells Gleam to compile to JavaScript modules and run main with Node.js. Erlang is not used at all for this run. The generated code goes in build/dev/javascript, next to build/dev/erlang, and the find command shows the .mjs file made from your module. To make JavaScript the default, add the line target = "javascript" near the top of gleam.toml.

Not every package works on both targets. A package that calls Erlang directly runs only on the BEAM, and one that calls browser or Node APIs runs only on JavaScript. Each package's page on packages.gleam.run says which targets it supports.

Check it worked

node --version prints a version number. gleam run --target javascript prints the same three lines as before, ending with "forty" is not a whole number., and find prints a path ending in javascript/hello_gleam/hello_gleam.mjs or similar.

Step 8 · Fix the errors beginners hit

Make a second, throwaway project to break on purpose, so your working one stays clean:

Bash
cd ~/hello-gleam-demo
gleam new oops
cd oops

A missing case branch. Remove the _ line from a case:

Bash
cat > src/oops.gleam <<'GLEAM'
import gleam/io

pub fn main() -> Nil {
  let name = "Ada"
  case name {
    "Ada" -> io.println("Hello, Ada")
  }
}
GLEAM
Bash
gleam build

The compiler refuses with an error titled something like Inexhaustive patterns, and lists a pattern you did not cover, such as _. Add _ -> io.println("Hello, stranger") as the last branch. This check is how Gleam avoids crashes from values nobody planned for.

The wrong type. io.println takes a String, so a number is an error:

Bash
cat > src/oops.gleam <<'GLEAM'
import gleam/io

pub fn main() -> Nil {
  io.println(42)
}
GLEAM
Bash
gleam build

The error is titled Type mismatch, points at 42, and says it expected String but found Int. Write io.println(int.to_string(42)) and add import gleam/int at the top.

Running gleam outside a project. Commands such as gleam run and gleam test look for gleam.toml in the current folder or a folder above it. If you see an error about a missing gleam.toml, cd into the project folder first.

An Erlang that is too old. If Gleam reports that your Erlang/OTP version is not supported, or packages fail to compile with strange Erlang errors, check erl as in the first step and install OTP 28 or 29 as shown there.

When you have finished, remove the practice folder:

Bash
cd ~
rm -rf ~/hello-gleam-demo

Check it worked

The missing branch gives an Inexhaustive patterns error and builds once you add _ ->. io.println(42) gives a Type mismatch error. After the last command, ls ~ no longer shows hello-gleam-demo.

Next steps

  • See another language on the BEAM, with the same runtime but dynamic types and a Ruby-like syntax: Hello World in Elixir.
  • Meet the language Gleam compiles to, and read the generated .erl file with new eyes: Hello World in Erlang.
  • Try Elm, the typed front-end language whose architecture Lustre follows, and which is also known for friendly compiler messages: Hello World in Elm.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.