Welcome to Livebook

Basic usage

Livebook is a tool for crafting interactive and collaborative code notebooks.

Each notebook consists of a number of cells, which serve as primary building blocks. There are Markdown cells (such as this one) that allow you to describe your work and Code cells to run your Elixir code!

To insert a new cell move your cursor between cells and click one of the revealed buttons. 👇

2 + 2

# This is a Code cell - as the name suggests that's where the code goes.
# To evaluate this cell, you can either press the "Evaluate" button above
# or use `Ctrl + Enter` (or Cmd + Enter on a Mac)!

message = "hey there, grab yourself a cup of 🍵"

Subsequent cells have access to the bindings you’ve defined:

String.replace(message, "🍵", "☕")

Note however that bindings are not global, so each cell sees only stuff that goes above itself. This approach helps to keep the notebook clean and predictable as you keep working on it. Furthermore, Livebook tracks which variables are used by each cell and in order to detect which cells become stale. For example, try changing the message variable and you will see the status indicator on the bottom right of the second cell become yellow.

Sections

You can leverage so called sections to nicely group related cells together. Click on the “Book” icon () in the sidebar to reveal a list of all sections. As you can see, this approach helps to easily jump around the notebook, especially once it grows.

Let’s make use of this section to see how output is captured!

cats = ~w(😼 😹 😻 😺 😸 😽)

for _ <- 1..3 do
  cats
  |> Enum.take_random(3)
  |> Enum.join(" ")
  |> IO.puts()
end

Branching sections

Additionally, you can make a section branch out from any previous regular section. Hover over the section name to reveal available actions and click on the branch icon to select the parent section.

You still have access to all the previous data:

{message, cats}

The important characteristic of a branching section is that it runs independently from other sections and as such is well suited for running long computations “in background”.

Process.sleep(300_000)

Having this cell running, feel free to insert another Code cell in the section below and see it evaluates immediately. Crashes in branched sections also have limited scope and will affect only the branched section.

Saving notebooks

By default, notebooks are stored in a temporary directory, which is fine for interactive hacking, but oftentimes you will want to save your work for later. Such can be done by clicking on the “Disk” icon () in the bottom-right corner and selecting the file location.

Once saved, you can access the location of the current .livemd file and its current directory using __ENV__ and __DIR__ variables:

IO.puts(__ENV__.file)
IO.puts(__DIR__)

Notebooks are stored in live markdown format, which is the Markdown you know, with just a few assumptions on how particular elements are represented. Thanks to this approach you can easily keep notebooks under version control and get readable diffs. You can also easily preview those files and even edit them in a text editor.

Keyboard shortcuts

Once you start using notebooks more, it’s gonna be beneficial to optimise how you move around. Livebook leverages the concept of navigation/insert modes and offers many shortcuts for common operations. Make sure to check out the shortcuts by clicking the “Keyboard” icon () in the sidebar or by pressing ?.

Autocompletion

Elixir code cells also support autocompletion. Autocompletion happens automatically as you type but you can explicitly trigger it with ctrl + ␣. You must start the runtime, by executing any cell at least once, for the autocompletion engine to load.

Let’s try autocompleting the code below to System.version(). First put the cursor after the System below and type .:

System.version()

You should have seen the editor listing many different options, which you can use to find version. Executing the code will return the Elixir version.

Note you can also press tab to cycle across the completion alternatives.

Storing secrets in Hubs

Livebook is capable of managing all secrets that belong to a notebook. Secrets can be read by Elixir Code cells and also by Smart cells - a feature we will explore in future sections.

Secrets are environment variables starting with the LB_ prefix. For example, let’s try reading an environment variable:

System.fetch_env!("LB_MY_SECRETZ")

Execute the cell above. If the secret is not available, Livebook will automatically detect it and prompt you to add the missing secret. You can save a secret in two different locations:

• in your notebook session: once you restart the session or your Livebook, the secret will be gone and you must input it again

• in a Hub: a Hub is a location where you can safely store secrets, deploy notebooks, and more. Every Livebook application has a personal Hub that can store secrets and stamp notebooks

Once the secret is saved, execute the cell again and it will evaluate successfully.

If you save secrets in your Hub, you will only need to input the secret once in notebooks authored by you. You can manage all of your secrets by clicking the lock icon () on the sidebar.

Markdown extensions

Livebook also include supports for links, mathematical expressions, and Mermaid diagrams.

Links

It is possible to link between Livebooks using Markdown’s link syntax. For example, [next chapter](chapter_2.livemd) could be used to link to a Livebook named chapter_2.livemd in the same directory as the current notebook. Once clicked, Livebook will automatically open up a new session to execute the linked notebook.

another notebook

Math expressions

Livebook uses $\TeX$ syntax for math inside your Markdown cells. It supports both inline math, like $e^{\pi i} + 1 = 0$, as well as display math:

$$ S(x) = \frac{1}{1 + e^{-x}} = \frac{e^{x}}{e^{x} + 1} $$

To write your own, put your math expressions between \$ signs for inline math or \$\$ if you want display math. You can double click the formulas above to see how they are written.

You can explore all supported expressions in the KaTeX documentation.

Mermaid diagrams

Mermaid is a library for creating diagrams and visualizations using text and code. You can define those diagrams in your Markdown cells via ```mermaid blocks. Let’s see an example:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
    D-->A;

Elixir integration

Here are some tips on how to better integrate Livebook with Elixir.

Mix projects

Sometimes you may want to run a notebook within the context of an existing Mix project. This is possible from Elixir v1.14 with the help of Mix.install/2.

As an example, imagine you have created a notebook inside your current project, at notebooks/example.livemd. In order to run within the root Mix project, using the same configuration and dependencies versions, you can change your notebook setup cell to invoke Mix.install/2 with the following arguments:

Mix.install(
  [
    {:my_app, path: Path.join(__DIR__, ".."), env: :dev}
  ],
  config_path: :my_app,
  lockfile: :my_app
)

Runtimes

Livebook has a concept of runtime, which in practice is an Elixir node responsible for evaluating your code. You can choose the runtime by clicking the “Runtime” icon () on the sidebar (or by using the s r keyboard shortcut).

By default, a new Elixir node is started (similarly to starting iex). You can click reconnect whenever you want to discard the current node and start a new one.

You can also manually attach to an existing distributed node by picking the “Attached Node” runtime. To do so, you will need the Erlang Name of the external node and its Erlang Cookie. For example, you can start a Phoenix application as follows:

$ iex --sname phoenix-app --cookie secret -S mix phx.server

Now open up a new notebook and click the “Runtime” icon on the sidebar. Click to “Configure” the runtime and choose “Attached node”. Input the name and cookie as above and you should be ready to connect to it.

Note, however, that you can’t install new dependencies on a connected runtime. If you want to install dependencies, you have three options:

1. Add any Livebook related to dependencies directly to the project (you may add them to a specific environment, such as :dev or :livebook, and then set MIX_ENV accordingly when starting your application)

2. Use the Mix project approach outlined in the previous section;

3. Use a regular notebook and use Node.connect/1 to connect to your application. Use the :erpc module to fetch data from the remote node and execute code.

Evaluation vs compilation

Livebook automatically shows the execution time of each Code cell on the bottom-right of the cell. After evaluation, the total time can be seen by hovering the green dot.

However, it is important to remember that all code outside of a module in Elixir is evaluated, and therefore executes much slower than code defined inside modules, which are compiled.

Let’s see an example. Run the cell below:

Enum.reduce(1..1_000_000, 0, fn x, acc -> x + acc end)

We are adding all of the elements in a range by iterating them one by one. However, executing it likely takes some reasonable amount of time, as the invocation of the Enum.reduce/3 as well as the anonymous function argument are evaluated.

However, what if we move the above to inside a function? Let’s do that:

defmodule Bench do
  def sum do
    Enum.reduce(1..1_000_000, 0, fn x, acc -> x + acc end)
  end
end

Now let’s try running it:

Bench.sum()

The latest cell should execute a least an order of magnitude faster than the previous Enum.reduce/3 call. While the call Bench.sum() itself is evaluated, the one million iterations of Enum.reduce/3 happen inside a module, which is compiled.

If a notebook is performing slower than expected, consider moving the bulk of the execution to inside modules.

Erlang integration

Livebook also allows developers to write Erlang code. To do so, click on the submenu option on the right side of the “Elixir” cell button and choose Erlang.

Your Erlang code will run alongside your Elixir cells. This means you can leverage all of dependency management and smart cells features outlined in the previous sections. In particular, integration between Erlang and Elixir will happen as follows:

• Variables in Elixir are available in Erlang cells in camel-case fashion. x in Elixir becomes X in Erlang. foo_bar becomes FooBar;

• Variables in Erlang are available in Elixir cells in underscored fashion. X in Erlang becomes x in Elixir. FooBar becomes foo_bar;

For example, to print all of the cats defined at the top of the notebook, but in Erlang:

[io:format("~ts", [Cat]) || Cat <- Cats].

We are just beginning the Erlang integration and contributions to enrich the support are welcome.

Running tests

There are two main ways of running tests inside Livebook.

Doctests

Doctests allows developers to provide and test examples directly from their documentation. Doctests are defined with the iex> prompts under the @moduledoc and @doc attributes of your modules. Let’s see an example:

defmodule MyModule do
  @moduledoc """
  This is an example of doctests:

      iex> 2 + 2
      5

      iex> 6 + 7
      13
  """
end

Livebook automatically detect doctests for any defined modules and automatically executes them when you evaluate the cell. Doctests which fail are marked in red in the gutter and show the failure information right below them. Otherwise they are tagged in green. For more information on doctests and their limitations, see ExUnit.Doctest.

ExUnit integration

It is also possible to ExUnit suites directly from your notebooks. The key is to disable ExUnit‘s autorun feature and then explicitly run the test suite after all test cases have been defined:

ExUnit.start(autorun: false)

defmodule MyTest do
  use ExUnit.Case, async: true

  test "it works" do
    assert true
  end
end

ExUnit.run()

This is perfect for testing more complex logic that does not fit under doctests.

Next steps

That’s our quick intro to Livebook! Where to go next?

• If you are not familiar with Elixir, there is a fast paced introduction to the language in the Distributed portals with Elixir notebook;

• Go back to the Learn page and see how to use Livebook to deploy apps, explore data, plot graphs, and much more;

• Finally, remember Livebook is an open source project, so feel free to look into the repository to contribute, report bugs, suggest features or just skim over the codebase.

Now go ahead and build something cool! 🚢