Before getting started, please check whether you have all the necessary software installed and configured properly. Alternatively, a pre-configured Ubuntu VM image is available here. Instructions for usage of the VM are provided here.


Your system must have the following (very common) software packages installed (we recommend using your favorite package manager to install them):

Installation on Ubuntu

$ sudo apt install gh git curl openjdk-17-jdk openjdk-17-jre nix screen
$ sudo snap install code --classic

Installation on macOS

$ brew install --cask visual-studio-code
$ brew install gh git cmake curl openjdk@17 screen
$ curl -L | sh

Lingua Franca Toolchain

To install the nightly (recommended) Lingua Franca CLI tools (i.e, the compiler lfc, the diagram generator lfd, and the code formatter lff), run:

curl -Ls | bash -s nightly cli

If you prefer an Eclipse-based IDE over the Lingua Franca VS Code extension, install the nightly build of epoch using the following command:

curl -Ls | bash -s nightly epoch

Troubleshooting for permission denied error

If you get a permission denied error while running the command above (the error will look like below):

> Creating directory /usr/local/share/lingua-franca
mkdir: /usr/local/share/lingua-franca: Permission denied

Try running the following commands which download the installation shell script and run the script with sudo:

chmod +x
sudo bash nightly cli

VS Code extensions

Please ensure that you have the following extensions installed:

For debugging support in VS Code:

To install them from the command line, run:

$ code --install-extension ms-vscode.cmake-tools
$ code --install-extension ms-vscode.cpptools
$ code --install-extension lf-lang.vscode-lingua-franca --pre-release
$ code --install-extension marus25.cortex-debug


Using nix on Linux/WSL

To use nix on Linux, make sure that your user is a member of the nix-users group. To check this, run:

$ groups

If nix-users is not listed, run:

$ sudo usermod -aG nix-users $USER

Please note that you might need to reboot your system after running usermod in order for the new group membership to be reflected.

Using picotool on Linux/WSL

To allow access to the RP2040 via USB without superuser privileges, add custom udev rules using the following command:

$ curl -s | sudo tee -a /etc/udev/rules.d/99-picotool.rules >/dev/null