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:

OS	Command
Ubuntu/Debian	sudo apt install gcc
Fedora/RHEL	sudo dnf install gcc
macOS	xcode-select --install
Windows	Install WSL2 first (see Windows users), then install gcc

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