How to install

How to install

This guide installs the pinned Mojo toolchain into a local .venv. Nothing is installed system-wide. At the end, make check-cpu passes.

Requirements

Platform	Support	Note
macOS	Yes	Apple Silicon only. Mojo does not support Intel Macs.
Linux	Yes	x86-64 and aarch64.
Windows	Through WSL 2	Mojo has no native Windows build.

You also need Python 3.9 or later, git, make and uv.

macOS

1. Install the tools:

brew install uv xorg-server
xcode-select --install

xorg-server gives Xvfb and libX11. The window tests start an Xvfb server. See Windowing and controls.

2. Clone and install the toolchain:

git clone https://github.com/SethKitchen/ThreeMojo.git
cd ThreeMojo
uv python install --no-bin 3.12.14
"$(uv python find --managed-python --no-project 3.12.14)" -m venv --without-pip --prompt ThreeMojo .venv
uv pip install "mojo==1.1.0"

Linux

1. Install the tools. On Debian or Ubuntu:

sudo apt update && sudo apt install -y build-essential curl git xvfb
curl -LsSf https://astral.sh/uv/install.sh | sh

On Fedora, use sudo dnf install -y make gcc git curl xorg-x11-server-Xvfb. On Arch, use sudo pacman -S --needed base-devel git curl xorg-server-xvfb. The window tests start an Xvfb server.

2. Clone and install the toolchain:

git clone https://github.com/SethKitchen/ThreeMojo.git
cd ThreeMojo
uv python install --no-bin 3.12.14
"$(uv python find --managed-python --no-project 3.12.14)" -m venv --without-pip --prompt ThreeMojo .venv
uv pip install "mojo==1.1.0"

Windows

1. Open PowerShell as Administrator and install WSL 2:

wsl --install -d Ubuntu

2. Reboot. Open the Ubuntu terminal.
3. Follow the Linux steps above.

Clone into the Linux filesystem, for example ~/ThreeMojo. Do not clone into /mnt/c/. Builds across the filesystem boundary are much slower.

The environment uses an upstream CPython that uv manages. make coverage refuses an interpreter that loads import hooks. Homebrew's Python loads a sitecustomize module, and uv venv adds an import hook, so neither can measure coverage. CI builds its environment the same way.

Without uv

python3 -m venv .venv
.venv/bin/pip install "mojo==1.1.0"

Verify

.venv/bin/mojo --version    # Mojo 1.1.0 (8189361e)
make check-cpu

make check-cpu needs no GPU and no MAX. For the GPU backend, see How to use the GPU backend.

Pinned versions

Component	Version	Needed for
Mojo	1.1.0 (8189361e)	Everything
MAX	26.6.0	render/gpu.mojo and its tests only
Metal toolchain	Xcode component	GPU kernels on macOS
Xvfb	Any	tests/test_x11.mojo

The toolchain version is part of the build cache key. An upgrade invalidates every cached result.

The pin is exact, not a floor. Mojo 1.1 moved the async task runtime behind an underscore, and moved gpu out of std into max. So one source cannot serve both 1.0 and 1.1: 1.0 has no std.runtime._asyncrt, and 1.1 has no std.runtime.asyncrt. See Rasterization and GPU backend.

Agent skills

The repository pins three Modular skills that teach an AI agent to write Mojo. skills-lock.json is committed; the fetched skills are not.

npx skills experimental_install   # restore the pinned skills
npx skills update -p -y           # bump them, and rewrite the lockfile

They land in .agents/skills/ or .claude/skills/. Both are ignored by git. Neither the build nor the tests read them, so this step is optional.

Editor setup

The Mojo language server does not read -I .. The repository ships .vscode/settings.json with "mojo.lsp.includeDirs": ["."], which fixes the imports.

1. Install the Mojo extension by Modular.
2. Reload the window. The setting is read at language-server startup.

The value must be ".". The extension does not expand ${workspaceFolder}.

Activate the virtualenv

The Makefile calls .venv/bin/mojo by path. You do not need to activate the virtualenv. If you want to:

Shell	Command
bash or zsh	source .venv/bin/activate
fish	source .venv/bin/activate.fish
PowerShell	.venv\Scripts\Activate.ps1