Skip to main content

Hello World (first programs) · Beginner · 16 min

Hello World in Elm: a web page with no runtime exceptions

By Padding · Updated 18 Nov 2026
Elm 0.19.3 · node:26 image (Debian)

You 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.

On this page

Elm is a small functional language for building web pages. You write Elm, and the compiler turns it into JavaScript that any browser runs. What makes it different from writing JavaScript directly is how much the compiler checks before anything reaches the browser. Elm has no null and no undefined, functions cannot change values in place, and every possible case must be handled. A value that might be missing has the type Maybe, and the compiler makes you say what happens when it is missing. The result is the claim on Elm's home page: programs that, in practice, do not crash with runtime exceptions.

Elm also gave front-end development a pattern that spread well beyond it. The Elm Architecture splits a program into a model (the data), an update function (how messages change the data) and a view (how the data looks). Redux, the JavaScript state library, names Elm as one of its main influences. You will build a small program in that shape in this tutorial.

Evan Czaplicki created Elm; the compiler's licence dates its copyright from 2012. Version 0.19.3, released in October 2026, changes the compiler's internals but not the language, so code written for 0.19.1 still compiles. Elm is used for front-end web apps, from small interactive widgets to large single-page apps. The education company NoRedInk is the best-known example of a large Elm code base in production. Elm's compiler error messages are also well known: they explain the problem in full sentences and usually suggest a fix.

In this tutorial you install the elm binary, create a project, compile a Hello World page, build a greeter that responds as you type, and then break the code on purpose to read a type error.

Step 1 · Install the elm binary

Elm is one program, elm. It contains the compiler, the package installer and a small development server. It is a single file with nothing else to install, and you do not need Node.js to use it.

Linux: download the compressed binary from the official Elm release on GitHub, unpack it, mark it as executable and move it onto your PATH. The case block picks the right file for your processor: x86_64 for most laptops and servers, aarch64 for ARM machines such as a Raspberry Pi 4 or 5.

Bash
case "$(uname -m)" in
  x86_64) asset=elm-0.19.3-linux-x64.gz ;;
  aarch64) asset=elm-0.19.3-linux-arm.gz ;;
  *) asset=unsupported ;;
esac
curl -fL -o elm.gz "https://github.com/elm/compiler/releases/download/0.19.3/$asset"
gunzip elm.gz
chmod +x elm
sudo mv elm /usr/local/bin/
elm --version

What each part does:

  • uname -m prints your processor type, and case sets asset to the matching file name. On any other processor, asset becomes unsupported and the download fails with a 404, so nothing is installed.
  • curl -fL -o elm.gz ... downloads the file. -L follows GitHub's redirect to the real download, -f makes curl fail on an error page instead of saving it, and -o elm.gz names the file. It is a one-off download of about 11 MB, worth doing on Wi-Fi if you pay for mobile data by the megabyte.
  • gunzip elm.gz unpacks it, leaving a file called elm.
  • chmod +x elm allows the file to run as a program.
  • sudo mv elm /usr/local/bin/ moves it into a folder on your PATH, so elm works from any folder.

A binary installed this way gets no updates from your package manager. To upgrade later, repeat these commands with the newer version number from the Elm releases page.

macOS and Windows: the same release page has an installer for each: installer-for-mac.pkg and installer-for-windows.exe. Run it, then open a new terminal.

Through npm: if you already use Node.js, npm install --global elm installs the same compiler. This is common in projects that already have a package.json, because it records the Elm version next to the other tools.

Check it worked

elm --version prints 0.19.3. If you see command not found, open a new terminal; if it still fails, check that /usr/local/bin/elm exists.

Step 2 · Create a project with elm init

Every Elm program lives in a project with an elm.json file. Make a practice folder and create a project in it:

Bash
mkdir -p ~/hello-elm-demo
cd ~/hello-elm-demo
Bash
elm init

elm init explains what it is about to do and asks Knowing all that, would you like me to create an elm.json file now? [Y/n]. Press Enter to accept. It then creates two things:

  • elm.json, the project file. It records the Elm version and the packages the project uses. A new project starts with elm/core (numbers, strings, lists), elm/html (building HTML) and elm/browser (running programs in a browser).
  • src/, an empty folder where your .elm files go.

Look at the file:

Bash
cat elm.json

The "direct" list holds packages your code imports. The "indirect" list holds packages those depend on, such as elm/virtual-dom. Elm pins an exact version of each, so the project builds the same way on any machine.

Check it worked

ls shows elm.json and src. elm.json contains "elm-version": "0.19.3" and lists elm/browser, elm/core and elm/html under "direct".

