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
gleambinary 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.
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.sha256sha256sum -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.
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.gzLine 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 theerlcheck below sayscommand not found, also runbrew 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:
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:
mkdir -p ~/hello-gleam-demo
cd ~/hello-gleam-demo
gleam new hello_gleam
cd hello_gleam
lsProject 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.gleamfile undersrc/is a module, named after its path.test/hello_gleam_test.gleam, a first test.README.md, a.gitignoreand a.githubfolder with a ready-made workflow that runs your tests on GitHub.
Open gleam.toml. It looks something like this:
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.
cat > src/hello_gleam.gleam <<'GLEAM'
import gleam/io
pub fn main() -> Nil {
io.println("Hello, world")
}
GLEAM
gleam runLine by line:
import gleam/iomakes thegleam/iomodule fromgleam_stdlibavailable. You then refer to its functions by the last part of the name,io.pub fn main() -> Nil {defines a function calledmain.pubmakes it public, so code outside this module (here,gleam run) can call it.()means it takes no arguments, and-> Nilsays it returnsNil, 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.printlnreturnsNil, and a function returns the value of its last expression, somainreturnsNilas promised. There is noreturnkeyword.}closes the function. Gleam uses braces, not indentation, to mark blocks, andgleam formatlays 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:
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:
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 runLine by line:
import gleam/intandimport gleam/stringbring in functions for whole numbers and strings.pub fn greet(name name: String, greeting greeting: String) -> Stringdefines a function with two labelled arguments. Inname name: String, the firstnameis the label callers use and the second is the variable inside the function. Both arguments areString, and the function returns aString.greeting <> ", " <> namejoins 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 { ... }comparesnameagainst each pattern, top to bottom, and uses the first that matches. Each line ispattern -> result.""and"Ada"match those exact strings."Dr " <> restmatches any string that starts withDr ` and binds the rest of it to `rest, so"Dr Okafor"givesrestthe 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_stringturns 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:
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 runWhat is new:
case int.parse(age_text) { ... }matches on theResult.Ok(age)matches a success and binds the number inside toage.Error(Nil)matches a failure.age + 1works becauseageis anInt. If you triedage_text + 1, the compiler would stop you:age_textis aString."\""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:
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 testLine by line:
import gleeunitbrings in the test runner, andimport hello_gleambrings in your module fromsrc/.pub fn main() -> Nil { gleeunit.main() }is the entry pointgleam testcalls.gleeunit.main()finds and runs every public function in thetestfolder whose name ends in_test.assert ... == ...checks that the expression isTrue. If it isFalse, 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:
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"
}
GLEAMgleam testPut the correct tests back:
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 testCheck 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):
sudo apt update
sudo apt install -y nodejs
node --versionThen run your project on the JavaScript target:
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:
cd ~/hello-gleam-demo
gleam new oops
cd oopsA missing case branch. Remove the _ line from a case:
cat > src/oops.gleam <<'GLEAM'
import gleam/io
pub fn main() -> Nil {
let name = "Ada"
case name {
"Ada" -> io.println("Hello, Ada")
}
}
GLEAMgleam buildThe 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:
cat > src/oops.gleam <<'GLEAM'
import gleam/io
pub fn main() -> Nil {
io.println(42)
}
GLEAMgleam buildThe 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:
cd ~
rm -rf ~/hello-gleam-demoCheck 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
.erlfile 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.
Related tutorials
- Hello World in Elixir: iex, scripts, Mix and your first processYou will install Elixir 1.20 on Erlang/OTP 29, print Hello World in iex and from a script, build and test a small Mix project, and start processes that send messages back to you.
- Hello World in Erlang: modules, the shell and message passingYou will install Erlang/OTP 29, write and compile a hello module, call it from the erl shell and from an escript, send a message between two processes, and create your first rebar3 project.
- Hello World in Elm: a web page with no runtime exceptionsYou will install Elm 0.19.3, compile a Hello World page with elm make, build a greeter that updates as you type using The Elm Architecture, and read and fix a compiler type error.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials