Install guide

You can install all the Modular APIs and tools (including MAX and Mojo) as a single package called modular, using pip or magic (or other Python and Conda package managers).

The modular package is available as a nightly and a stable build. You can also select the latest nightly or stable documentation, using a drop-down in the website header. By default, we show the nightly version so you always see the latest APIs and documentation.

If you just want to get started, instead see our quickstart guide.

If you'll mostly be programming in Mojo, we recommend installing with magic, because the pip package currently doesn't include the Mojo LSP or debugger.

Install

To get the latest performance improvements and new features, we recommend installing our nightly build, which we release several times a week. If you want a better tested but slightly older version, you can install a stable build. (Each stable release is described in the changelog.)

pip

1. Create a project folder:

   mkdir modular && cd modular

   mkdir modular && cd modular
2. Create and activate a virtual environment:

   python3 -m venv .venv/modular \
     && source .venv/modular/bin/activate

   python3 -m venv .venv/modular \
     && source .venv/modular/bin/activate
3. Install the modular Python package:
   Nightly

   pip install modular \
     --index-url https://download.pytorch.org/whl/cpu \
     --extra-index-url https://dl.modular.com/public/nightly/python/simple/

   pip install modular \
     --index-url https://download.pytorch.org/whl/cpu \
     --extra-index-url https://dl.modular.com/public/nightly/python/simple/

   Stable

   pip install modular \
     --index-url https://download.pytorch.org/whl/cpu

   pip install modular \
     --index-url https://download.pytorch.org/whl/cpu

uv

1. Install uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh

   curl -LsSf https://astral.sh/uv/install.sh | sh

   Then restart your terminal to make uv accessible.

2. Create a project:

   uv init modular && cd modular

   uv init modular && cd modular
3. Create and start a virtual environment:

   uv venv && source .venv/bin/activate

   uv venv && source .venv/bin/activate
4. Install the modular Python package:
   Nightly

   uv pip install modular \
     --index-url https://download.pytorch.org/whl/cpu \
     --extra-index-url https://dl.modular.com/public/nightly/python/simple/

   uv pip install modular \
     --index-url https://download.pytorch.org/whl/cpu \
     --extra-index-url https://dl.modular.com/public/nightly/python/simple/

   Stable

   uv pip install modular \
     --index-url https://download.pytorch.org/whl/cpu

   uv pip install modular \
     --index-url https://download.pytorch.org/whl/cpu

magic

1. Install magic:

   curl -ssL https://magic.modular.com/ | bash

   curl -ssL https://magic.modular.com/ | bash

   Then run the source command that's printed in your terminal.

2. Create a project:

   magic init modular --format pyproject && cd modular

   magic init modular --format pyproject && cd modular
3. Install the max-pipelines conda package:
   Nightly

   magic add max-pipelines

   magic add max-pipelines

   Stable

   magic add "max-pipelines==25.3"

   magic add "max-pipelines==25.3"
4. Start the virtual environment:

   magic shell

   magic shell

The modular package installs MAX, Mojo, and other package dependencies.

GitHub stable branch

When using a stable build, make sure you also checkout the stable branch when you clone the Modular repo (because the main branch includes the latest nightly code). For example:

git clone -b stable https://github.com/modular/modular.git

git clone -b stable https://github.com/modular/modular.git

Uninstall

pip

You can uninstall modular from your virtual environment with the following command:

pip uninstall modular

pip uninstall modular

To deactivate your virtual environment, run:

deactivate

deactivate

uv

You can uninstall modular from your virtual environment with the following command:

uv pip uninstall modular

uv pip uninstall modular

To deactivate your virtual environment, run:

deactivate

deactivate

magic

If you installed with magic, just delete the project paths that you created with magic init (paths with a pyproject.toml, mojoproject.toml, or pixi.toml file).

To remove the magic tool, delete the magic binary:

rm ~/.modular/bin/magic

rm ~/.modular/bin/magic

What's included

pip

The modular Python wheel installs the following:

• MAX tools and libraries
  • max CLI
  • max Python library
  • max Mojo library
• Mojo tools and libraries
  • mojo CLI
  • Mojo standard library

pip known issues:

• The Mojo LSP and Mojo debugger aren't included. If you want to develop with Mojo, we currently recommend you install the modular conda package with Magic or conda.

magic

The max conda package installs the following:

• MAX tools and libraries
  • max Python library
  • max Mojo library
  • MAX Engine C API
• Mojo tools and libraries
  • mojo CLI
  • Mojo standard library
  • Mojo LSP
  • Mojo debugger

The max-pipelines package installs the max CLI.

magic known issues:

• You might encounter issues if you invoke magic within a conda virtual environment. It's best if you don't mix the two tools.

Next steps

Was this page helpful?

Thank you! We'll create more content like this.

Thank you for helping us improve!

😔 What went wrong?

Some code doesn’t work

It includes inaccurate information

It's missing information I need

It was difficult to understand

Other

Submit