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) 
  user.to_string(todo)
  

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 💬

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 
  user.to_string(todo)
  

pub fn happy_birthday_mom() 🔥

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 
  user.to_string(todo)
  

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() 🔥

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 🔥

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 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
    
  }
}

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: