Contributing to Enso

April 27, 2026 ยท View on GitHub

Thank you for your interest in contributing to Enso! We believe that only through community involvement can Enso be the best it can be! There are a whole host of ways to contribute, and every single one is appreciated. The major sections of this document are linked below:

All contributions to Enso should be in keeping with our Code of Conduct.

The Contributor License Agreement

As part of your first contribution to this repository, you need to accept the Contributor License Agreement. You will automatically be asked to sign the CLA when you make your first pull request.

Any work intentionally submitted for inclusion in Enso shall be licensed under this CLA.

The CLA you sign applies to all repositories associated with the Enso project, so you will only have to sign it once at the start of your contributions.

Issues

If you're wanting to get involved with Enso's development and are looking for somewhere to start, you can check out the following tags in our issues:

You can use the "Size" and "Difficulty" labels that should be assigned to every issue to get a better idea of how much work a given issue might be.

Feature Enhancements

If you feel like you have a suggestion for a change to the way that Enso works as a language, please take a look at the Enso RFC process to learn how to file an RFC for the project.

In essence, the RFC process provides a way to propose major changes to the language, the compiler, and the runtime in a way that ensures that they get seen and discussed by all the major stakeholders involved.

If, on the other hand, you're asking for a smaller feature, please feel free to submit a feature request to the repository.

Bug Reports

While it's never great to find a bug, they are a reality of software and software development! We can't fix or improve on the things that we don't know about, so report as many bugs as you can! If you're not sure whether something is a bug, file it anyway!

If you are concerned that your bug publicly presents a security risk to the users of Enso, please look at our security guidelines.

Even though GitHub search can be a bit hard to use sometimes, we'd appreciate if you could search for your issue before filing a bug as it's possible that someone else has already reported the issue. We know the search isn't the best, and it can be hard to know what to search for, so we really don't mind if you do submit a duplicate!

Opening an issue is as easy as following this link and filling out the fields. The template is intended to collect all the information we need to best diagnose the issue, so please take the time to fill it out accurately.

The reproduction steps are particularly important, as the more easily we can reproduce it, the faster we can fix the bug! It's also helpful to have the output of enso --version, as that will let us know if the bug is Operating System or Architecture specific.

Turning on verbose logs

Sometimes, it is helpful to attach a verbose log to your bug report. The way to enable verbose logging depends on which version of Enso you are using. For a standalone distribution (.exe on Windows, .AppImage on Linux), you can enable verbose logging by passing -debug.verbose option. If you are starting the project-manager, or language server separately, then pass --log-level trace option. With verbose logging, there are a lot of messages printed to the standard output, and it is possible that on slower terminal emulators this will clog the terminal and hence the whole backend. To avoid this, we recommend redirecting the output to /dev/null, via a command like enso -debug.verbose > /dev/null 2>&1.

The logs are kept in a central location $ENSO_DATA_DIRECTORY/log - on Linux, they are in $XDG_DATA_HOME/enso/log (usually ~/.local/share/enso/log), and on Windows they are in %APPDATA%\enso\log, see distribution.md for details. The log level name consists of the timestamp of the log file creation. There is no automatic log rotation, so you may want to delete the old logs from time to time.

Hacking on Enso

This will get you up and running for Enso development, with only a minimal amount of setup required. Enso's build system is fairly simple, allowing you to bootstrap the compiler as long as you have a minimal set of tools.

Design Documentation

If you're going to start contributing to Enso, it is often a good idea to take a look at the design documentation for the language. These files explain provide both a rigorous specification of Enso's design, but also insight into the why behind the decisions that have been made.

These can be found in docs/, and are organised by the part of the compiler that they relate to.

System Requirements

The following operating systems are supported for developing Enso:

  • Windows 10
  • macOS 12 and above
  • Linux 4.4 and above

Currently, we support x86_64 (all mentioned OS) and arm64 (Mac only) architectures. You may be able to develop Enso on other systems, but issues arising from unsupported configurations will not be fixed by the core team.

In order to build and run Enso you will need the following tools:

  • NodeJS with the latest LTS version. We recommend installing a Node version manager that automatically picks up the correct version, like fnm.
  • sbt with the same version as specified in project/build.properties.
  • Maven with version at least 3.6.3.
  • GraalVM with the same version as described in the build.sbt file, configured as your default JVM.
  • Flatbuffers Compiler with version 24.3.25. It is automatically downloaded when using the run command. For direct sbt usage, you can download the flatc binary from the release assets.
  • Rustup, the rust toolchain management utility.
  • On MacOS and Linux, the tar command is required for running some tests. It should be installed by default on most distributions.
  • On Windows, the run command must be run in the latest version of Powershell or in cmd.
  • If you want to be able to build the ensoup Native Image, you will need a native C compiler for your platform as described in the Native Image Prerequisites. On Linux that will be gcc, on macOS you may need xcode and on Windows you need to configure the Developer Command Prompt for Microsoft Visual C++ for the x64 architecture.

Managing multiple JVM installations can be a pain, so you can consider using helper tools for that. We recommend:

On Windows: you need a few additional requirements:

  1. Developer Mode must be enabled to support creating filesystem symlinks. E.g., using this instruction: https://pureinfotech.com/enable-developer-mode-windows-11/
  2. You must create either .bazelrc.local at repository root, or %USERPROFILE%\.bazelrc (consult https://bazel.build/run/bazelrc for more possible locations), containing the following:
# Use different drive letter if needed, but the path must be SHORT
startup --output_base=C:/_bzl
common --disk_cache=C:/_bzl-disk
common --repository_cache=C:/_bzl-repo
  1. You need to have bash.exe available in PATH. bash.exe from WSL is not suitable so either:
  • install MSYS2 (https://www.msys2.org/)
  • or use bash executable provided with Git by adding the following to your PATH variable: C:\Program Files\Git\bin, if you have it installed.
  • or configure Git installation selecting the third option: Git installation settings
  • or have BAZEL_SH environment variable set to exact path to bash.exe, whatever way you have it installed.

For users of M1 Mac: installing GraalVM on M1 Mac requires manual actions, please refer to a dedicated documentation.

Getting the Sources

Given you've probably been reading this document on GitHub, you might have an inkling where to look!. You can clone Enso using two methods:

  • Via HTTPS: We recommend you only use HTTPS if checking out the sources as read-only.
git clone https://github.com/enso-org/enso.git
  • Via SSH: For those who plan on regularly making direct commits, cloning over SSH may provide a better user experience (but requires setting up your SSH Keys with GitHub).
git clone git@github.com:enso-org/enso.git

The recommended IDE for working with the sources is VSCode with Enso extension. Alternativelly, use the IntelliJ with the official Scala plugin and import the sbt project.

Getting Set Up (Rust)

The Rust code in this repository requires a specific nightly rust toolchain, as defined by rust-toolchain override file. The rustup will automatically download the appropriate compiler version along with the necessary components.

enso$ rustup toolchain install stable   # Stable toolchain required for the following tools.

The previous three steps shall be enough to build the IDE via ./run ide build.

Getting Set Up (Documentation)

We enforce automated formatting of all of our documentation and configuration using the fairly common prettier automatic formatter. You can install prettier for our project by running the following command:

enso$ corepack pnpm install

This does, however, mean that you have to have node installed on your system. Please follow the guidelines above to install node if you have not already done so.

The version if prettier is forced by our package-lock.json in order for us to make formatting bumps all at once.

You can format all of our documentation and configuration as follows:

enso$ corepack pnpm run format

Building Enso Engine

There are multiple projects in the main Enso repository. All of the engine parts can be built, run and tested using Scala Build Tool. As long as your configuration is correct, with the correct versions of sbt, Rust and GraalVM, the same steps can be followed on all of our supported platforms (Linux, MacOS and Windows).

$ sbt
sbt:enso> buildEngineDistribution

The language interpreter CLI distribution is generated into built-distribution directory with bin/enso launcher script/executable located inside. sbt handles downloading and building library dependencies as needed, meaning that you don't need to handle any of this manually.

One can use the generated binaries directly, but the suggested workflow is to continue using sbt for execution as well.

Running Enso from CLI

The language interpreter CLI distribution can be built by sbt. To execute the Enso interpreter use sbt as well:

$ sbt
sbt:enso> runEngineDistribution --help

The runEngineDistribution task takes care of everything. It builds the distribution in the built-distribution directory (with the help of buildEngineDistribution command) and launches the generated Enso launcher executable.

Detailed information on the flags it supports can be shown with the --help flag, but the primary functionality is as follows:

  • --new PATH: Creates a new Enso project at the location specified by PATH.
  • --run PATH: Executes the interpreter on the Enso source specified by PATH. In this case, PATH must point to either a standalone Enso file or an Enso project.
sbt:enso> runEngineDistribution --new Hello

The above command generates project in directory Hello with the main source file being at Hello/src/Main.enso. One can edit the file and then execute it:

sbt:enso> runEngineDistribution --run Hello

Testing Enso Libraries

To run the tests inside sbt you can use the following command:

sbt:enso> runEngineDistribution --run test/Table_Tests/

This builds the library code and runs all the tests in the specified folder. And is the fastest way to build the code and run the tests.

Alternatively to run a single file of tests you can specify the file to run

sbt:enso> runEngineDistribution --run test/Base_Tests/src/Data/Time/Duration_Spec.enso

Or you can pattern match against the test name using this syntax

sbt:enso> runEngineDistribution --run test/Base_Tests/src/Data/Time/Duration_Spec.enso should.normalize

Or even control additional environment variables of the running process. The Base tests rely in a few places on the system language controlled (on Linux) by a value of LANG environment variable. To change value of LANG environment variable to C run the tests with --env option and name/value pair:

sbt:enso> runEngineDistribution --env LANG=C --run test/BASE_Tests

This runs all tests in Duration_Spec.enso that have 'should normalize' the their name.

To run with a debugger first start the debugger listening on 5005, add a breakpoint in a test then run with

sbt:enso> runEngineDistribution --run test/Base_Tests --debug

Then connect your development environment to the 5005 port. More details on debugging are available in a separate document.

When using the runEngineDistribution command of sbt the Java assertions (-ea JVM option) as well as Enso assertions are enabled.

Details on profiling are available in a separate document.

Static Analysis

Additionally, you can check a project/script for basic errors (without running it) using --compile flag. The --enable-static-analysis flag enables experimental static analysis passes. So if you want to try out the type checker prototype on your project, you can run:

sbt:enso> runEngineDistribution --compile Hello --enable-static-analysis

Native Image

Native image is a capability provided alongside GraalVM that allows the generation of native executables from JVM language programs (such as the Enso interpreter itself). Details:

Native image support is disabled for development (as it slows down edit/compile/run cycle significantly). One has to opt-in to enable it.

Running IDE

Running development version of the IDE is possible via the npm script in the root of the repository:

enso$ corepack pnpm install
enso$ corepack pnpm run compile
enso$ corepack pnpm run dev:gui

By default the dev:run script looks for the dev enso executable in the built-distribution directory assuming that it was built with sbt:

sbt:enso> buildEngineDistribution

and will fallback to downloading the latest nightly if not found. You can override the location of enso executable by providing the absolute path to it in the ENSO_ENGINE_PATH environment variable.

enso$ ENSO_ENGINE_PATH=/path/to/enso corepack pnpm run dev:gui

You can provide extra arguments to the enso executable using the ENSO_ENGINE_ARGS environment variable.

enso$ ENSO_ENGINE_ARGS='--log-level trace' corepack pnpm run dev:gui

To debug the language server process of a running project, you can set the JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,address=5005 environment variable when starting the pnpm run dev:gui dev server. Just configure your Java IDE to listen on port 5005 before starting the project.

Pull Requests

Pull Requests are the primary method for making changes to Enso. GitHub has fantastic documentation on using the pull request feature. Enso uses the 'fork-and-pull' model of development. It is as described here and involves people pushing changes to their own fork and creating pull requests to bring those changes into the main Enso repository.

Please make all pull requests against the develop branch.

  • We run CI on all contributions to Enso, but it's still useful for you to run the tests yourself locally first! This can be done by running test in the enso project in sbt.
  • Additionally, please ensure that your code conforms to the Enso style guides, particularly the Scala Style Guide and the Java Style Guide.

Make sure you perform these checks before every pull request. You can even add git hooks before every push to make sure that you can't forget.

  • Every pull request to the Enso repository is reviewed by a member of the core team! You'll get assigned a reviewer based on the areas your PR touches, but please feel free to ask for a specific person if you've worked with them in a specific area before!
  • If you have questions, or would like to begin the review process before your PR is 'done', please use the Draft Pull Requests feature on GitHub. Doing so will allow you to make use of our CI infrastructure as part of your development process.

Once the reviewer approves your pull request it will be tested by our continuous integration provider before being merged. If we request changes to your PR, please feel free to discuss the suggestions and comments! We can only achieve the best results through open collaboration.

Documentation

Documentation improvements are very welcome! For now, the main documentation available is the developer documentation for the language, which can be found at the dev docs site. The source for this documentation is found in the docs/ folder, and can be altered from there.

Documentation pull requests will be reviewed in exactly the same way as normal pull requests.

To find documentation-related issues, sort by the Category: Documentation label.

Issue Triage

Sometimes issues can be left open long after the bug has been fixed. Other times, a bug might go stale because something has changed in the meantime.

It can be helpful to go through older bug reports and make sure that they are still valid. Load up an older issue, double check that it's still true, and leave a comment letting us know if it is or is not. The least recently updated sort is good for finding issues like this.

Contributors with sufficient permissions can help by adding labels to help with issue triage.

If you're looking for somewhere to start, take a look at the Difficulty: Beginner issue label, as well as the Status: Help Wanted and Status: Good First Issue labels.

Out-of-Tree Contributions

As helpful as contributing to Enso directly is, it can also be just as helpful to contribute in other ways outside this repository:

For people new to Enso, and just starting to contribute, or even for more seasoned developers, some useful places to look for information are: