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

• Code notebooks with Markdown support and Code cells where Elixir code is evaluated on demand.

• Rich code editor throughCodeMirror: with support for autocompletion, inline documentation, code formatting, etc.

• Interactive results viaKino: displayVega-Lite charts, tables, maps, and more.

• Automation: use Smart cells to perform high-level tasks and write notebooks faster than ever. Query databases, plot charts, build maps, and more directly from Livebook's UI.

• Reproducible: Livebook ensures your code runs in a predictable order, all the way down to package management. It also tracks your notebook state, annotating which parts are stale.

• Collaboration: multiple users can work on the same notebook at once, no additional setup required.

• Decentralized: Livebook is open-source and you can run it anywhere. The"Run in Livebook" badge makes it easy to import any Livebook into your own Livebook.

• Versionable: notebooks are stored in the.livemd format, which is a subset of Markdown with support for diagrams viaMermaid and for mathematical formulas viaKaTex..livemd files can be shared and play well with version control.

• Custom runtimes: when executing Elixir code, you can either start a fresh Elixir instance, connect to an existing node, or run it inside an existing Elixir project, with access to all of its modules and dependencies. This means Livebook can be a great tool to introspect and document existing projects too.

Getting started

Head out tothe 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:

There are more resources for those who are ready to dig deeper:

• Our official documentation with in-depth guides

• Our Integrations page covering the languages, data sources, and libraries that Livebook works with out-of-the-box

• Our blog with news, posts, and screencasts

Installation

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

Desktop app

• Download the installer for Mac and Windows from our homepage

• Latest stable builds:Mac (Universal),Windows

• Nightly builds:Mac (Universal),Windows

• Builds for particular Livebook version are available on ourGitHub releases.

Docker

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

# Running with the default configurationdocker 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 permissionsdocker 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 belowdocker 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 ourDocker Deployment guide.

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

To try out features from the main branch you can alternativelyuse theghcr.io/livebook-dev/livebook:nightly image.SeeLivebook images.

Embedded devices

If you want to run Livebook on embedded devices, such as Raspberry Pi, BeagleBone, etc.,check outthe Livebook firmware builtwithNerves.

Direct installation with Elixir

You can run Livebook on your own machine using just Elixir. You will needElixir v1.18 or later.Livebook also requires the following Erlang applications:inets,os_mon,runtime_tools,ssl andxmerl. Those applications comewith most Erlang distributions but certain package managers may splitthem apart. For example, on Ubuntu, these Erlang applications canbe installed as follows:

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

Note: Thelivebook packageis meant to be used as a CLI tool. Livebook is not officiallysupported as a Mix/Hex dependency.

Escript

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

mix do local.rebar --force, local.hex --forcemix escript.install hex livebook# Start the Livebook serverlivebook server# See all the configuration optionslivebook server --help

After you install the escript, make sure you add the directory whereElixir keeps escripts to your$PATH.If you installed Elixir withasdf, you'll need to runasdf reshim elixironce the escript is built.

To try out features from the main branch you can alternativelyinstall 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.gitcd livebookmix deps.get --only prod# Run the Livebook serverMIX_ENV=prod mix phx.server

Security considerations

Livebook is built to document and execute code. Anyone with access to a Livebook instancewill 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 withinthe current machine. When running Livebook in the production environment - the recommendedenvironment - we also generate a token on initialization and we only allow access to theLivebook if said token is supplied as part of the URL.

Environment variables

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

• LIVEBOOK_ALLOW_URI_SCHEMES - sets additional allowed hyperlink schemes to theMarkdown content. Livebook sanitizes links in Markdown, allowing only a fewstandard schemes by default (such as http and https). Set it to a comma-separatedlist of schemes.

• LIVEBOOK_APP_SERVICE_NAME - sets the application name used by the cloudprovider to aid debugging.

• LIVEBOOK_APP_SERVICE_URL - sets the application url to manage thisLivebook instance within the cloud provider platform.

• LIVEBOOK_APPS_PATH - the directory with app notebooks. When set, the appsare deployed on Livebook startup with the persisted settings. Password-protectednotebooks will receive a random password, unlessLIVEBOOK_APPS_PATH_PASSWORDis set. When deploying using Livebook's Docker image, consider usingLIVEBOOK_APPS_PATH_WARMUP.

• LIVEBOOK_APPS_PATH_PASSWORD - the password to use for all protected appsdeployed fromLIVEBOOK_APPS_PATH.

• LIVEBOOK_APPS_PATH_WARMUP - sets the warmup mode for apps deployed fromLIVEBOOK_APPS_PATH. Must be either "auto" (apps are warmed up on Livebookstartup, right before app deployment) or "manual" (apps are warmed up whenbuilding the Docker image; to do so add "RUN /app/bin/warmup_apps" toyour image). Defaults to "auto".

• LIVEBOOK_AWS_CREDENTIALS - enable Livebook to read AWS Credentials fromenvironment variables, AWS Credentials, EC2/ECS metadata when configuringS3 buckets.

• LIVEBOOK_BASE_URL_PATH - sets the base url path the web application isserved on. Useful when deploying behind a reverse proxy.

