How to Set Up Midnight Development on Windows with WSL2

If you’re developing for Midnight on Windows, you’ve likely hit a critical limitation: Midnight’s toolchain—including the Compact compiler, proof server, and other essential components—are Linux binaries. They won’t run natively on Windows, no matter how you try. This isn’t a dead end, though. Windows Subsystem for Linux 2 (WSL2) bridges this gap by providing a full-fledged Linux environment inside Windows. Once configured, you gain access to a genuine Ubuntu terminal, all the Linux development tools you need, and a stable foundation for building Midnight applications.

I recently migrated my entire Midnight development workflow to WSL2. The process wasn’t flawless—there were hidden pitfalls and subtle configuration steps that weren’t immediately obvious. Below is a distilled guide covering every step, including the adjustments that saved me hours of debugging.

Set Up WSL2 Properly Before Installing Ubuntu

Microsoft provides official documentation for enabling WSL2, so we won’t replicate that here. Follow the Microsoft guide to install WSL2 on your system and ensure Ubuntu is running before proceeding. Once WSL2 is active, open the Microsoft Store, search for Ubuntu 24.04 LTS, and install it. After installation, launch Ubuntu from the Start menu to complete the initial setup, which includes creating a Linux username and password.

Important: When entering your password, nothing will appear on screen. This is normal behavior for Linux. Just type the password and press Enter.

To confirm WSL2 is functioning as expected, open PowerShell and run:

wsl --list --verbose

You should see Ubuntu listed with Version 2. If it shows Version 1, switch to WSL2 as the default:

wsl --set-default-version 2

Allocate Sufficient Memory to WSL2 to Avoid Silent Failures

This step is often overlooked, but it’s critical for Midnight development. By default, WSL2 is allocated only 1GB of RAM, which is insufficient for the Midnight proof server. The server requires at least 4GB of memory to generate zero-knowledge proofs without crashing. Without this adjustment, the proof server may fail silently or terminate mid-process with no clear error message—exactly what happened to me during my first attempt.

Create a .wslconfig file in your Windows user directory. Open PowerShell and run:

notepad "$env:USERPROFILE\.wslconfig"

Paste the following configuration into the file:

[wsl2]
memory=8GB
processors=4
swap=3GB
localhostForwarding=true

If your system has less than 16GB of RAM, scale these values proportionally. The minimum reliable configuration for Midnight development is memory=4GB. Save the file, then restart WSL with:

wsl --shutdown

Reopen Ubuntu from the Start menu to apply the changes.

Install Core Development Tools in Ubuntu

With WSL2 properly configured, the next step is installing the foundational tools required for Midnight development.

First, update your package lists and install curl, which is essential for downloading other software:

sudo apt update
sudo apt install -y curl

Next, install Git for version control and repository cloning:

sudo apt install -y git

Midnight requires Node.js 22 or higher, so we’ll use nvm (Node Version Manager) to install and manage the correct version. Avoid installing Node.js directly from Windows, as version mismatches can cause compatibility issues later. Run the following commands in your Ubuntu terminal:

curl -o-  | bash

After installation, reload your shell configuration:

source ~/.bashrc

Then install Node.js 22:

nvm install 22
nvm use 22

Verify the installation:

node --version
npm --version

Note for Zsh users: Replace ~/.bashrc with ~/.zshrc in the commands above. The Midnight team validates create-mn-app and the SDK against Node.js 22, so using a newer major version may introduce unexpected compatibility issues. Always check the Midnight documentation for the latest supported versions.

Deploy Docker Engine Inside WSL2 for Containerized Proofs

The Midnight proof server runs as a Docker container, so Docker Engine must be installed inside WSL2, not in the Windows host. Begin by setting up Docker’s package repository:

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Add the Docker repository to your sources:

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: 
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Update your package lists and install Docker:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the Docker group to avoid running commands with sudo:

sudo usermod -aG docker $USER
newgrp docker

Start the Docker service:

sudo service docker start

Test the installation:

docker run hello-world

Install the Midnight Toolchain and Scaffold Your Project

With Docker running, install the Compact toolchain—the core compiler and CLI for Midnight—using its official installer:

curl --proto '=https' --tlsv1.2 -LsSf  | sh

Add the toolchain to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify the installation:

compact --version

Finally, scaffold your first Midnight project using create-mn-app, the official scaffolding tool from the Midnight team. This command generates a complete project structure, including wallet scripts, contract sources, and compilation configurations:

npx create-mn-app@latest

Note for Zsh users: If you’re using Zsh, replace ~/.bashrc with ~/.zshrc in the PATH addition step.

A Seamless Midnight Workflow on Windows

Building on Midnight from a Windows machine no longer requires dual-booting or remote Linux servers. With WSL2, Docker, and the Midnight toolchain properly configured, you can develop, test, and deploy Midnight applications directly on your Windows machine with minimal friction. This setup not only simplifies the development process but also ensures compatibility with the Midnight ecosystem’s Linux-native components.