Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/n64decomp/sm64/llms.txt

Use this file to discover all available pages before exploring further.

Windows is supported through two approaches: the Windows Subsystem for Linux (WSL) and MSYS2. WSL2 is the recommended path because it provides a full Linux kernel and the widest compatibility with the build toolchain.
Once your Linux environment is set up, the actual build steps are identical to the Linux build guide. This page covers only the Windows-specific setup.
WSL lets you run a Linux distribution directly on Windows without a virtual machine. WSL2 is strongly preferred over WSL1.
WSL1 does not support Ubuntu 20.04 or later. If you want to use Ubuntu, install WSL2 or use Ubuntu 18.04 under WSL1. Debian is a reliable alternative that works under both versions.
1

Enable WSL and install a distribution

Follow the official Microsoft guide to install WSL2 and a Linux distribution of your choice:Windows Subsystem for Linux Installation Guide for Windows 10The recommended distributions are Debian or Ubuntu 18.04. Both are available in the Microsoft Store after WSL is enabled.For Windows 11 and recent Windows 10 builds, you can install WSL2 with a single command in an elevated PowerShell:
wsl --install
Then install your preferred distribution:
wsl --install -d Debian
2

Confirm you are running WSL2

In PowerShell, verify the WSL version assigned to your distribution:
wsl --list --verbose
The VERSION column should show 2. If it shows 1, upgrade with:
wsl --set-version <DistroName> 2
3

Open your Linux shell

Launch your installed distribution from the Start menu or by running wsl in PowerShell. All subsequent steps run inside this Linux shell.
4

Follow the Linux build instructions

Inside your WSL shell, follow the Linux build guide for your chosen distribution to install dependencies, clone the repository, place the baserom, and run make.
# Example for Debian / Ubuntu inside WSL
sudo apt install -y binutils-mips-linux-gnu build-essential git pkgconf python3
git clone https://github.com/n64decomp/sm64.git
cd sm64
cp /mnt/c/Users/<YourName>/Downloads/sm64.z64 baserom.us.z64
make VERSION=us -j4
Your Windows drives are mounted under /mnt/ inside WSL (e.g., C:\ is /mnt/c/). Use these paths to copy the baserom from your Windows filesystem into the WSL environment.

​
Option 2: MSYS2

MSYS2 provides a Unix-like shell and package manager (pacman) on native Windows. It is a supported alternative if you prefer not to use WSL.
1

Install MSYS2

Download and run the MSYS2 installer from msys2.org. Follow the on-screen instructions to complete the installation.
2

Update the package database

Open the MSYS2 MinGW 64-bit shell and update all packages:
pacman -Syu
Close and reopen the shell if prompted, then run:
pacman -Su
3

Install build dependencies

Install the required tools through pacman. You will need a MIPS cross-compiler toolchain appropriate for your MSYS2 environment, along with Python and the base development tools:
pacman -S base-devel python3
Install the MIPS binutils cross-compiler package matching your MSYS2 environment. Refer to the MSYS2 package repository for the current package name.
4

Clone the repository and build

From the MSYS2 shell, clone the repository and run make as you would on Linux:
git clone https://github.com/n64decomp/sm64.git
cd sm64
cp /c/Users/<YourName>/Downloads/sm64.z64 baserom.us.z64
make VERSION=us -j4

​
Troubleshooting

WSL1 has known incompatibilities with the build toolchain, especially on newer Ubuntu releases. Upgrade to WSL2 (see step 2 above) or switch to Debian, which tends to be more stable under WSL1.
Windows drives are accessible inside WSL at /mnt/<drive-letter>/. For example, a file at C:\Users\Name\Downloads\sm64.z64 can be copied with:
cp /mnt/c/Users/Name/Downloads/sm64.z64 baserom.us.z64
Ensure the full path to your cloned repository (as seen inside the Linux shell) does not exceed 255 characters. Clone closer to the filesystem root if needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us