Skip to main content

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.

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:

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"

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 you can also create a pyproject.toml or mojoproject.toml file for enhanced Python and Mojo project features, respectively.

Create a Python project

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

  1. Create a Python project with the magic init command:

    magic init my-project
    magic init my-project

    This creates a my-project directory and a pixi.toml file that defines the project dependencies and more. (If you omit the directory name, it creates the pixi.toml file in the current directory.)

  2. Enter the project and use magic add to set the Python version:

    cd my-project
    cd my-project
    magic add "python==3.11"
    magic add "python==3.11"
  3. Use magic run to execute code inside the virtual environment:

    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.

  4. To install Python packages for your project, use magic add:

    magic add max
    magic add max

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

A Mojo project is defined with either a pixi.toml or mojoproject.toml file. Currently, these files behave the same, but the mojoproject.toml file allows us to add support for Mojo-specific features in the future.

  1. 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.

  2. 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

    Or, activate the environment shell with magic shell:

    magic shell
    magic shell
    mojo --version
    mojo --version

    Then use exit to deactivate the shell:

    exit
    exit

    Always exit the shell before changing projects.

  3. 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"

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

Manage packages

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

magic add max "numpy<2.0"
magic add max "numpy<2.0"

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

By default, Magic looks for packages in the conda-forge repository (as specified by your config file channels).

If you prefer to use PyPI for your packages, add the --pypi flag:

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 pixi.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

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, 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.5"
magic add "max~=24.5"

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

For more information, read about Pixi dependency tables.

Change the Python version

You can also use magic add to change your Python version with a version specifier. For example:

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.

More reading

You can learn more about the available commands by printing the help:

magic -h
magic -h

Or see all the Magic commands here.

If you have more questions, see the Magic FAQ.

And because Magic is built upon pixi, you can also learn more from the pixi documentation (just replace each pixi command with magic). However, there are several differences between magic and pixi. For example, magic does not support exec, auth, and upload commands, and probably others to come.