Gleam First Program

Writing your first Gleam program is the fastest way to understand how the language works. This topic creates a new project, explains every file in it, and runs a working program that prints output to the screen.

Create a New Project

Open your terminal and run:

gleam new hello_world

The Gleam CLI creates a folder called hello_world with everything you need to start.

hello_world/
├── gleam.toml        ← project configuration
├── src/
│   └── hello_world.gleam   ← your main code file
└── test/
    └── hello_world_test.gleam  ← your test file

Understanding Each File

gleam.toml

This file is the project's identity card. It stores the project name, version, and dependencies.

name = "hello_world"
version = "1.0.0"

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

You rarely edit this file by hand. The gleam add command updates it automatically when you add new packages.

src/hello_world.gleam

This is where you write your program. Gleam generates a starting file with a simple working example.

import gleam/io

pub fn main() {
  io.println("Hello from hello_world!")
}

test/hello_world_test.gleam

This file holds tests for your code. Tests check that your functions do what you expect. You learn more about testing in a later topic.

Reading the Starter Code Line by Line

Line-by-Line Breakdown
──────────────────────────────────────────────────
import gleam/io
  → Load the "io" module from the standard library
  → "io" stands for input/output

pub fn main() {
  → "pub" means this function is public (visible outside this module)
  → "fn" means function
  → "main" is the name — Gleam always starts here
  → "()" means the function takes no arguments
  → "{" opens the function body

  io.println("Hello from hello_world!")
  → Call the "println" function from the "io" module
  → Pass the text string as an argument
  → This prints the text and adds a newline

}
  → Close the function body

Running the Program

Navigate into the project folder and run the program:

cd hello_world
gleam run

Gleam compiles the code and executes it. The terminal shows:

   Compiling hello_world
    Finished in 0.57s

Hello from hello_world!

The "Compiling" line appears every time you change your code. When nothing changed, Gleam skips compilation and runs immediately.

Modifying the Program

Open src/hello_world.gleam in your editor and change the message:

import gleam/io

pub fn main() {
  io.println("Gleam is awesome!")
  io.println("Let's learn more.")
}

Run it again:

gleam run

Output:

Gleam is awesome!
Let's learn more.

Each io.println call prints one line. Call it multiple times to print multiple lines.

Printing Different Values

Gleam's io module provides several print functions:

io Functions Reference
──────────────────────────────────────────────
Function          │ What it does
──────────────────┼───────────────────────────
io.println(text)  │ Print text + newline
io.print(text)    │ Print text, no newline
io.debug(value)   │ Print any value (for debugging)

Try this example:

import gleam/io

pub fn main() {
  io.print("Name: ")
  io.println("Gleam")
  io.debug(42)
  io.debug(True)
}

Output:

Name: Gleam
42
True

io.debug accepts any type — numbers, booleans, lists — which makes it useful when you want to quickly check a value during development.

Adding a Custom Function

Programs grow by adding more functions. Here is a program with a custom greeting function:

import gleam/io

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

pub fn main() {
  let message = greet("Priya")
  io.println(message)
}

How the Program Flows
──────────────────────────────────────────
main()
  │
  ├── calls greet("Priya")
  │       │
  │       └── returns "Hello, Priya!"
  │
  ├── stores result in  `message`
  │
  └── calls io.println(message)
            │
            └── prints: Hello, Priya!

The greet function takes a String (a text value) and returns a String. The arrow -> shows the return type. The <> operator joins strings together — it is Gleam's string concatenation operator.

Running Tests

Open test/hello_world_test.gleam. The starter file contains one basic test:

import gleeunit
import gleeunit/should

pub fn main() {
  gleeunit.main()
}

pub fn hello_world_test() {
  1
  |> should.equal(1)
}

Run the tests:

gleam test

Output:

   Compiling hello_world
    Finished in 0.45s

.
1 test, 0 failures

A dot represents a passing test. A letter "F" represents a failing test. All tests pass here.

Useful gleam CLI Commands

Command Reference
──────────────────────────────────────────────
gleam new <name>    Create a new project
gleam run           Compile and run the project
gleam test          Compile and run all tests
gleam build         Compile without running
gleam format        Format all .gleam files
gleam add <pkg>     Add a package dependency
gleam docs build    Build HTML documentation

What the Compiler Does

When you run gleam run, four things happen in sequence:

Compilation Pipeline
──────────────────────────────────────────────
Your .gleam file
      ↓
  1. Parsing    → Reads your code structure
  2. Type Check → Verifies all types are correct
  3. Code Gen   → Produces Erlang bytecode
  4. Execution  → BEAM VM runs the bytecode

If the type checker finds a problem in step 2, compilation stops and prints a clear error. You fix the error and run again. No broken program ever reaches step 4.

You now have a working Gleam program and understand the project layout. The next topic explains how Gleam organizes files and folders in real projects.