Single file Gleam BEAM programs with escript

Gleam is a type safe and scalable language for the Erlang virtual machine and JavaScript runtimes. Today Gleam v1.17.0 has been published.

Gleam Gathering

But first: the first videos from the first ever all-Gleam conference have been released! You can view them on the Gleam Gathering YouTube account. The event was a roaring success and loads of fun. Stay tuned for news of the next one in 2027!

Right, back to the release coverage.

BEAM escripts

When running on the Erlang virtual machine Gleam code is compiled to a series of .beam files, each of which contains the bytecode for a single Gleam module. This works fine for programs distributed or installed using package managers, containers, or other such systems, but having many files to share is a little inconvenient for sharing small command-line programs.

In the JavaScript world this problem is solved using a "bundler", a program that takes many JavaScript modules and combines them into a single file. This single file can be copied to and run on any computer that has a JavaScript runtime installed (such as NodeJS, Deno, or Bun). Erlang has a similar solution: escripts. Much like a JavaScript bundle, an escript is a single file that contains all the modules of a program in the form of pre-compiled bytecode, and it can be run on any computer that has Erlang installed.

The Erlang build tool has a convenient command for creating an escript, but for Gleam programmers the escript creation process has not been as straightforward. This release brings the gleam export escript command, which will compile the project, verify it has a valid main function, and build the escript file from the compiled bytecode.

louis ~/src/my_project $ gleam export escript
  Compiling gleam_stdlib
  Compiling my_project
   Compiled in 0.48s

Your escript has been generated to /home/louis/src/my_project/my_project.

louis ~/src/my_project $ ./my_project
Hello from my_project!

Highlight references

Gleam's language server provides IDE functionality for all editors that implement the language server protocol. This release adds support for the textDocument/documentHighlight feature, highlighting all references to a selected variable.

For example, in this code triggering it with the cursor over any instance of vec will result in these highlights:

fn to_cartesian(vec) {
//              ^^^
  let x = vec.rho * cos(vec.theta)
  //      ^^^           ^^^
  let y = vec.rho * sin(vec.theta)
  //      ^^^           ^^^
  #(x, y)
}

Thank you Gavin Morrow for this addition!

Constant todo expressions

Gleam's todo keyword is a placeholder expression that programmers can use when they have not-yet-finished code they wish to type-check or run. At compile time it outputs a warning to say that the code is incomplete, and if the code path with the todo expression is run then it will panic, exiting the program.

todo can now also be used in constant expressions. Since constant expressions are evaluated at compile time, when todo is used in a constant the program can no longer be run, but it can still be type checked and analysed.

This has also enabled us to upgrade the "Fill labels" code action so that it works with constants too. When run it fills in the missing labelled arguments from a record constructor. For example:

pub type Pokemon {
  Pokemon(number: Int, name: String, hp: Int)
}

pub const cleffa = Pokemon(number: 173)

In this code snippet we haven't specified the name and hp fields, that's an error! Triggering the "Fill labels" code action will result in the following:

pub const cleffa = Pokemon(number: 173, name: todo, hp: todo)

Thank you Giacomo Cavalieri!

Record update hovering

Hovering in your editor is a great way to gleam more information, with the language server showing the types, documentation, and other details of whatever is being hovered over.

Gleam's record update syntax is used to create a new record from an existing one, but with some fields updated with new values. When hovering over one of these the language server will now also show the remaining fields that have not been given new values, saving you from navigating to the definition to see what others you could set new values for.

pub type Person {
  Person(name: String, age: Int)
}

pub fn happy_birthday_mom() {
  let mom = Person(name: "Antonella", age: 60)
  Person(..mom, age: 61)
  //     ^^^^^ Hovering this will show:
  //           Unchanged fields:
  //           - name
}

Thank you Giacomo Cavalieri!

Unknown value import suggestions

In Gleam functions from other modules are almost always used in a qualified fashion, written as dict.fold rather than just fold. This is done so it is clearer to the reader where the function is defined and what it does, and to prevent redundant suffixes being added to function names to indicate what type they work with.

