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]
pixi add [max / mojo]
pixi shell

# Existing project - add to pixi.toml channels first:
# [workspace]
# channels = ["https://conda.modular.com/max-nightly/", "conda-forge"]
pixi add [max / mojo]

Stable

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

# Existing project
pixi add [max / mojo]

Python-using projects

If your project uses Python libraries with Mojo:

pixi add python
pixi add requests           # conda-forge packages
pixi add --pypi some-pkg    # PyPI-only packages

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)

uv init [PROJECT] && cd [PROJECT]
uv add [max / mojo] \
  --index https://whl.modular.com/nightly/simple/ \
  --prerelease allow

Stable (project)

uv init [PROJECT] && cd [PROJECT]
uv add "max[all]"

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)

mkdir [PROJECT] && cd [PROJECT]
uv venv
uv pip install [max / mojo] \
  --index https://whl.modular.com/nightly/simple/ \
  --prerelease allow

Stable (quick environment)

mkdir [PROJECT] && cd [PROJECT]
uv venv
uv pip install "max[all]"

When using uv, you can use max or mojo directly by working within the project environment:

 source .venv/bin/activate

pip

Standard Python package manager.

Nightly

python3 -m venv .venv && source .venv/bin/activate
pip install --pre [max / mojo] \
  --extra-index-url https://whl.modular.com/nightly/simple/

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

python3 -m venv .venv && source .venv/bin/activate
pip install "max[all]"

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

conda install -c conda-forge \
  -c https://conda.modular.com/max-nightly/ [max / mojo]

Stable

conda install -c conda-forge \
  -c https://conda.modular.com/max/ [max / mojo]

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).

# Check that both came from the same channel
pixi list | grep -E "^(max|mojo)\b"

Or, instead install max[all] (with pip/uv) or max-all (with conda/pixi):

uv add "max[all]"

pixi add max-all

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