Skip to main content

Hello World (first programs) · Beginner · 16 min

Hello World in Erlang: modules, the shell and message passing

By Padding · Updated 18 Nov 2026
Debian 13 (erlang:29 image) · Erlang/OTP 29.1.2 · rebar3 3.27.0

You will install Erlang/OTP 29, write and compile a hello module, call it from the erl shell and from an escript, send a message between two processes, and create your first rebar3 project.

On this page

Erlang was built at Ericsson in the 1980s to run telephone switches: systems that must handle many thousands of calls at once and keep running while parts of them fail. That shaped everything about it. An Erlang program is made of many small processes that share no memory and talk only by sending each other messages. They are not operating system processes or threads; the Erlang runtime, called the BEAM, creates and schedules them itself, and each one starts with only a few kilobytes of memory.

Erlang comes as Erlang/OTP. Erlang is the language; OTP (originally the Open Telecom Platform) is the standard library and the set of tools that ship with it: the compiler, the interactive shell, libraries for servers and supervisors, and much more. When people say "OTP 29" they mean this whole bundle at version 29.

In this tutorial you install OTP, write a module and compile it to a .beam file, call it from the shell, run a script with escript, spawn a process and exchange a message with it, and create a project with rebar3, Erlang's build tool. The code was written for Erlang/OTP 29.1.2 and runs on OTP 27 and later.

Step 1 · Install Erlang/OTP

There are two good ways on Ubuntu or Debian. Pick one.

Option 1: the distribution package. This is the quickest download and apt keeps it patched. Ubuntu 26.04 packages OTP 27, which is two major versions behind but runs everything in this tutorial:

Bash
sudo apt update
sudo apt install -y erlang

Option 2: build OTP 29 with kerl. kerl is a small script that downloads the OTP source, compiles it, and lets you keep several versions side by side. Install the build tools, then fetch kerl into ~/.local/bin:

Bash
sudo apt update
sudo apt install -y curl git build-essential autoconf m4 libncurses-dev libssl-dev
mkdir -p ~/.local/bin
curl -fsSL -o ~/.local/bin/kerl https://raw.githubusercontent.com/kerl/kerl/master/kerl
chmod a+x ~/.local/bin/kerl
export PATH="$HOME/.local/bin:$PATH"

Build and install OTP 29.1.2, then activate it in the current shell:

Bash
kerl build 29.1.2 29.1.2
kerl install 29.1.2 ~/erlang/29.1.2
. ~/erlang/29.1.2/activate

The build takes several minutes, longer on a low-end laptop. kerl build names the build (the second 29.1.2), kerl install copies it to a folder you choose, and activate puts that folder first on your path. Add the . ~/erlang/29.1.2/activate line to ~/.bashrc so new terminals pick it up. A version built this way gets no apt security updates: to upgrade, repeat the two kerl commands with the newer version number and activate the new folder. On metered or prepaid data, option 1 downloads less, because kerl fetches the full source code.

On macOS, run brew install erlang. On Windows, download the 64-bit installer for OTP 29.1.2 from erlang.org/downloads and run it; then add its bin folder (inside the install folder, under C:\Program Files by default) to your PATH so erl works in a terminal.

Check it worked

Ask the runtime which OTP release it is:

Bash
erl -noshell -eval 'io:format("~s~n", [erlang:system_info(otp_release)]), halt().'

It prints 29 after option 2, or 27 after option 1 on Ubuntu 26.04. -noshell starts Erlang without the interactive shell, -eval runs the code in quotes, and halt() stops the runtime afterwards.

Step 2 · Write a hello module

Erlang code lives in modules, one per file. Make a folder for this tutorial and write a module called hello:

Bash
mkdir -p ~/erlang-demo
cd ~/erlang-demo
cat > hello.erl <<'ERL'
-module(hello).
-export([world/0, greet/1]).

world() ->
    io:format("Hello, world!~n").

greet(Name) ->
    io:format("Hello, ~ts!~n", [Name]).
ERL