Step 3 · Write Hello World and compile it

Create src/Main.elm with four lines of code. On Windows, create the file in your editor and paste the lines between the ELM markers.

Bash
cat > src/Main.elm <<'ELM'
module Main exposing (main)

import Html exposing (text)

main =
    text "Hello, World!"
ELM
elm make src/Main.elm

Line by line:

  • module Main exposing (main) names this module Main and makes its main value visible to the outside. The module name must match the file name: Main lives in src/Main.elm.
  • import Html exposing (text) brings in the Html module from the elm/html package, and lets you write text instead of Html.text.
  • main = defines a value called main. Elm looks for main to know what to show. There are no parentheses and no return: main is simply equal to what follows.
  • text "Hello, World!" calls the function text with one argument. Elm calls functions with a space, not brackets and commas. text returns a piece of HTML holding the string. The body is indented under main =, and the indentation is required.

main here is not a list of instructions that run. It is a description of what the page contains. The Elm runtime, which the compiler adds to your output, turns that description into real HTML in the browser.

The first elm make downloads the three packages from package.elm-lang.org and keeps them in a .elm folder in your home directory. Later projects reuse that copy, so they compile without downloading again. Then it compiles your module and prints something like Success! Compiled 1 module. with a line showing Main ───> index.html.

Check it worked

elm make ends with Success!, and ls shows a new index.html file next to elm.json, plus an elm-stuff folder where Elm keeps build files. You never edit elm-stuff; it is safe to delete, and Elm rebuilds it.

Step 4 · Open the page and see what elm make produced

Open index.html in your browser: double-click it in your file manager, or drag it onto a browser window. There is no server to start.

index.html is a complete page in one file: a short HTML wrapper, the compiled JavaScript for your module, and the parts of the Elm runtime and packages your code uses. Look at the start and the size of the file:

Bash
head -c 300 index.html
echo
wc -c index.html

The browser tab shows Main, the module name, because elm make writes that as the page title. Most of the file is the runtime and package code. When you are ready to publish a real app, elm make src/Main.elm --optimize removes debugging help and produces smaller output, which matters for people on slow connections or older Android phones.

Check it worked

The browser shows Hello, World! as plain text in the top-left corner, and the tab is titled Main. head shows the file starts with <!DOCTYPE HTML> and a <head> section, and wc -c prints its size in bytes.

Step 5 · Build a greeter with The Elm Architecture

A page that never changes is a start. Now build one that responds as you type. Browser.sandbox is the simplest kind of interactive Elm program: it has a model, an update function and a view, and nothing else.

Create a second module, src/Greeter.elm, so your Hello World stays as it is:

Bash
cat > src/Greeter.elm <<'ELM'
module Greeter exposing (main)

import Browser
import Html exposing (Html, div, h1, input, label, text)
import Html.Attributes exposing (for, id, placeholder, value)
import Html.Events exposing (onInput)


type alias Model =
    { name : String }


init : Model
init =
    { name = "" }


type Msg
    = NameChanged String


update : Msg -> Model -> Model
update msg model =
    case msg of
        NameChanged newName ->
            { model | name = newName }


greeting : String -> String
greeting name =
    if String.isEmpty (String.trim name) then
        "Hello, World!"

    else
        "Hello, " ++ String.trim name ++ "!"


view : Model -> Html Msg
view model =
    div []
        [ label [ for "name" ] [ text "Your name " ]
        , input [ id "name", placeholder "Type your name", value model.name, onInput NameChanged ] []
        , h1 [] [ text (greeting model.name) ]
        ]


main : Program () Model Msg
main =
    Browser.sandbox { init = init, update = update, view = view }
ELM
elm make src/Greeter.elm --output=greeter.html

Read it from the top:

  • import Html exposing (Html, div, h1, input, label, text) brings in the HTML elements used below. Html.Attributes gives attributes such as id and value, and Html.Events gives onInput.
  • type alias Model = { name : String } describes the program's data: a record with one field, name, which is a String. The whole state of the program lives in this one value.
  • init : Model is a type annotation: it says init is a Model. The line below gives its value, a record with an empty name. Annotations are optional, because Elm works out types itself, but they make code easier to read and the error messages more precise.
  • type Msg = NameChanged String lists every message the program can receive. There is only one: the name changed, carrying the new text.
  • update : Msg -> Model -> Model takes a message and the current model and returns a new model. case msg of handles each kind of message. { model | name = newName } makes a copy of the record with name replaced; Elm never changes the old one.
  • greeting returns Hello, World! when the name is empty or only spaces, and Hello, <name>! otherwise. ++ joins strings. Every if must have an else, so the function always returns a string.
  • view : Model -> Html Msg turns the model into HTML. Each element function takes two lists: attributes first, then children. onInput NameChanged tells Elm to send NameChanged with the field's text every time the reader types.
  • main : Program () Model Msg wires the three parts together with Browser.sandbox.

