Home

Awesome

Livebook

Website Latest Version

Livebook is a web application for writing interactive and collaborative code notebooks. It features:

Getting started

Head out to the Install section of Livebook's website to get started. Once Livebook is up and running on your machine, visit the "Learn" section with introductory guides and documentation on several Livebook features. Here is a sneak peak of the "Welcome to Livebook" guide:

Screenshot

For screencasts and news, check out news.livebook.dev.

Installation

We provide several methods for running Livebook, pick the one that best fits your use case.

Desktop app

Docker

Running Livebook using Docker is another great option to run Livebook in case you don't have Elixir installed.

# Running with the default configuration
docker run -p 8080:8080 -p 8081:8081 --pull always ghcr.io/livebook-dev/livebook

# In order to access and save notebooks directly to your machine
# you can mount a local directory into the container.
# Make sure to specify the user with "-u $(id -u):$(id -g)"
# so that the created files have proper permissions
docker run -p 8080:8080 -p 8081:8081 --pull always -u $(id -u):$(id -g) -v $(pwd):/data ghcr.io/livebook-dev/livebook

# You can configure Livebook using environment variables,
# for all options see the dedicated "Environment variables" section below
docker run -p 8080:8080 -p 8081:8081 --pull always -e LIVEBOOK_PASSWORD="securesecret" ghcr.io/livebook-dev/livebook

# Or if you need to run on different ports:
docker run -p 8090:8090 -p 8091:8091 --pull always -e LIVEBOOK_PORT=8090 -e LIVEBOOK_IFRAME_PORT=8091 ghcr.io/livebook-dev/livebook

To deploy Livebook on your cloud platform, see our Docker Deployment guide.

For CUDA support, see images with the "cuda" tag.

To try out features from the main branch you can alternatively use the ghcr.io/livebook-dev/livebook:nightly image. See Livebook images.

Embedded devices

If you want to run Livebook on embedded devices, such as Raspberry Pi, BeagleBone, etc., check out the Livebook firmware built with Nerves.

Direct installation with Elixir

You can run Livebook on your own machine using just Elixir. You will need Elixir v1.16 or later. Livebook also requires the following Erlang applications: inets, os_mon, runtime_tools, ssl and xmerl. Those applications come with most Erlang distributions but certain package managers may split them apart. For example, on Ubuntu, these Erlang applications can be installed as follows:

sudo apt install erlang-inets erlang-os-mon erlang-runtime-tools erlang-ssl erlang-xmerl erlang-dev erlang-parsetools

Note: The livebook package is meant to be used as a CLI tool. Livebook is not officially supported as a Mix/Hex dependency.

Escript

Running Livebook using Escript makes for a very convenient option for local usage and provides easy configuration via CLI options.

mix do local.rebar --force, local.hex --force
mix escript.install hex livebook

# Start the Livebook server
livebook server

# See all the configuration options
livebook server --help

After you install the escript, make sure you add the directory where Elixir keeps escripts to your $PATH. If you installed Elixir with asdf, you'll need to run asdf reshim elixir once the escript is built.

To try out features from the main branch you can alternatively install the escript directly from GitHub like this:

mix escript.install github livebook-dev/livebook

From source

You can run latest Livebook directly from source.

git clone https://github.com/livebook-dev/livebook.git
cd livebook
mix deps.get --only prod

# Run the Livebook server
MIX_ENV=prod mix phx.server

Security considerations

Livebook is built to document and execute code. Anyone with access to a Livebook instance will be able to access any file and execute any code in the machine Livebook is running.

For this reason, Livebook only binds to the 127.0.0.1, allowing access to happen only within the current machine. When running Livebook in the production environment - the recommended environment - we also generate a token on initialization and we only allow access to the Livebook if said token is supplied as part of the URL.

Environment variables

<!-- Environment variables -->

The following environment variables can be used to configure Livebook on boot:

The environment variables ERL_AFLAGS and ERL_ZFLAGS can also be set to configure Livebook and the notebook runtimes. ELIXIR_ERL_OPTIONS are also available to customize Livebook, but it is not forwarded to runtimes.

<!-- Environment variables -->

If running Livebook via the command line, run livebook server --help to see all CLI-specific options.

Livebook Desktop

When running Livebook Desktop, Livebook will invoke on boot a file named ~/.livebookdesktop.sh on macOS or %USERPROFILE%\.livebookdesktop.bat on Windows. This file can set environment variables used by Livebook, such as:

Be careful when modifying boot files, Livebook may be unable to start if configured incorrectly.

Development

Livebook is primarily a Phoenix web application and can be setup as such:

git clone https://github.com/livebook-dev/livebook.git
cd livebook
mix setup

# Run the Livebook server
mix phx.server

# Run tests
mix test

Acknowledgements

Thank you to Uffizzi for providing ephemeral environments to preview pull requests.

Desktop app builds

For macOS, run:

# Test macOS app locally
(cd rel/app/macos && ./run.sh)

# Build macOS installer
.github/scripts/app/build_macos.sh

For Windows, run:

# Test Windows app locally
(cd rel/app/windows && ./run.sh)

# Build Windows installer
.github/scripts/app/build_windows.sh

Platinum sponsors

<a href="https://fly.io"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://fly.io/public/images/brand/logo-inverted.svg"> <source media="(prefers-color-scheme: light)" srcset="https://fly.io/public/images/brand/logo.svg"> <img height="130" src="https://fly.io/public/images/brand/logo.svg" alt="Fly.io"> </picture> </a>

Fly is a platform for running full stack apps and databases close to your users.

Sponsors

<a href="https://huggingface.co/"> <img height="70" src="https://huggingface.co/datasets/huggingface/brand-assets/resolve/main/hf-logo-with-title.png" alt="Hugging Face"> </a>

The platform where the machine learning community<br /> collaborates on models, datasets, and applications.

<br /> <a href="https://www.tigrisdata.com/"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://www.tigrisdata.com/docs/logo/dark.png"> <source media="(prefers-color-scheme: light)" srcset="https://www.tigrisdata.com/docs/logo/light.png"> <img height="50" src="https://www.tigrisdata.com/docs/logo/light.png" alt="Tigris"> </picture> </a>

Tigris is a globally distributed S3-compatible object storage<br /> service that provides low latency anywhere in the world.

License

Copyright (C) 2021 Dashbit

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.