Line by line:

  • -module(hello). names the module. It must match the file name without .erl, so module hello lives in hello.erl. Lines starting with - are attributes: instructions to the compiler rather than code that runs.
  • -export([world/0, greet/1]). lists the functions other modules and the shell may call. world/0 means "the function world that takes 0 arguments". In Erlang the number of arguments, the arity, is part of a function's name, so greet/1 and a greet/2 would be two different functions. Anything you leave out of the export list is private to the module.
  • world() -> starts a function with no arguments. The -> separates the function's head from its body.
  • io:format("Hello, world!~n") calls the function format in the standard module io. The colon is how you call a function in another module. ~n is a format directive that prints a newline.
  • The full stop after the body ends the function. Erlang reads punctuation like an English sentence: a comma separates expressions that run one after another, a semicolon separates alternative clauses of one function, and a full stop ends a whole form (a function or an attribute). Forgetting the full stop is the most common first error.
  • greet(Name) -> takes one argument. Name starts with a capital letter, which is what makes it a variable. A lowercase word such as hello or ok is an atom: a constant whose value is its own name.
  • "Hello, ~ts!~n" has a placeholder, ~ts, filled from the list [Name] that follows. ~ts prints text that may contain any Unicode character. The shorter ~s only handles characters up to code 255, so a Yoruba name such as Ọlá or a name in Amharic script fails with it. Use ~ts for text people type.

Check it worked

cat hello.erl prints the eight lines above, with a full stop at the end of each attribute and each function.

Step 3 · Compile and call it from the erl shell

Start the interactive shell from the same folder:

Bash
erl

It prints a banner starting Erlang/OTP 29 and a prompt 1>. Type each line below at the prompt, including the full stop, and press Enter:

Text
c(hello).
hello:world().
hello:greet("Ada").
q().

What you see is something like this:

Text
1> c(hello).
{ok,hello}
2> hello:world().
Hello, world!
ok
3> hello:greet("Ada").
Hello, Ada!
ok
4> q().
ok
  • c(hello) compiles hello.erl and loads it into the running shell. {ok,hello} is a tuple, a fixed group of values in curly brackets, here the atom ok and the module name.
  • hello:world() runs your function. It prints Hello, world!, and then the shell shows the function's return value. io:format returns the atom ok, which is why every greeting is followed by ok.
  • q() quits the shell.

If you press Enter without the full stop, the shell shows nothing new and waits: it thinks your expression is not finished. Type . and press Enter.

Compiling left a new file next to the source. Exit the shell and look:

Bash
ls

Check it worked

ls lists hello.beam next to hello.erl. A .beam file holds compiled bytecode for the BEAM, the same way a .class file holds bytecode for Java's virtual machine. The source stays as it is; the runtime loads the .beam file.

Step 4 · Try the shell, variables and strings

The shell evaluates any expression, not only calls to your modules. Start erl again and try these, one at a time:

Text
X = 5.
X + 1.
X = 6.
[104, 105].
"hi" =:= [104, 105].

You see something like:

Text
1> X = 5.
5
2> X + 1.
6
3> X = 6.
** exception error: no match of right hand side value 6
4> [104, 105].
"hi"
5> "hi" =:= [104, 105].
true

Two things here are specific to Erlang.

Variables bind once. = is not assignment; it is a match. The first time, X has no value, so the match binds it to 5. After that, X = 6 asks "does 6 match 5?", and it does not, so you get an error. To hold a new value, use a new name such as X2. This rule is why Erlang code has no surprise changes to shared state: once bound, a value never changes. In the shell, f(X). forgets X so you can bind it again; compiled modules have no such escape.

Strings are lists of character codes. "hi" is the list [104, 105], and =:= (exactly equal) returns true. The shell prints a list as a string when all its numbers look like printable characters. Erlang also has binaries, written <<"hi">>, which store text compactly as bytes; larger programs usually prefer them for text.

The shell is for trying things out. Variables you bind there disappear when you quit, and you cannot define a module there. Code you want to keep goes in a .erl file and is compiled.

Check it worked

X = 6. gives ** exception error: no match of right hand side value 6, and the last line prints true. Type q(). to leave the shell.

Step 5 · Run a script with escript

For small command-line tools you do not need to compile anything yourself. escript runs a file of Erlang code as a script. Write one that greets the name you pass, or the world if you pass none:

Bash
cd ~/erlang-demo
cat > greet.escript <<'ERL'
#!/usr/bin/env escript
main([]) ->
    io:format("Hello, world!~n");
main([Name | _]) ->
    io:format("Hello, ~ts!~n", [Name]).
ERL
chmod +x greet.escript
./greet.escript
./greet.escript Ada
escript greet.escript Grace

Line by line:

  • #!/usr/bin/env escript tells the system to run the file with escript, so ./greet.escript works once the file is executable. escript greet.escript works with or without that line, and is how you run it on Windows.
  • main is where an escript starts. It receives the command-line words as a list of strings.
  • main([]) -> is the first clause: it runs when the list is empty. It ends with a semicolon, because another clause of the same function follows.
  • main([Name | _]) -> is the second clause. [Name | _] is a pattern that matches a list with at least one item: the first item is bound to Name and _ ignores the rest. Erlang tries the clauses in order and runs the first whose pattern matches, which replaces the if you might write in other languages.
  • The full stop ends the whole function, after the last clause.

Since OTP 27, escript compiles the script before running it, so it runs at the same speed as a compiled module. If main returns normally the script exits with status 0; if it crashes, escript prints the error and exits with 127.

Check it worked

The three runs print Hello, world!, Hello, Ada! and Hello, Grace!.

Step 6 · Spawn a process and send it a message

Now the part Erlang is known for. Write a module that starts a second process, sends it some text, and waits for the reply:

Bash
cd ~/erlang-demo
cat > shout.erl <<'ERL'
-module(shout).
-export([start/1]).

start(Text) ->
    Pid = spawn(fun loop/0),
    Pid ! {self(), Text},
    receive
        {Pid, Reply} ->
            io:format("Reply from ~p: ~ts~n", [Pid, Reply])
    after 1000 ->
        io:format("No reply within a second~n")
    end.

loop() ->
    receive
        {From, Text} ->
            From ! {self(), string:uppercase(Text)}
    end.
ERL
erlc shout.erl
erl -noshell -eval 'shout:start("hello from the beam"), halt().'

This time you compiled with erlc, the command-line compiler, which makes shout.beam without opening a shell. Line by line:

  • spawn(fun loop/0) starts a new process that runs loop(), and returns its process identifier, or pid. loop does not need to be exported, because fun loop/0 refers to it from inside the module.
  • Pid ! {self(), Text} sends a message. ! is the send operator. The message is a tuple holding your own pid, from self(), so the other process knows where to reply, and the text. Sending never waits: the message goes into the other process's mailbox and your code carries on.
  • receive ... end waits for a message that matches one of its patterns. The pattern {Pid, Reply} uses Pid, which is already bound, so it only matches a reply from that exact process. Any other message stays in the mailbox. This is the bind-once rule from earlier, doing useful work.
  • after 1000 -> gives up after 1,000 milliseconds if no matching message arrives, so the program never hangs forever.
  • In loop/0, the second process waits for {From, Text}, uppercases the text with string:uppercase/1 and sends the result back to From, tagged with its own pid. Then the function ends, and so does the process.
  • ~p prints any Erlang value in readable form; here it prints the pid.

The two processes share no memory: the only way data got from one to the other was inside a message. That is what lets an Erlang system run hundreds of thousands of processes and lets one of them crash without corrupting the others.

Check it worked

The output is one line like Reply from <0.84.0>: HELLO FROM THE BEAM. The numbers in the pid differ from run to run; the uppercased text is what matters.

Step 7 · Create a project with rebar3

Single files are fine for learning. Real Erlang projects use rebar3, which creates the standard folder layout, compiles everything, fetches libraries and runs tests. Install it from the official build, which is itself an escript:

