new-modular-project

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) or uv.
• 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] Don't look for or use magic for Mojo or MAX projects; it's no longer supported. Pixi has fully replaced its capabilities.

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

# New project
pixi init [PROJECT] \
  -c https://conda.modular.com/max-nightly/ -c conda-forge \
  && cd [PROJECT]

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.

References

• Mojo Installation Guide
• Mojo Stable Docs
• Mojo Nightly Docs