Getting Gleam Running

Gleam exists because Erlang syntax looks like it was designed to torture developers. Louis Pilfold, Gleam's creator, got tired of writing {ok, Value} = some_function() for every damn function call. Gleam 1.0 dropped in March 2024 - I've been using it since version 0.8 and it's finally stable enough that I won't get fired for suggesting it.

What Gleam Actually Fixes

Three weeks ago my Node.js API crashed in production because someone passed null to a function expecting a string. No type checking, no warning, just a silent failure that took down order processing for 2 hours. Gleam won't let you deploy code with that kind of stupidity.

When Gleam's compiler yells at you, it actually tells you what's wrong. Last week I had a type mismatch error - instead of getting cryptic bullshit like "error TS2322" it showed me exactly what types were expected vs what I provided. Fixed in 30 seconds instead of searching through 47 Stack Overflow answers.

The BEAM Runtime Advantage

BEAM was built for telecom companies that needed 99.9% uptime or people died. WhatsApp scaled to 900M users with 50 engineers because BEAM doesn't fall over when you get traffic spikes. Meanwhile I've seen Java APIs crash from 100 concurrent connections because someone fucked up the thread pool configuration.

Here's why BEAM doesn't suck:

• Actor model processes that use 2KB of memory each (not Java threads that start at 8MB and grow)
• Supervisor trees restart crashed processes without killing your whole app (learned this during a production incident where only one feature broke instead of everything)
• Hot code deployment that I've actually used in production without downtime (still feels like black magic)
• Built-in clustering - servers just know about each other without Consul or etcd bullshit

My last Node.js project started dropping connections at 1,000 concurrent users. Same logic in Elixir handled 50,000 users on the same hardware. BEAM is legitimately different.

Why Types Don't Suck Here

Rust's borrow checker makes me want to throw my laptop out the window. Haskell's type system needs a PhD to understand. Gleam just prevents the dumb bugs without making me hate my life.

When you screw up, Gleam shows you exactly where and how to fix it. No Googling "how to fix lifetime annotation in async function" for 3 hours.

Compile to Whatever You Want

Your Gleam code compiles to either:

• Erlang: All the BEAM runtime benefits, OTP supervision trees, the works
• JavaScript: Runs anywhere JS runs - browsers, Node, Deno, edge functions

I've used the same validation logic in both my API (compiled to Erlang) and frontend (compiled to JS). No rewriting, no "frontend validation is different from backend validation" bullshit.

Library Ecosystem Reality

Gleam's package ecosystem is tiny. But here's the thing - it can use any Erlang or Elixir library through FFI. Phoenix web framework? Works. Postgrex database driver? Works. That Redis library your entire architecture depends on? Probably works.

I've wrapped Erlang crypto functions, used Elixir HTTP clients, and called into weird telecom libraries from the 1990s. If it runs on BEAM, Gleam can use it. Check the awesome-gleam list but don't expect to find everything you need yet.

The real question isn't whether Gleam is worth learning - it's whether you're tired of debugging the same stupid runtime errors over and over. If you're ready to let the compiler catch your bugs before they hit production, let's get this thing installed.

Installation works 80% of the time. The other 20% will make you question why you didn't stick with Python. Here's what actually happens and why computers hate us.

macOS Installation

Homebrew (works until it doesn't):

brew install gleam

This works great until macOS updates and breaks everything. I've reinstalled Gleam 5 times this year because Sonoma decided to randomly declare my Erlang build "incompatible" with system libraries. Apple broke something in 14.3.1 that fucked up BEAM apps for weeks.

MacPorts if you hate yourself:

sudo port install gleam

Takes 45 minutes to compile everything from source. But hey, at least it doesn't randomly break when Apple releases point updates. Used this during the macOS Ventura fiasco when Homebrew was fucked for 3 weeks.

Linux Installation

Every distro except Ubuntu: Use Homebrew because native package managers are a nightmare:

## Install Homebrew first (yes, on Linux, shut up)
/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"
brew install gleam

Arch Linux (because of course you use Arch):

yay -S gleam

The AUR maintainer randomly vanished for 2 months in 2024. Gleam 0.32 was stuck for 6 weeks because the PKGBUILD hadn't been touched since 2023. I ended up maintaining my own fork just to get security updates.

Alpine/Docker (actually works):

apk add gleam

Fedora (COPR roulette):

sudo dnf copr enable frostyx/gleam
sudo dnf install gleam

COPR repos are maintained by volunteers who have real jobs. The current repo hasn't been updated since Gleam 1.8 and the maintainer's last commit was 6 months ago.

Ubuntu: Just don't. The official repos have Gleam 0.18 from 2021. Use Homebrew or compile from source like a masochist.

Windows Installation

Scoop (least terrible option):

scoop install gleam

If you don't have Scoop, install it first. It's the only Windows package manager that doesn't fuck up your PATH every other Tuesday.

Manual installation: Download from GitHub releases and prepare for PATH hell. You'll add the binary, restart your terminal 3 times, reboot Windows twice, and it'll still claim gleam doesn't exist. I spent 4 hours last month debugging this exact issue for a coworker.

Verification

gleam --version
erl -version  # Verify Erlang is working

Expected output:

gleam 1.12.0
Erlang (SMP,ASYNC_THREADS) (BEAM) emulator version 26.2

Common issues that will ruin your day:

• gleam: command not found - PATH is fucked, shell cache is stale, or the binary landed in /usr/local/bin instead of /opt/homebrew/bin
• Erlang version 25.3 expected, found 24.1 - You've got Homebrew Erlang, system Erlang, AND kerl Erlang all fighting for control
• Command exists in PATH but shell can't find it - Classic Windows. Restart PowerShell, restart Explorer, sacrifice a rubber duck, reboot twice

Editor Setup

VS Code:

1. Install the Gleam extension
2. Enable format-on-save in settings
3. The language server connects automatically. If it doesn't, restart VS Code.

Other editors:

• Vim: gleam.vim for syntax highlighting
• Emacs: gleam-mode
• Sublime: sublime-text-gleam

Language server support provides decent error highlighting and autocompletion.

Let's Actually Build Something

Create a project:

gleam new my_first_project
cd my_first_project

This spits out a basic project structure. It's clean, minimal, and doesn't come with 47 configuration files like some frameworks I could mention:

my_first_project/
├── gleam.toml          # Project config (not 500 lines of XML)
├── manifest.toml       # Lock file (like package-lock.json but sane)
├── README.md           # Obligatory README
├── src/
│   └── my_first_project.gleam  # Your code goes here
└── test/
    └── my_first_project_test.gleam  # Tests (you'll write them, right?)

Run it:

gleam run

If this fails with cryptic Erlang errors, you're in the 10% where installation has issues.

What You Actually Got

gleam.toml - Clean configuration:

name = \"my_first_project\"
version = \"1.0.0\"

[dependencies]
gleam_stdlib = \">= 0.38.0 and < 2.0.0\"  # Standard library, always needed

Simple and clear compared to Maven XML or complex package.json files.

No complex configuration options. No plugins. No build phases. Just dependencies and metadata.

src/my_first_project.gleam - Your actual program:

import gleam/io

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

Simple. No classes, no public static void main, no framework initialization. Just a function that prints output.

Run gleam run and if everything worked, you'll see your message. If it didn't work, you're in the 10% of installations with issues.

If gleam run fails with cryptic BEAM errors, your Erlang installation is completely fucked. Run erl -version first - if that crashes, you're in dependency hell. Last month I had 3 different Erlang versions from Homebrew, system packages, AND kerl, and Gleam kept picking OTP 23 from 2020 for some reason. Took me 6 hours to trace down which symlink was pointing where. Deleted everything and started over with just Homebrew.

Forget "Hello World" - let's build something that doesn't make you want to delete your code. We'll make a CLI tool for reading environment variables because I'm tired of debugging shell scripts that break when $HOME is empty.

Adding Dependencies (The Non-Nightmare Version)

gleam add argv envoy

Unlike npm, this doesn't download 500MB of dependencies to print "Hello World". Your `gleam.toml` gets two lines:

[dependencies]
gleam_stdlib = ">= 0.38.0 and < 2.0.0"
argv = ">= 1.0.0 and < 2.0.0"      # Command line args
envoy = ">= 1.0.0 and < 2.0.0"     # Environment variables

Version ranges actually work here. I haven't had a dependency break my build in 6 months, which is a personal record coming from JavaScript land.

The Code (That Won't Make You Cry)

Replace the hello world template with something actually useful:

import argv
import envoy
import gleam/io
import gleam/result
import gleam/list

pub fn main() {
  case argv.load().arguments {
    ["get", name] -> get_environment_variable(name)
    ["list"] -> list_common_variables()
    _ -> show_usage()  // For invalid commands
  }
}

fn get_environment_variable(name: String) -> Nil {
  let value = envoy.get(name) 
    |> result.unwrap("Environment variable not set")
  
  io.println(format_variable(name, value))
}

fn list_common_variables() -> Nil {
  let common_vars = ["PATH", "HOME", "USER", "SHELL"]
  
  common_vars
  |> list.each(fn(var) { get_environment_variable(var) })
}

fn show_usage() -> Nil {
  io.println("Usage:")
  io.println("  gleam run -- get <VARIABLE_NAME>")
  io.println("  gleam run -- list")
  io.println("")
  io.println("Examples:")
  io.println("  gleam run -- get PATH")
  io.println("  gleam run -- list")
}

fn format_variable(name: String, value: String) -> String {
  name <> "=" <> value
}

What's actually happening here:

• Pattern matching on command line args (no giant if/else chains)
• Error handling with `Result` types (no try/catch nightmare)
• Pipe operator makes the code read left to right (revolutionary, I know)

Testing This Thing

Get a specific variable:

gleam run -- get PATH

List common variables:

gleam run -- list

Trigger the help text (because you forgot the syntax already):

gleam run

If it works, great. If it crashes with badmatch errors, welcome to Erlang's completely useless error messages. {badmatch,{error,enoent}} means "file not found" but you'll spend 30 minutes on Stack Overflow figuring that out. BEAM error messages were designed by sadists.

What Makes This Code Not Suck

Pattern Matching (The Good Kind)

Look at this beauty:

case argv.load().arguments {
  ["get", name] -> get_environment_variable(name)  // Exact match
  ["list"] -> list_common_variables()              // Simple match  
  _ -> show_usage()                                 // Everything else
}

No giant switch statements full of null checks. The compiler forces you to handle all cases, which annoyed me for the first week until I realized it prevents the stupid bugs that crash in production.

Pipe Operator (Finally, Readable Code)

Instead of this nested nightmare:

result.unwrap(envoy.get(name), "Not set")

You get this left-to-right flow:

envoy.get(name) |> result.unwrap("Not set")

Your brain reads it like: "Get the environment variable, then unwrap it with a default."

No Exceptions (Finally)

Gleam doesn't have exceptions. Environment variable doesn't exist? You get a Result type:

// envoy.get() returns Result(String, Nil) - it tells you it might fail
let value = envoy.get(name) |> result.unwrap("Environment variable not set")

No more try/catch blocks wrapping every function call. No more Cannot read property 'foo' of undefined crashing user checkout flows at 2am on Black Friday. The type system forces you to handle failures explicitly, which feels annoying for about 2 weeks until you realize it prevents 90% of the production bugs that used to ruin my weekends.

What's Next (The Stuff You'll Actually Need)

Tests (You Know, Those Things You Should Write)

Put this in test/my_first_project_test.gleam:

import gleeunit
import gleeunit/should
import my_first_project

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

pub fn format_variable_test() {
  my_first_project.format_variable("TEST", "value")
  |> should.equal("TEST=value")
}

Run them:

gleam test

The test runner actually works and gives you useful output. Shocking, I know.

Building for Production (The Moment of Truth)

gleam build

This compiles to BEAM bytecode. No giant binaries, no weird runtime dependencies, just efficient code that runs on the battle-tested Erlang VM.

Honestly? After spending 3 years debugging Node.js memory leaks and random Java OutOfMemoryErrors at 3am, Gleam feels like cheating. BEAM apps just fucking stay up. The type system catches the dumb bugs before they hit prod, and when something does break, it fails fast instead of limping along corrupting user data for 6 hours before anyone notices.

I haven't been woken up by production alerts in 8 months. That's a personal record since I started writing server code.

You're now armed with enough Gleam to be dangerous. But if you want to go deeper, you'll need to know where to find help when things inevitably get weird.