Bash
cd ~/.local/bin
curl -fsSLO https://s3.amazonaws.com/rebar3/rebar3
chmod +x rebar3
./rebar3 local install
export PATH="$HOME/.cache/rebar3/bin:$PATH"
cd ~/erlang-demo

rebar3 local install unpacks rebar3 into ~/.cache/rebar3 and prints the export PATH line to add to ~/.bashrc; rebar3 local upgrade updates it later. Once rebar3 is on your path you can delete ~/.local/bin/rebar3. On macOS, brew install rebar3 works too.

Create an application called hello_app, add your hello module to it and compile:

Bash
cd ~/erlang-demo
rebar3 new app hello_app
cd hello_app
find . -type f | sort
cp ../hello.erl src/
rebar3 compile
ls _build/default/lib/hello_app/ebin
erl -noshell -pa _build/default/lib/hello_app/ebin -eval 'hello:greet("rebar3"), halt().'

rebar3 new app writes a complete OTP application:

  • rebar.config is the project's settings file. Libraries you depend on go in its deps list.
  • src/hello_app.app.src describes the application: its name, version and the other applications it needs.
  • src/hello_app_app.erl and src/hello_app_sup.erl are the start module and a supervisor, the OTP process whose job is to restart other processes when they crash. You do not need them yet, but every OTP application has them.
  • .gitignore, README.md and LICENSE.md complete the project.

rebar3 compile compiles every module in src/, including the hello.erl you copied in, and puts the .beam files in _build/default/lib/hello_app/ebin. -pa adds that folder to the runtime's code path, so erl can find hello. For day-to-day work, rebar3 shell compiles the project and opens an erl shell with everything already loaded.

Check it worked

find lists the seven files above. rebar3 compile ends with a line like ===> Compiling hello_app, the ebin folder holds hello.beam, hello_app_app.beam, hello_app_sup.beam and hello_app.app, and the last command prints Hello, rebar3!.

Step 8 · Learn the common mistakes and clean up

These are the errors almost everyone meets in their first week:

  • A missing or misplaced full stop. In the shell, nothing happens until you type .. In a file, erlc reports syntax error before: and a line number; look at the end of the line before.
  • A comma where a semicolon belongs, or the reverse. Clauses of one function are separated by ;, expressions inside a body by ,.
  • A variable written in lowercase. greet(name) -> compiles, but name is an atom, so the clause only matches the atom name and any real string fails with no function clause matching.
  • Calling a function you did not export. The call fails with undef. Add it to -export and compile again.
  • The module name does not match the file name. c(hello) on a file that says -module(helo). fails, and the error names both.
  • Rebinding a variable, as you saw: use a new name instead.

Try the export one now. Calling a function that does not exist, or is not exported, fails like this:

Bash
cd ~/erlang-demo
erl -noshell -eval 'try hello:secret() catch error:undef -> io:format("undef: hello:secret/0 is not exported~n") end, halt().'

Where Erlang is used

Erlang still runs in telecoms equipment, where it started. It is behind messaging systems and chat back ends that hold millions of open connections, and behind RabbitMQ, the widely used message broker, which is written in Erlang. The BEAM also runs other languages: Elixir and Gleam compile to the same .beam files and can call Erlang modules directly, so what you learnt here carries over.

When you are done, remove the tutorial folder:

Bash
cd ~
rm -rf ~/erlang-demo

Check it worked

The try command prints undef: hello:secret/0 is not exported. After the cleanup, ls ~/erlang-demo reports No such file or directory, and erl -noshell -eval 'io:format("~s~n", [erlang:system_info(otp_release)]), halt().' still prints your OTP release, because deleting a project does not touch Erlang itself.

Next steps

  • Meet the language most people now reach the BEAM through: Hello World in Elixir.
  • Try a statically typed language on the same runtime: Hello World in Gleam.
  • See the logic language whose syntax inspired Erlang's: Hello World in Prolog.
  • Read the official Getting Started with Erlang guide at erlang.org/doc, which builds on processes and messages with links, monitors and distributed nodes.

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.