Sometimes the programmer may forget to write the module qualifier, resulting in a compile error due to there being no value with that name in scope. When this happens the compiler will now search in the imported modules for an appropriate value with that name, and suggest it as a position correction.

For example, for this invalid program:

import gleam/io

pub fn main() -> Nil {
  println("Hello, World!")
}

The compiler will display this error message:

error: Unknown variable
  ┌─ /path/to/project/src/project.gleam:4:3
  │
4 │   println("Hello, World!")
  │   ^^^^^^^

The name `println` is not in scope here.
Did you mean one of these:

    - io.println

Thank you raphrous!

Context aware type printing in warnings

Up until now when the name of a type is displayed in a warning it has been displayed using its canonical name, but this may not be how the programmer has referred to the type in the code. A type could be referred to in a qualified way such as accounting.Invoice, or the programmer could have aliased the type to a new name to make it easier to understand in the context of that code.

Types in warnings are now correctly qualified or aliased when displayed in warnings. For example, this code:

import user as visitor

pub fn main() {
  user.to_string(todo)
  |> io.println
}

Will produce the following warning:

warning: Todo found
  ┌─ /src/warning/wrn.gleam:4:19
  │
4 │     user.to_string(todo)
  │                    ^^^^ This code is incomplete

This code will crash if it is run. Be sure to finish it before
running your program.

Hint: I think its type is `visitor.User`.

Notice how the type hint is correctly qualified for the module the warning is raised in.

Thank you Giacomo Cavalieri!

JavaScript pattern matching optimisations

Gleam's case expression pattern matching may look like a linear search from the first to the last clause, but it compiles to an efficient decision tree that takes a "divide and conquer" approach to finding the matching clause.

Daniele Scaratti and Gavin Morrow have worked on further optimising the code generated for pattern matching when compiling to JavaScript, detecting and removing some redundant checks when working with the length of bit arrays, and making the code for assignments more compact. Thank you both!

Quiet development

When running the Gleam build tool it will print messages that show what it is doing.

louis ~/src/my_project $ gleam dev
  Compiling gleam_stdlib
  Compiling my_project
   Compiled in 0.48s
    Running my_project_dev.main
Hello, from my_project_dev!

The --no-print-progress flag can be used to disable this information, and with the release it is now accepted by the gleam dev command, which runs code in development mode.

louis ~/src/my_project $ gleam dev --no-print-progress
Hello, from my_project_dev!

Thank you Giacomo Cavalieri!

Outdated dependencies count

The gleam deps outdated command is used to see which dependencies of a package have newer versions that could be adopted. With this release it now includes a summary showing how many packages have newer versions available. For example:

louis ~/src/my_project $ gleam deps outdated
1 of 12 packages have newer versions available.

Package       Current  Latest
-------       -------  ------
gleam_stdlib  0.70.0   0.71.0

It is also helpful when no packages are outdated, as before some people were confused by the lack of anything being printed and were unsure if they had any outdated dependencies or not.

louis ~/src/my_project $ gleam deps outdated
0 of 12 packages have newer versions available.

Thank you Daniele Scaratti!

Better git repository detection

The gleam publish command now has better Git repository detection in monorepos, correctly identifying if the package is in a git repository even if the Gleam package being published is not located at the root of the repository.

Thank you Andrey Kozhev!

Further fault tolerance

Gleam's compiler implements fault tolerant compilation, enabling it to analyse and infer information about code even when it is in an invalid state. This is useful as it means the language server is always able to provide useful help to the programmer.

Giacomo Cavalieri has improved the fault tolerance for errors in the list-prepend syntax and the record update syntax. Thank you!

Remove redundant record update code action

The language server now has a code action to remove a redundant record update. For example:

pub type User {
  User(name: String, likes: List(String))
}

pub fn main() {
  let lucy = User(name: "Lucy", likes: ["Gleam", "Ice Cream"])
  let jak = User(..lucy, name: "Jak", likes: ["Gleam", "Dogs"])
  //             ^^^^^^ This record update is not needed!
}

This record update is not actually needed and will raise a warning; all fields are already specified. Triggering the code action anywhere on the expression will remove the unnecessary update:

pub type User {
  User(name: String, likes: List(String))
}

pub fn main() {
  let lucy = User(name: "Lucy", likes: ["Gleam", "Ice Cream"])
  let jak = User(name: "Jak", likes: ["Gleam", "Dogs"])
}

Thank you Giacomo Cavalieri!

Correct operator in guard expression code action

Gleam doesn't have overloading for its operators, so each one works with a specific type. This is beneficial as it removes ambiguity and helps the compiler reliably infer the types of all the values in the program without requiring additional annotations. Other languages approach this problem using sub-typing, but Gleam doesn't have sub-typing, so it uses unambiguous syntax instead.

Sometimes programmers new to Gleam can mix up operators, such as trying to use + to concatenate strings instead of Gleam's <>. When this happens Gleam will suggest the correct operator to the programmer and provide a language server auto-fix action to correct it. This is now also supported for guard expressions, so it can be triggered on the erroneous + in this code:

pub fn categorise() {
  case pokemon {
    Pokemon(name:, ..) if name == "rai" + "chu" -> todo
    _ -> todo
  }
}

Thank you Giacomo Cavalieri!

Pattern match on discarded value code action

Gleam implements exhaustiveness checking, so if a program fails to cover all the possible edge cases with its flow control a helpful error will be raised during compilation, showing the programmer what is missing.

The information that the compiler collects from the code for this feature also enables it to provide some very convenient time-saving language server code actions, such as "add missing patterns" and "pattern match on value". The latest of these is an action to expand a discard pattern in a case expression, replacing it with clauses to match what it was discarding.

pub fn list_names(x: Result(List(String), Nil)) {
  case x {
    Error(Nil) -> io.println("no names")
    Ok(_) -> todo
    // ^ Triggering the code action here
  }
}

Here the _ discard pattern is being used to match on any list. Triggering the code action on that pattern expands that clause to the 2 clauses with the patterns most commonly used with lists.

pub fn list_names(x: Result(List(String), Nil)) {
  case x {
    Error(Nil) -> io.println("no names")
    Ok([]) -> todo
    Ok([first, ..rest]) -> todo
  }
}

Thank you Giacomo Cavalieri!

Create unknown module code action

There are two types of programmers in this world: top-down, and bottom-up. A top-down programmer starts with the biggest picture and breaks it down into progressively smaller pieces, recursively implementing them until the lowest level is reached. A bottom-up programmer starts by making the smallest building blocks and composing them until they have a full working system.

This release brings a new code action that may be especially appreciated by top-down programmers: create module. This action is available any time that a module that does not exist is imported, and when run will create the missing module in the programmer's package.

For example, if import wobble/woo is added to src/wiggle.gleam, then a code action to create src/wobble/woo.gleam will be presented when triggered over import wobble/woo.

Thank you Cory Forsstrom!

Security fixes

Security researchers Abdelrahman Ahmed Aboelkasem, Aly, and evipepota, found some configuration validation related vulnerabilities in the Gleam build tool. Thankfully they are not too scary, and they have now been fixed. For details see CVE-2026-43965, CVE-2026-32685, and CVE-2026-42795.

The Erlang Ecosystem Foundation security team has been invaluable for their work securing the whole Erlang ecosystem, especially now that AI-based vulnerability detection tools become more effective. If you or your company is able, please offer them your support.

Thank you to all the researchers and remediators!

And more!

And a huge thank you to the bug fixers and experience polishers:

Andrey Kozhev, apsoras, Charlie Tonneslan, daniellionel01, Eyup Can Akman, Gavin Morrow, Giacomo Cavalieri, John Downey, Logan Bresnahan, Sahil Upasane, and Surya Rose.

For full details of the many fixes and improvements they've implemented, see the changelog.

Support Gleam

Gleam is not from big-tech and has not taken any VC funding. We rely entirely on the community for our livelihoods.

We have made great progress towards our goal of being able to appropriately pay the core team members, but we still have further to go. Please consider supporting the project or core team members Giacomo Cavalieri and Surya Rose on GitHub Sponsors.

Thank you to all our sponsors! And special thanks to our top sponsor:

Try Gleam