Skip to main content
Product
Developers
Connect
Company
Log inGet started

Get started with Magic

Magic is a package manager and virtual environment manager for MAX and Mojo projects. It builds upon both the conda and pypi packaging ecosystems, providing access to thousands of packages for Python and other languages, while adding additional functionality for MAX and Mojo.

Managing package dependencies on your system is crucial for code stability and compatibility, but that's just half the battle. Virtual environments are also essential to avoid package conflicts between projects and improve code reproducibility across systems. Although tools like pip, brew, and apt help install and update packages, they don't help manage your virtual environments. Although some tools like conda can do both, we needed something that can also handle Mojo and keep up with our evolving requirements for both MAX and Mojo. That's why we created magic.

magic allows you to instantly launch code examples and create new projects that use MAX—all the package dependencies and environment settings magically managed for you.

If you have more questions, check out the Magic FAQ.

Install Magic​

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

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

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

To see all of Magic's commands, print the help:

magic --help

Or see all the Magic commands here.

Enable auto-completion​

To enable auto-completion for magic commands, 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"

Update Magic​

You can update with the self-update command:

magic self-update

Uninstall Magic​

To remove Magic, just delete the binary:

rm ~/.modular/bin/magic

Create a Python project for MAX​

You can create a Python project with its own virtual environment using magic init. Here's how to create a new project and add the MAX Python API:

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

    magic init my-project

    This creates a my-project directory and a pixi.toml file that defines the project dependencies and more.

    caution

    magic also supports pyproject.toml files created with magic init --format pyproject but it currently fails when you run magic shell. We suggest you instead use pixi.toml as shown above for now.

  2. Enter the project and use magic run to execute code inside the environment:

    cd my-project
    magic run python3 --version

    Or, activate the environment shell with magic shell:

    magic shell
    python3 --version

    Then use exit to deactivate the shell:

    exit

  3. To change the Python version, you can also use magic add using the Python version operators. For example, you can set the Python version to 3.9 like this:

    magic add "python==3.9"

    The next time you run any Magic command, it will update the Python version in the environment:

    magic run python3 --version
    Python 3.9.0

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

    magic add max "numpy<2.0"

    By default, Magic first looks for packages in conda-forge repositories. If you prefer to use PyPI for a given package, add the --pypi flag. For example:

    magic add --pypi "numpy<2.0"

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

Create a Mojo project​

A Mojo project can be defined with either a pixi.toml or a mojoproject.toml file. Although both config files support Mojo and Python, the mojoproject.toml config file adds additional support for Mojo tools.

  1. Create a Mojo project with magic init:

    magic init my-mojo-project --format mojoproject

    This creates the my-mojo-project directory (if it doesn't already exist) and creates a mojoproject.toml file inside, which defines the project dependencies and more.

    If you already have a project where you want to put the mojoproject.toml, then specify the path name to that project. If you omit the path name, Magic creates the TOML file in the current directory.

    note

    mojoproject.toml is conceptually similar to pyproject.toml but it is still evolving.

  2. Enter the project and use magic run to execute code inside the environment:

    cd my-mojo-project
    magic run mojo --version

    Or, activate the environment shell with magic shell:

    magic shell
    mojo --version

    Then use exit to deactivate the shell:

    exit

  3. If you want to import Python modules in your Mojo code, specify the Python version and Python packages with magic add. For example:

    magic add "python==3.9" "numpy<2.0"

    This installs the packages and adds them to the project config:

    cat mojoproject.toml
    [project]
    name = "my-mojo-project"
    version = "0.1.0"
    description = "Add a short description here"
    channels = ["conda-forge", "https://conda.modular.com/max"]
    platforms = ["linux-64"]

    [tasks]

    [dependencies]
    max = ">=24.4,<24.5"
    python = "==3.9"
    numpy = "<2.0"

    Transient dependencies (the dependencies of your dependencies) are not specified in this TOML file, but they are specified in the magic.lock file.

    note

    By default, Magic sets the max version to the latest version—yours might be different than the one shown above. Also see how to update.

Update MAX and Mojo​

To update your max package (which includes Mojo), use the magic update command within your project path (every project has its own package versions):

magic update max

Or, you can change the max version by running magic add with a new version specifier. For example:

magic add "max~=24.4"

For more information, read about Pixi dependency tables.

Migrate a conda project to Magic​

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

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.

More documentation​

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

magic -h

Or see all the Magic commands here.

And because Magic is built upon pixi, you can also learn more from the pixi documentation. Just replace any pixi command with magic and you'll usually do fine.

caution

There are several differences between magic and pixi. For example, magic does not support exec, auth, and upload commands—and probably others to come.

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.

  • The Replit pipeline currently doesn’t work with the max-conda package.

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

Next steps​

Get started with MAX

Run a PyTorch model on MAX Engine and run Llama 3 built entirely in Mojo.

Get started with Mojo

Get started in Mojo by writing "Hello world" using the Mojo REPL and compiler.

Was this page helpful?