Setting up Midnight on Windows via WSL2: The Complete Guide

Uroy Nwankwo — Fri, 08 May 2026 22:59:21 +0000

Midnight's toolchain runs natively on UNIX systems, Linux and macOS. If you're on Windows, you will need the Windows Subsystem for Linux 2 (WSL2).
This tutorial takes you from a fresh Windows machine to a working Midnight dev environment.

Target audience: Windows developers who want to build on the Midnight network.

Prerequisites:

Windows 10 (version 2004+) or Windows 11
Administrator access
stable internet connection.

What you'll have by the end: A winodws machine setup with a complete development environment for building on the midnight network.

You will set up WSL2, configure Docker Desktop, allocate enough memory for the proof server, install the Compact compiler, and verify everything by deploying the Hello World contract. It also shows which Windows approaches fail, so you can skip the dead ends.

What does not work on Windows

You cannot run the Midnight toolchain natively on Windows. The following approaches all fail:

PowerShell / Command Prompt: the Compact installer script is a POSIX shell script. It will not run.
Windows-native Node.js: even if you install Node.js for Windows, the Compact compiler and proof server depend on Linux binaries. They will not resolve correctly.
Git Bash / Cygwin: these are POSIX compatibility layers, not real Linux environments. The installer may appear to work, but it will produce broken PATH entries and missing binaries at runtime.

The supported Windows setup is WSL2 with a real Linux distribution. Everything after this point assumes you are inside a WSL2 terminal unless explicitly marked [Windows terminal].

Step 1: Install and configure WSL2

[Windows terminal: run PowerShell as Administrator]

wsl --install

This command installs WSL2 and downloads Ubuntu, which is the recommended distribution. Restart your machine when prompted.

After restart, open Ubuntu from the Start menu. The first launch completes the Ubuntu setup and asks you to create a Linux username and password. These credentials are for your WSL2 environment only. They do not need to match your Windows credentials.

Verify WSL2 is active:

wsl --list --verbose

You should see Ubuntu listed with Version 2. If it shows Version 1, upgrade it:

wsl --set-version Ubuntu 2

Step 2: Configure WSL2 memory with `.wslconfig`

This is the step the official docs miss. The Midnight proof server generates zero-knowledge proofs locally, which takes real memory. By default, WSL2 caps memory at 1 GB, so the proof server can run out of memory and crash without much explanation.

You need to create a .wslconfig file in your Windows user profile directory to raise this limit.

[Windows terminal]

Open Notepad (or any text editor) and create the file at C:\Users\<YourUsername>\.wslconfig:

# .wslconfig: WSL2 resource configuration
[wsl2]
memory=8GB          # Allocate 8 GB RAM to WSL2 (minimum 4 GB for proof server)
processors=4        # Number of CPU cores available to WSL2
swap=2GB            # Optional: virtual swap space
localhostForwarding=true

Save the file, then restart WSL2 from a Windows terminal:

wsl --shutdown

Wait 10 seconds, then reopen your Ubuntu terminal. The new memory limit takes effect immediately.

Warning: The proof server can crash with less than 4 GB allocated. 8GB is the safer setting. If your machine has 16 GB of RAM or more, giving WSL2 8GB still leaves enough memory for Windows and a browser.

Step 3: Set up Docker Desktop with the WSL2 backend

The Midnight proof server runs as a Docker container. Docker Desktop must use the WSL2 backend. The Hyper-V backend does not give your WSL2 terminal access to Docker.

Download and install Docker Desktop.
During installation, select Use WSL2 instead of Hyper-V when prompted.
After installation, open Docker Desktop and go to Settings → General. Confirm that Use the WSL2 based engine is checked.
Go to Settings → Resources → WSL Integration. Enable integration for your Ubuntu distribution.
Click Apply & Restart.

Verify Docker is accessible from inside WSL2:

[WSL terminal]

docker --version

You should see output like Docker version 26.x.x, build .... If you see command not found, Docker is not exposed inside WSL yet. Go back to item 4 in this section and make sure WSL integration is enabled for your Ubuntu distro.

Step 4: Install Node.js inside WSL2

The Midnight DApp tooling requires Node.js v22 or later. Install it inside WSL2 with nvm (Node Version Manager). That keeps the version under your user account and avoids sudo headaches.

[WSL terminal]

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Reload your shell:

source ~/.bashrc

Install and activate Node.js v22:

nvm install 22
nvm use 22
node --version   # should output v22.x.x

Note: Do not install Node.js with apt for this workflow. Ubuntu's apt packages are usually older and do not meet the v22 requirement.

Step 5: Install the Compact compiler

[WSL terminal]

Run the official Compact installer:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh

The installer downloads the Compact binary and adds it to your PATH. Reload your shell config so the PATH change takes effect:

source ~/.bashrc
# or, if you use zsh:
source ~/.zshrc

Verify the installation:

compact --version
compact compile --version
which compact

All three commands should return valid output. If compact: command not found appears, the PATH was not updated. Add it manually:

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

Update to the latest compiler version:

compact update

Warning: If compact update fails with:
Failed to spawn artifact extraction command
No such file or directory (os error 2)
your WSL environment is missing required system tools (for example unzip or tar). Install them before retrying:
sudo apt update
sudo apt install -y unzip tar gzip curl

Install a package manager

The Hello World example later in this tutorial uses yarn. Install it with npm:

npm install -g yarn

Verify it installed:

yarn --version

Note: yarn is optional. You can use npm or pnpm instead.
If you prefer a different package manager, substitute yarn commands
with your preferred equivalent throughout this tutorial
(e.g. npm install instead of yarn install, npm run env:up
instead of yarn env:up).

Step 6: Start the proof server

The proof server generates ZK proofs for your transactions. It runs as a Docker container on port 6300.

[WSL terminal]

Make sure Docker Desktop is running (check your Windows system tray for the Docker icon). Then start the proof server:

docker run -p 6300:6300 midnightntwrk/proof-server:8.0.3 midnight-proof-server -v

This command occupies the terminal while the server runs. Open a second WSL2 terminal window for the next steps. You should see log output ending with something like:

 INFO actix_server::server: starting service: "actix-web-service-0.0.0.0:6300", 
 workers: 4, listening on: 0.0.0.0:6300

That confirms the proof server is running and ready.

Tip: Keep the proof server terminal open while you work. If you close it, any compile or deploy step that needs ZK proofs will hang or fail.

Step 7: Install the Compact VS Code extension

Before opening any contract files, install the Compact VS Code
extension. It provides syntax highlighting and code snippet
completion for .compact files. Without it, VS Code treats
your contract as plain text.

[WSL terminal]

Download the VSIX package:

curl -L -o compact.vsix https://raw.githubusercontent.com/midnight-ntwrk/releases/gh-pages/artifacts/vscode-extension/compact-0.2.13/compact-0.2.13.vsix

Install it in VS Code:

code --install-extension compact.vsix

Alternatively, install it manually through the VS Code UI:

Open VS Code
Go to Extensions (Ctrl+Shift+X)
Click the ... menu at the top right of the Extensions panel
Select Install from VSIX...
Navigate to and select the downloaded compact.vsix file

Verification: Open the Extensions panel and confirm
Compact Language Support appears in your installed extensions list.

Step 8: Deploy the Hello World contract

With the proof server running, verify the full setup by cloning the Hello World example, compiling a Compact smart contract, and deploying it to a local Devnet.

Before cloning the example project, set up a working directory inside your WSL environment. A fresh Ubuntu install starts in your home directory, which is typically empty.

Check your current location:

ls

If nothing meaningful appears, create a directory for your development work:

mkdir -p ~/dev
cd ~/dev

The -p flag makes this safe to run:

It creates parent directories if they do not exist.
It does not fail if the directory already exists.

That means the command works on both fresh and existing setups.

Note: Keep your project inside WSL (for example ~/dev), not in the Windows filesystem (/mnt/c/...). Working in /mnt/c often causes slower file access, permission issues, and strange behavior with Node.js and Docker.

Confirm your location:

pwd

You should see a path like:

/home/<your-username>/dev

Now clone the Hello World example:

[WSL terminal: new window]

git clone https://github.com/midnightntwrk/example-hello-world.git
cd example-hello-world

Fix the `docker-compose.yml` before running

The default docker-compose.yml in the Hello World repo has two
issues that can make yarn env:up fail on a fresh setup.
Open docker-compose.yml and find the proof-server service block.

It currently looks like this:

proof-server:
  image: 'midnightntwrk/proof-server:8.0.3'
  command: ['midnight-proof-server -v']
  ports:
    - '127.0.0.1:6300:6300'
  environment:
    RUST_BACKTRACE: 'full'
  healthcheck:
    test: ['CMD', 'curl', '-f', 'http://localhost:6300/version']
    interval: 10s
    timeout: 5s
    retries: 20
    start_period: 10s

Replace it with:

proof-server:
  image: 'midnightntwrk/proof-server:8.0.3'
  command: ['midnight-proof-server', '-v']
  ports:
    - '127.0.0.1:6300:6300'
  environment:
    RUST_BACKTRACE: 'full'
  healthcheck:
    test: ['CMD-SHELL', 'echo > /dev/tcp/127.0.0.1/6300']
    interval: 10s
    timeout: 5s
    retries: 20
    start_period: 10s

Two things changed:

command: the original passes the entire string as a single executable, which fails silently. The corrected version passes the flag as a separate argument as Docker expects.
healthcheck: the original uses curl to check if the server is ready, but the proof server image is a minimal production image and does not include curl. The replacement uses a TCP socket check via bash's built-in /dev/tcp, which works without any additional tools.

Note: These issues have been reported upstream. See
issue #16 and PR #17.
If the PR has merged by the time you read this, your file may
already have the corrected command. Only apply the changes that
differ from what you see.

Install dependencies:

yarn install

Create the contract file:

touch contracts/hello-world.compact
code . # opens VS Code for the current working directory

Open contracts/hello-world.compact in VS Code and paste the following:

pragma language_version >= 0.22;

export ledger message: Opaque<"string">;

