new-modular-project

Original：🇺🇸 English

Translated

Creates a new Mojo or MAX project. Use when wanting to start a new Mojo or MAX project, initializing the Pixi or UV environment to use Mojo or MAX, or when the user wants to begin a new Mojo or MAX project from scratch.

2installs

Sourcemodular/skills

Added on2026-03-17

NPX Install

npx skill4agent add modular/skills new-modular-project

SKILL.md Content

View Translation Comparison →

When the user wants to create a new project, first infer as many options as possible from the user's request (e.g., "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 not specified
Type of project — Mojo or MAX (infer from context if the user said "Mojo project" or "MAX project")
Environment manager — Pixi (recommended) or uv
If uv: UV project type — full uv project (
```
uv init
```
+
```
uv add
```
, recommended) or quick uv environment (
```
uv venv
```
+
```
uv pip install
```
, lighter weight)
Channel — nightly (latest features, recommended) or stable (production)

Then follow the appropriate section below (Pixi or uv) to initialize the project and choose

max

or

mojo

as appropriate. For stable versions in the below examples,

mojo

will start with a 0. prefix (0.26.1.0.0.0) where

max

packages will not (26.1.0.0.0).

NOTE: Do not look for or use

magic

for Mojo or MAX projects, it is no longer supported. Pixi has fully replaced its capabilities.

Pixi (Recommended)

Pixi manages Python, Mojo, and other dependencies in a reproducible manner inside a controlled environment.

First, determine if

pixi

is installed. If it is not available for use at the command line, install it using the latest instructions found on https://pixi.prefix.dev/latest/#installation

You may need to place the

pixi

tool in the local shell environment after installation if it had not already been installed.

Nightly

bash

# 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 (v26.1.0.0.0)

bash

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

# Existing project
pixi add "[max / mojo]==0.26.1.0.0.0"

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)

bash

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

Stable (project)

bash

uv init [PROJECT] && cd [PROJECT]
uv add [max / mojo] \
  --extra-index-url https://modular.gateway.scarf.sh/simple/

Nightly (quick environment)

bash

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

Stable (quick environment)

bash

mkdir [PROJECT] && cd [PROJECT]
uv venv
uv pip install [max / mojo] \
  --extra-index-url https://modular.gateway.scarf.sh/simple/

When using

uv

, you can use

max

or

mojo

directly by working within the project environment:

bash

 source .venv/bin/activate

pip

Standard Python package manager.

Nightly

bash

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

Stable

bash

python3 -m venv .venv && source .venv/bin/activate
pip install [max / mojo] \
  --extra-index-url https://modular.gateway.scarf.sh/simple/

Conda

For conda/mamba users.

Nightly

bash

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

Stable (v26.1.0.0.0)

bash

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

Version Alignment with MAX

If using MAX with custom Mojo kernels, versions must match:

bash

# Check alignment
uv pip show mojo | grep Version   # e.g., 0.26.2
pixi run mojo --version           # Must match major.minor (e.g., 0.26.2)

Mismatched versions cause kernel compilation failures. Always use the same channel (stable or nightly) for both.

new-modular-project

NPX Install

Tags

SKILL.md Content

Pixi (Recommended)

Nightly

Stable (v26.1.0.0.0)

uv

Nightly (project)

Stable (project)

Nightly (quick environment)

Stable (quick environment)

pip

Nightly

Stable

Conda

Nightly

Stable (v26.1.0.0.0)

Version Alignment with MAX

References