Get started with Magic

Magic is a package manager and virtual environment manager for any language, including Python and Mojo. It builds upon the conda and PyPI packaging ecosystems, which provide access to thousands of packages for Python and other languages, while also adding functionality for MAX and Mojo.

The magic CLI allows you to instantly launch code examples and create new projects that are fully contained and reproducible across systems. All the package dependencies and environment settings are magically managed for you.

This page provides an introduction to basic magic commands. For a deep-dive into more features, see the Magic tutorial.

Magic is built upon pixi, so you'll see this name appear below.

Install Magic

You can install Magic on macOS and Ubuntu with this command:

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.

To see the available commands, print the help:

magic --help
magic --help

Enable auto-completion

To enable auto-completion for magic, run the following commands:

Bash
ZSH
fish

BASHRC=$( [ -f "$HOME/.bash_profile" ] && echo "$HOME/.bash_profile" || echo "$HOME/.bashrc" )
echo 'eval "$(magic completion --shell bash)"' >> "$BASHRC"
source "$BASHRC"
BASHRC=$( [ -f "$HOME/.bash_profile" ] && echo "$HOME/.bash_profile" || echo "$HOME/.bashrc" )
echo 'eval "$(magic completion --shell bash)"' >> "$BASHRC"
source "$BASHRC"

echo 'eval "$(magic completion --shell zsh)"' >> ~/.zshrc
source ~/.zshrc
echo 'eval "$(magic completion --shell zsh)"' >> ~/.zshrc
source ~/.zshrc

echo 'magic completion --shell fish | source' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish
echo 'magic completion --shell fish | source' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Update Magic

You can update with the self-update command:

magic self-update

magic self-update

Uninstall Magic

To remove Magic, delete the binary:

rm ~/.modular/bin/magic
rm ~/.modular/bin/magic

To remove packages installed for your projects, delete the corresponding project directories.

Create a project

You can create a project with its own package dependencies and virtual environment using the magic init command.

By default, this creates a configuration file called pixi.toml, but we recommend that you specify the --format option as shown below, to instead create a pyproject.toml or mojoproject.toml file for enhanced Python and Mojo features, respectively.

MAX build versions

MAX is available as either a stable or nightly build. For more detail about installing MAX versions, instead see MAX packages.

Create a Python project

Here's how to create a new Python project and install MAX:

Create a Python project with the magic init command:
```
magic init my-project --format pyproject
```
```
magic init my-project --format pyproject
```
This creates a my-project directory and a pyproject.toml file that defines the project dependencies and more. (If you omit the directory name, it creates the pyproject.toml file in the current directory.)
Enter the project directory and use magic run to execute code inside the virtual environment:
```
cd my-project
```
```
cd my-project
```
```
magic run python3 --version
```
```
magic run python3 --version
```
Or, activate the environment shell with magic shell:
```
magic shell
```
```
magic shell
```
```
python3 --version
```
```
python3 --version
```
Then use exit to deactivate the shell:
```
exit
```
```
exit
```
Always exit the shell before changing projects.
If you want a different Python version, open the pyproject.toml file and edit the version specifier defined with this line:
```
requires-python = ">= 3.11"
```
```
requires-python = ">= 3.11"
```
To install Python packages for your project, use magic add. We recommend you always specify the version, for example:
```
magic add "max~=24.6"
```
```
magic add "max~=24.6"
```

You can run commands such as magic add anywhere inside a Magic project directory, whether or not you've activated the shell.

For more information about using Magic for your Python projects, read using Pixi for Python (just replace each pixi command with magic).

Create a Mojo project

Here's how to create a new Mojo project:

Create a Mojo project with magic init:
```
magic init my-mojo-project --format mojoproject
```
```
magic init my-mojo-project --format mojoproject
```
This creates the my-mojo-project directory and creates a mojoproject.toml file inside, which defines the project dependencies and more. If you omit the path name, Magic creates the confg file in the current directory.

By default, mojoproject.toml includes max as a dependency because max is the package that installs Mojo.
Enter the project and use magic run to execute code inside the environment:
```
cd my-mojo-project
```
```
cd my-mojo-project
```
```
magic run mojo --version
```
```
magic run mojo --version
```
```
mojo 25.1.0.dev2025012705 (304c3219)
```
```
mojo 25.1.0.dev2025012705 (304c3219)
```
By default, magic creates each project and adds the latest nightly release of MAX/Mojo as a dependency. If you prefer to use a stable release, you can specify the version you want like this:
magic add "max~=24.6"
magic add "max~=24.6"
You can also activate the environment shell with magic shell:
```
magic shell
```
```
magic shell
```
```
mojo --version
```
```
mojo --version
```
```
mojo 25.1.0.dev2025012705 (304c3219)
```
```
mojo 25.1.0.dev2025012705 (304c3219)
```
Then use exit to deactivate the shell before changing projects:
```
exit
```
```
exit
```
If you want to use Python with Mojo, specify the Python version and Python packages with magic add. For example:
```
magic add "python==3.9"
```
```
magic add "python==3.9"
```
caution
If your Mojo project has Python package dependencies and you create an executable with mojo build, the executable might not work outside of the Magic environment. That's because the Mojo executable doesn't include the Python packages, so they must be provided in the environment where you run it (such as inside the Magic environment where you built the executable).

You can run commands such as magic add anywhere inside a Magic project directory, whether or not you've activated the shell.

Convert a conda project to Magic

If you have an existing conda project, you can convert the environment.yml configuration file to Magic with this command:

magic init --import environment.yml
magic init --import environment.yml

caution

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

Manage packages

You can add Python and Mojo packages to your project by running magic add inside your project directory (every project has its own package versions). For example:

magic add "max~=24.6" "numpy<2.0"
magic add "max~=24.6" "numpy<2.0"

This adds version 24.6 of MAX and the latest version of NumPy that's less than 2.0.

Default channels

When you create a new project with magic, the project configuration includes some default conda channels where magic looks for packages. The channel names appear in your pyproject.toml or mojoproject.toml like this:

channels = ["https://conda.modular.com/max-nightly", "https://conda.modular.com/max", "https://repo.prefix.dev/modular-community", "conda-forge"]

channels = ["https://conda.modular.com/max-nightly", "https://conda.modular.com/max", "https://repo.prefix.dev/modular-community", "conda-forge"]

Here's a brief explanation of these channels:

max-nightly includes all MAX packages, including nightly and stable builds. When this channel is in your project, magic add max will install the latest nightly build; if you want a stable build then you must specify the version, such as magic add max==24.6.
max includes only the MAX stable builds. If you never want a nightly version of MAX in your project, then you can delete the max-nightly channel and keep just this one. In that case, magic add max will install the latest stable instead of nightly, but we recommend that you always specify the version with a version specifier.
modular-community includes official community-created packages for MAX. You can also browse these packages on MAX Builds.
conda-forge includes everything else you might want from the conda package community, hosted by https://conda-forge.org.

If you prefer to install PyPI packages instead of conda packages, add the --pypi flag with magic add:

magic add --pypi "numpy<2.0"
magic add --pypi "numpy<2.0"

However, you should avoid mixing conda and PyPi packages in the same project.

Add channels

If the package you want is not available by default with magic add, you might need to add a new conda channel. For example, if you want to install the official version of pytorch instead of the version from conda-forge, edit your pyproject.toml or mojoproject.toml config file to add the "pytorch" channel:

channels = ["pytorch", "conda-forge", "https://conda.modular.com/max"]

channels = ["pytorch", "conda-forge", "https://conda.modular.com/max"]

Then you can install the latest PyTorch as a conda package:

magic add pytorch
magic add pytorch

You can also use magic project channel add to add a channel to your config file, but it adds the channel at the end of the list, which means it is the lowest channel priority.

Update a package

To update a package, use magic update within your project path:

magic update max

magic update max

If there's a new version of MAX (that adheres to the specified package version), this updates the config file and installs it.

Define a package version

Even after you've added a package, you can run magic add again with a new version specifier. For example:

magic add "max~=24.6"
magic add "max~=24.6"

This ensures that the project uses MAX 24.6 but it also allows "compatible" versions such as 24.6.1.

For more information, read about Pixi dependency tables.

Change the Python version

If you created a Python project, open the pyproject.toml file and edit the version specifier defined with this line:

requires-python = ">= 3.11"

requires-python = ">= 3.11"

If you created a Mojo project, you can modify the Python version like any other package dependency:

magic add "python==3.9"
magic add "python==3.9"

The next time you run a magic command, it updates Python with the appropriate version:

magic run python3 --version
magic run python3 --version

Python 3.9.0

Python 3.9.0

The `magic.lock` file

Although the project configuration file (pixi.toml, pyproject.toml, or mojoproject.toml) defines your project dependencies, it doesn't define the project's transitive dependencies, which are the dependencies of your project dependencies. Nor does the configuration file always specify the exact package version that is actually installed (such as when you specify a version merely as less-than < or greater-than >).

The transitive dependencies and actual installed versions are instead specified in the magic.lock file, which is automatically generated—you should not edit this file by hand.

This file is crucial to ensure that you can reliably reproduce your environment across different machines. You can learn more about it from the Pixi lock file docs.

Known issues

You might encounter issues if you invoke magic within a conda or venv virtual environment. It's best if you don't mix Magic with other virtual environment tools.
If you also have pixi installed, it generally should work with projects you created using magic, but you might see some issues so we advise you only use magic for MAX and Mojo projects.
Linux aarch64 (ARM64) does not work with projects using PyTorch 2.2.2.
The MAX Replit pipeline currently doesn't work with the max-conda package.

Install Magic​

Enable auto-completion​

Update Magic​

Uninstall Magic​

Create a project​

Create a Python project​

Create a Mojo project​

Convert a conda project to Magic​

Manage packages​

Default channels​

Add channels​

Update a package​

Define a package version​

Change the Python version​

The magic.lock file​

Known issues​

More reading​