• LIVEBOOK_PUBLIC_BASE_URL_PATH - sets the base url path the/public/* routesare served on. Note that this takes precedence overLIVEBOOK_BASE_URL_PATH,if both are set. Setting this may be useful to create exceptions when deployingbehind a reverse proxy that requires authentication.

• LIVEBOOK_CACERTFILE - path to a local file containing CA certificates.Those certificates are used during for server authentication when Livebookaccesses files from external sources.

• LIVEBOOK_CLUSTER - configures clustering strategy when running multipleinstances of Livebook using either the Docker image or an Elixir release.See the "Clustering" docs for more information:https://hexdocs.pm/livebook/clustering.html

• LIVEBOOK_COOKIE - sets the cookie for running Livebook in a cluster.Defaults to a random string that is generated on boot.

• LIVEBOOK_DATA_PATH - the directory to store Livebook's internalconfiguration. Defaults to "livebook" under the default user datadirectory.

• LIVEBOOK_DEFAULT_RUNTIME - sets the runtime type that is used by defaultwhen none is started explicitly for the given notebook. Must be either"standalone" (Standalone), "attached:NODE:COOKIE" (Attached node)or "embedded" (Embedded). Defaults to "standalone".

• LIVEBOOK_FIPS - if set to "true", it enables the FIPS mode on startup.See more details inthe documentation.

• LIVEBOOK_FORCE_SSL_HOST - sets a host to redirect to if the request is not over HTTPS.Note it does not apply when accessing Livebook via localhost. Defaults to nil.

• LIVEBOOK_HOME - sets the home path for the Livebook instance. This is thedefault path used on file selection screens and others. Defaults to theuser's operating system home.

• LIVEBOOK_IDENTITY_PROVIDER - controls whether Zero Trust Authenticationmust be used for this Livebook instance. This is useful when deployingLivebook airgapped inside a cloud platform, such as Cloudflare and Google.Supported values are:

  • basic_auth:<username>:<password>
  • cloudflare:<your-team-name (domain)>
  • google_iap:<your-audience (aud)>
  • tailscale:<tailscale-cli-socket-path>
  • custom:YourElixirModule

  See our authentication docs for more information:https://hexdocs.pm/livebook/authentication.html

• LIVEBOOK_IFRAME_PORT - sets the port that Livebook serves iframes at.This is relevant only when running Livebook without TLS. Defaults to 8081.

• LIVEBOOK_IFRAME_URL - sets the URL that Livebook loads iframes from.By default iframes are loaded from localLIVEBOOK_IFRAME_PORT when accessingLivebook over http:// and fromhttps://livebookusercontent.com when accessing over https://.

• LIVEBOOK_IP - sets the ip address to start the web application on.Must be a valid IPv4 or IPv6 address.

• LIVEBOOK_LOG_LEVEL - sets the logger level, allowing for more verboselogging, either of: error, warning, notice, info, debug. Defaults to warning.

• LIVEBOOK_LOG_METADATA - a comma-separated list of metadata keys that shouldbe included in the log messages. Currently the only Livebook-spcecific key isusers (attached to evaluation and request logs). By default includes onlyrequest_id.

• LIVEBOOK_LOG_FORMAT - sets the log output format, either "text" (default)for human-readable logs or "json" for structured JSON.

• LIVEBOOK_NODE - sets the node name for running Livebook in a cluster.Note that Livebook always runs using long names distribution, so thenode host name must use a fully qualified domain name (FQDN) or an IPaddress.

• LIVEBOOK_PASSWORD - sets a password that must be used to access Livebook.Must be at least 12 characters. Defaults to token authentication.

• LIVEBOOK_PROXY_HEADERS - a comma-separated list of headers that are set byproxies. For example,x-forwarded-for,x-forwarded-proto. Configuring thosemay be required when running Livebook behind reverse proxies.

• LIVEBOOK_PORT - sets the port Livebook runs on. If you want to run multipleinstances on the same domain with the same credentials but on different ports,you also need to setLIVEBOOK_SECRET_KEY_BASE. Defaults to 8080. If set to 0,a random port will be picked.

• LIVEBOOK_SECRET_KEY_BASE - sets a secret key that is used to sign and encryptthe session and other payloads used by Livebook. Must be at least 64 characterslong and it can be generated by commands such as:openssl rand -base64 48.Defaults to a random secret on every boot.

• LIVEBOOK_SHUTDOWN_ENABLED - controls if a shutdown button should be shownin the homepage. Set it to "true" to enable it.

• LIVEBOOK_TOKEN_ENABLED - controls whether token authentication is enabled.Enabled by default unlessLIVEBOOK_PASSWORD is set. Set it to "false" todisable it.

• LIVEBOOK_UPDATE_INSTRUCTIONS_URL - sets the URL to direct the user to forupdating Livebook when a new version becomes available.

• LIVEBOOK_WITHIN_IFRAME - controls if the application is running inside aniframe. Set it to "true" to enable it. If you do enable it, then the applicationmust run with HTTPS.

The environment variablesERL_AFLAGS andERL_ZFLAGS can also be set to configureLivebook and the notebook runtimes.ELIXIR_ERL_OPTIONS are also available to customizeLivebook, but it is not forwarded to runtimes.

If running Livebook via the command line, runlivebook server --help to seeall CLI-specific options.

Livebook Desktop

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

• thePATH environment variable

• or to configure the Erlang VM, for instance, by settingERL_AFLAGS="-proto_dist inet6_tcp" if you need Livebook to run over IPv6

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

Development

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

git clone https://github.com/livebook-dev/livebook.gitcd livebookmix setup# Run the Livebook servermix phx.server# Run testsmix test

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

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

Sponsors

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

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 athttp://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, softwaredistributed 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 andlimitations under the License.