The cycle runs like this: you type a letter, the browser fires an input event, Elm sends NameChanged "A" to update, update returns a new model, and Elm calls view with it and updates only the parts of the page that changed. Your code never touches the page directly.

--output=greeter.html writes this program to its own file, so index.html keeps your Hello World.

Check it worked

elm make prints Success! and a line ending in greeter.html. Open greeter.html in your browser. The heading says Hello, World!. Type a name in the box, for example Adébáyọ̀, and the heading changes with each letter to Hello, Adébáyọ̀!, tone marks included, since Elm strings are Unicode. Delete the name, or type only spaces, and it goes back to Hello, World!.

Step 6 · Break it on purpose and read the type error

The compiler is the part of Elm you will spend most time with, so it is worth seeing an error before you meet one by accident. Create a throwaway module that joins a string and a number:

Bash
cat > src/Oops.elm <<'ELM'
module Oops exposing (main)

import Html exposing (text)

main =
    text ("Your name has " ++ String.length "Ada" ++ " letters")
ELM
Bash
elm make src/Oops.elm --output=/dev/null

--output=/dev/null tells elm make to check the code without writing a file. On Windows, leave that flag off; the build fails either way.

The compiler refuses. Its message starts with a heading such as -- TYPE MISMATCH --- src/Oops.elm, shows the line with the problem underlined, and explains in a sentence that ++ can join String values but String.length "Ada" is an Int. It usually ends with a hint, such as a pointer to String.fromInt for turning the number into text. In JavaScript, the same mistake would silently produce text and carry on; in Elm, it never reaches the browser.

Apply the fix: turn the number into text with String.fromInt.

Bash
cat > src/Oops.elm <<'ELM'
module Oops exposing (main)

import Html exposing (text)

main =
    text ("Your name has " ++ String.fromInt (String.length "Ada") ++ " letters")
ELM
elm make src/Oops.elm --output=/dev/null

The brackets around String.length "Ada" matter: without them, Elm would read String.fromInt String.length "Ada" as passing two arguments to String.fromInt, which is another error.

Check it worked

The first elm make fails with a TYPE MISMATCH heading and an explanation of why ++ cannot join a String and an Int. The second prints Success!.

Step 7 · Fix the errors beginners hit

These are the messages you are most likely to see in your first week with Elm. Each has a heading in capitals, which is the quickest way to recognise it.

  • MODULE NAME MISMATCH. The first line says module Greeter but the file is src/greeter.elm, or the reverse. Module names start with a capital letter and match the file name exactly, case included.
  • Indentation errors. If the body of main = starts in the first column, the compiler reports that it found something unexpected and asks you to indent it. Indent the body of every definition, and use spaces, not tabs; Elm rejects tabs.
  • MODULE NOT FOUND. import Http fails until the project has the elm/http package: the compiler says you are trying to import an Http module it cannot find. Run elm install elm/http in the project folder; it adds the package to elm.json after asking you to confirm.
  • elm.json not found. elm make looks for elm.json in the current folder and the folders above it. If it reports that it cannot find one, cd into the project folder first.
  • MISSING PATTERNS. If you add a second message to type Msg but not a branch for it in update, the compiler lists the case you forgot. This is how Elm keeps the "no runtime exceptions" promise: there is no message the program cannot handle.

Remove the throwaway module, then rebuild both programs to confirm the project is clean:

Bash
rm src/Oops.elm
elm make src/Main.elm
elm make src/Greeter.elm --output=greeter.html

When you have finished with the practice project, delete the folder. The elm binary and the package cache in ~/.elm stay, ready for your next project.

Bash
cd ~
rm -rf ~/hello-elm-demo

Check it worked

Both elm make commands print Success!. After the last command, ls ~ no longer shows hello-elm-demo, and elm --version still prints 0.19.3.

Next steps

  • Compare Elm with the language it compiles to, and see how the browser runs it: Hello World in JavaScript.
  • Meet Haskell, the language Elm's syntax and type system come from, and the language its compiler is written in: Hello World in Haskell.
  • Try Gleam, another typed functional language that compiles to JavaScript, with a front-end framework in the style of The Elm Architecture: Hello World in Gleam.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.