When the user wants to create a new project, first infer as many options as possible from the user's request (for example, "new Mojo project" means type=Mojo, "called foo" means name=foo). Then use a structured multiple-choice prompt (not plain text) to gather only the remaining unspecified options in a single interaction. Do NOT ask about options the user has already provided or implied. The options to determine are:
- Project name: ask if the user hasn't specified one.
- Type of project: Mojo or MAX (infer from context if the user said "Mojo project" or "MAX project").
- Environment manager:
pixi(recommended) oruv. - uv project type (only when the environment manager is
uv): full uv project (uv init+uv add, recommended) or quick uv environment (uv venv+uv pip install, lighter weight). - Channel: nightly or stable. Default to nightly for MAX projects and stable for Mojo projects, and ask only if the user hasn't implied one.
Then follow the appropriate section below (pixi or uv) to initialize the
project and choose max or mojo as appropriate. Don't pin a version: each
channel already resolves to the right one.
MAX and Mojo ship together but number their releases differently, so their
version strings don't look alike. On the stable channel, max is 26.5
while mojo is 1.0.0; on nightly they're 26.6.0.dev* and 1.1.0.dev*.
That's expected, not a mismatch.
[!NOTE] Mojo and MAX projects use
pixi. ThemagicCLI is retired; its replacement is themodularCLI. Don't use or suggestmagic.
System prerequisites
Mojo requires a C linker for compilation. Install one if not already present:
Windows users: Mojo doesn't run natively on Windows.
Install WSL2
(wsl --install in PowerShell), then follow the Linux instructions
inside your WSL environment.
Pixi (recommended)
Pixi manages Python, Mojo, and other dependencies in a reproducible manner inside a controlled environment.
First, determine whether pixi is installed. If it isn't available at the
command line, install it using the latest instructions at
https://pixi.prefix.dev/latest/#installation.
After installing pixi, you may need to add it to the local shell environment.
Nightly
Stable
Python-using projects
If your project uses Python libraries with Mojo:
uv
uv is a fast and very popular package manager, familiar to developers coming
from a Python background. It also works well with Mojo projects.
Nightly (project)
Stable (project)
This resolves from PyPI. The all extra pulls in mojo and the rest of the
MAX stack, so the MAX and Mojo versions always match.
Nightly (quick environment)
Stable (quick environment)
When using uv, you can use max or mojo directly by working within the
project environment:
pip
Standard Python package manager.
Nightly
Use --extra-index-url, not --index-url. The latter replaces PyPI, and the
nightly index doesn't carry third-party dependencies like numpy, so pip
backtracks through every max version instead of reporting a clear error.
Stable
As with uv, the all extra installs mojo as well, so the MAX and Mojo
versions always match.
Conda
For conda and mamba users.
Nightly
Stable
Version alignment with MAX
If using MAX with custom Mojo kernels, both must come from the same channel.
Don't compare their version numbers: MAX and Mojo number releases
differently, so a matching pair looks mismatched (stable is max 26.5
with mojo 1.0.0).
Or, instead install max[all] (with pip/uv) or max-all (with conda/pixi):
Installing max with "all" optional dependencies instead of installing max
and mojo separately will ensure that the max and mojo versions always
match. Mixing versions between the two causes kernel compilation failures.
