new-modular-project

当用户想要创建新项目时，首先从用户的请求中尽可能推断选项（例如，“新建 Mojo 项目”表示 type=Mojo，“名为 foo”表示 name=foo）。然后使用结构化的多选提示（而非纯文本），通过一次交互仅收集其余未指定的选项。不要询问用户已提供或暗示过的选项。需要确定的选项如下：

• 项目名称：如果用户尚未指定，则询问。
• 项目类型：Mojo 或 MAX（如果用户提到“Mojo 项目”或“MAX 项目”，则据此推断）。
• 环境管理器：pixi（推荐）或 uv。
• uv 项目类型（仅当环境管理器为 uv 时）：完整 uv 项目（uv init + uv add，推荐）或快速 uv 环境（uv venv + uv pip install，更轻量）。
• 频道：nightly 或 stable。MAX 项目默认使用 nightly，Mojo 项目默认使用 stable；仅在用户未暗示频道时询问。

然后按照下方相应章节（pixi 或 uv）初始化项目，并酌情选择 max 或 mojo。不要固定版本：每个频道都会解析到正确的版本。

MAX 和 Mojo 会一同发布，但版本编号方式不同，因此版本字符串看起来并不相同。在 stable 频道中，max 的版本为 26.5，而 mojo 的版本为 1.0.0；在 nightly 频道中，版本分别为 26.6.0.dev* 和 1.1.0.dev*。这是正常的，并非版本不匹配。

说明

Mojo 和 MAX 项目使用 pixi。magic CLI 已停用，其替代品是 modular CLI。不要使用或建议使用 magic。

---

系统先决条件

Mojo 编译需要 C 链接器。如果尚未安装，请安装一个：

操作系统	命令
Ubuntu/Debian	sudo apt install gcc
Fedora/RHEL	sudo dnf install gcc
macOS	xcode-select --install
Windows	请先安装 WSL2（参见 Windows 用户），然后安装 gcc

Windows 用户：Mojo 无法在 Windows 上原生运行。 请安装 WSL2 （在 PowerShell 中运行 wsl --install），然后按照 WSL 环境中的 Linux 说明操作。

---

Pixi（推荐）

Pixi 会在受控环境中以可复现的方式管理 Python、Mojo 和其他依赖项。

首先，确认是否已安装 pixi。如果无法在命令行中使用，请按照 https://pixi.prefix.dev/latest/#installation 上的最新说明安装。

安装 pixi 后，可能需要将其添加到本地 shell 环境中。

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 的项目

如果项目将 Python 库与 Mojo 配合使用：

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

---

uv

uv 是一款快速且非常流行的包管理器，对于有 Python 开发背景的开发者来说十分熟悉。它也能很好地用于 Mojo 项目。

Nightly（项目）

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

Stable（项目）

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

这会从 PyPI 解析依赖项。all 附加项会引入 mojo 和其余 MAX 堆栈，因此 MAX 和 Mojo 的版本始终匹配。

Nightly（快速环境）

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

Stable（快速环境）

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

使用 uv 时，可以在项目环境中直接使用 max 或 mojo：

 source .venv/bin/activate

---

pip

标准 Python 包管理器。

Nightly

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

请使用 --extra-index-url，而不是 --index-url。后者会替换 PyPI，而 nightly 索引不包含 numpy 等第三方依赖项，因此 pip 会遍历每个 max 版本进行回溯，而不是报告清晰的错误。

Stable

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

与 uv 一样，all 附加项也会安装 mojo，因此 MAX 和 Mojo 的版本始终匹配。

---

Conda

适用于 conda 和 mamba 用户。

Nightly

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

稳定版

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

---

与 MAX 的版本对齐

如果使用 MAX 和自定义 Mojo 内核，两者必须来自同一发布渠道。 不要比较它们的版本号：MAX 和 Mojo 的版本编号方式不同，因此匹配的版本组合看起来会不匹配（稳定版组合为 max 26.5 和 mojo 1.0.0）。

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

或者，改为安装 max[all]（使用 pip/uv）或 max-all（使用 conda/pixi）：

uv add "max[all]"

pixi add max-all

安装带有“所有”可选依赖项的 max，而不是分别安装 max 和 mojo，可确保 max 和 mojo 版本始终匹配。混用两者的不同版本会导致内核编译失败。

---

参考资料

• Mojo 安装指南
• Mojo 稳定版文档
• Mojo Nightly 文档