export circuit storeMessage(newMessage: Opaque<"string">): [] {
  message = disclose(newMessage);
}

A quick breakdown of what this contract does:

ledger message declares a public, persistent on-chain state variable that stores a string.
circuit storeMessage defines the logic to update that variable.
newMessage is a private input by default. The disclose() call marks it safe to write to public ledger state. Without it, the compiler rejects the assignment.

Compile the contract. The compact compile command expects paths
relative to the contracts/ directory, so navigate into it first:

cd contracts
compact compile hello-world.compact managed/hello-world.compact

After compilation completes, navigate back to the project root
before running the next commands:

cd ..

Expected output:

Compiling 1 circuits:
  circuit "storeMessage" (k=6, rows=26)

This generates ZK circuits, proving and verifying keys, and TypeScript API bindings in the contracts/managed/ directory.

Start the local Devnet environment. The first run pulls the required Docker images. Run this in the project terminal while the proof server stays open in the other terminal:

yarn env:up

In your second terminal, deploy and run the test:

yarn test:local

A successful run looks like this:

[12:46:12.694] INFO: Wallet sync complete after 23 emissions
[12:46:12.703] INFO: Providers initialized. Ready to test
[12:46:32.347] INFO: Contract deployed at: bba6579743ae23b44301d4a9f8df30dbd5244d63a59d8fbc2c9fc7ea521a04f8

 ✓ Hello World Contract > Deploys the contract   19649ms
 ✓ Hello World Contract > Stores a message        18184ms

Your Midnight dev environment is now working on Windows.

Troubleshooting

Proof server crashes or goes silent

Cause: WSL2 ran out of memory.

Fix: Open .wslconfig and increase the memory value (minimum 4GB, recommended 8GB). Shut down WSL2 with wsl --shutdown from a Windows terminal, then restart Ubuntu and rerun the proof server.

`docker: command not found` inside WSL

Cause: Docker Desktop's WSL2 integration is not enabled for your distro.

Fix: Open Docker Desktop → Settings → Resources → WSL Integration → enable your Ubuntu distro → Apply & Restart.

`compact: command not found` after installation

Cause: The PATH update was not applied to the current shell session.

Fix:

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

`compact update` fails with “Failed to spawn artifact extraction command”

Cause: Missing system utilities (unzip, tar, etc.) in WSL.

Fix:

sudo apt update
sudo apt install -y unzip tar gzip curl

Verify:

which unzip
which tar

Retry:

compact update

If it still fails:

rm -rf ~/.compact

Then reinstall.

Port 6300 already in use

Cause: An earlier proof server container is still running.

Fix: Find and stop it:

docker ps
docker stop <container_id>

Or run the proof server on an alternate port and update your app config to match:

docker run -p 6301:6300 midnightntwrk/proof-server:8.0.3 midnight-proof-server -v

`yarn test:local` hangs indefinitely

Cause: The proof server is not running, or Docker is not accessible from WSL2.

Fix: Confirm the proof server terminal is active and showing the listening log. Confirm docker ps returns results from your WSL2 terminal. If Docker is not visible, re-check the WSL integration setting in Docker Desktop.

Working `.wslconfig` reference

Save this file at C:\Users\<YourUsername>\.wslconfig:

[wsl2]
# Memory: minimum 4GB for proof server, 8GB recommended
memory=8GB

# CPU cores available to WSL2
processors=4

# Optional swap space
swap=2GB

# Allow localhost forwarding between Windows and WSL2 (needed for Docker port access)
localhostForwarding=true

After saving, always run wsl --shutdown from a Windows terminal and restart Ubuntu for changes to take effect.

Next steps

Your environment is configured and verified. Next:

Read the Compact language reference to understand how to model privacy in smart contracts.
Explore the full examples library for DApps with more complex state and circuit logic.
Join the Midnight developer forum and Discord for community support and announcements.

If you find an outdated step, leave a comment or ask in the Midnight Discord. If you publish your own build notes, tag @midnightntwrk.

DEV Community: Uroy Nwankwo

Setting up Midnight on Windows via WSL2: The Complete Guide

What does not work on Windows

Step 1: Install and configure WSL2

Step 2: Configure WSL2 memory with .wslconfig

Step 3: Set up Docker Desktop with the WSL2 backend

Step 4: Install Node.js inside WSL2

Step 5: Install the Compact compiler

Install a package manager

Step 6: Start the proof server

Step 7: Install the Compact VS Code extension

Step 8: Deploy the Hello World contract

Fix the docker-compose.yml before running

Troubleshooting

Proof server crashes or goes silent

docker: command not found inside WSL

compact: command not found after installation

compact update fails with “Failed to spawn artifact extraction command”

Port 6300 already in use

yarn test:local hangs indefinitely

Working .wslconfig reference

Next steps

Step 2: Configure WSL2 memory with `.wslconfig`

Fix the `docker-compose.yml` before running

`docker: command not found` inside WSL

`compact: command not found` after installation

`compact update` fails with “Failed to spawn artifact extraction command”

`yarn test:local` hangs indefinitely

Working `.wslconfig` reference