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:
- 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 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:
-
Create a Python project with the
magic init
command:magic init my-project
magic init my-project
This creates a
my-project
directory and apixi.toml
file that defines the project dependencies and more. (If you omit the directory name, it creates thepixi.toml
file in the current directory.) -
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"
-
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.
-
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.
-
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 amojoproject.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
includesmax
as a dependency becausemax
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
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.
-
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 a package appears unavailable from conda via magic add
, you might need to
add a new conda channel. For example, PyTorch is not available in
conda-forge
, so you must 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 aconda
orvenv
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 usingmagic
, but you might see some issues so we advise you only usemagic
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.
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!
๐ What went wrong?