Why Magic?

Last month marked the release of Magic, a new virtual environment and package manager that replaces the Modular CLI, our legacy command line installer for Mojo and MAX. Magic is a major step forward in improving the Modular installation and development experience, but we recognize that you may be asking, “Another package management solution? Why?”

Our intention with Magic isn’t to create a superfluous command line tool or to unnecessarily splinter package management — in fact, our goal is the opposite: simplification. While using it is optional, Magic provides one tool to enable developers to:

• Work across multiple languages: Mojo, Python, C, and more.
• Work with packages from multiple ecosystems (PyPI and Conda).
• Manage both packages and virtual environments.

This blog post dives into the most frequently asked questions around Magic, with the aim of clarifying why we recommend using Magic to build Mojo and MAX projects.

If you have any questions that aren’t covered by this post, please share them in the #magic-cli channel in Discord. If you encounter any issues while working with Magic, please open an issue on Github.

What is Magic?

Magic is a package and virtual environment manager for any language, including Python and Mojo. Because it's built on the same open standards that power the Conda and PyPI packing ecosystems, it provides access to thousands of packages for Python and other languages. Additionally, Magic adds functionality that makes working with MAX and Mojo more productive — keep reading to learn more.

What problems does Magic solve?

Magic allows you to instantly launch projects shared with you and create new projects that are fully contained and reproducible across development environments. Package dependencies and environment settings are managed for you by Magic, allowing you to easily switch between different versions of MAX, Mojo, Python, and other dependencies.

Why did you replace the Modular CLI?

Our former installer, the Modular CLI, installed MAX and Mojo globally. For some users, this was not an issue, but for many, it created dependency management challenges, especially when using MAX and Mojo with Python. Using the Modular CLI alongside a separate dependency management tool was not a great developer experience, so we set out to deliver a new solution that better meets developer needs by building on top of open packaging standards.

How is Magic different from existing package and environment managers?

Magic uses the open packaging standards defined by the Conda community, and is built on top of the open source Pixi package manager. While you can leverage existing Python tools like Conda (more on that later), Magic adds functionality designed to help you get started more quickly with Modular’s development stack. For example, Magic adds a Mojo-specific project format, and is aware of the default channel configurations for MAX.

Plus, the future of Magic is bright. We’re working on new features for Magic — beyond package & environment management — that will help you to share projects and put models into production faster.

Why should I use virtual environments?

Virtual environments provide isolated project-specific setups, helping avoid version conflicts by keeping dependencies separate. This ensures consistency across different systems, which is especially helpful in collaborative work where everyone needs the same environment. By keeping project dependencies contained, virtual environments prevent unnecessary clutter in the global environment, preserving system stability and organization. Additionally, they allow you to run different versions of Python, MAX, or Mojo for each project, making it easy to test new configurations without risk to other projects.

How do I use Magic to install MAX and run an example project?

Get started using Magic by following the Getting Started tutorial, or install it now from your command line with one simple command:

Run magic --help for usage information and commands.

Once you have Magic installed, you can download a CPU-optimized Llama3 example by cloning the MAX repository from GitHub, and running it with just three commands:

From here, you can easily modify the example code to build your own Python app with MAX and Llama3.

How do I use Magic to create a virtual environment?

You can create a project with its own package dependencies and virtual environment using the command magic init <project_name> --format pyproject, where <project_name> is the name to give your new project. To work with the Mojo language, change pyproject to mojoproject.

Learn more about creating Magic projects.

How can I migrate a Mojo project to Magic?

First, you’ll want to navigate to the folder where your project is located, then initialize it as a Mojo project like so:

This will create a virtual environment for your project, and a mojoproject.toml file for configuring it.  

To build and run your Mojo code, you have a few options:

1. Use the command magic shell to activate an interactive virtual environment, providing you direct access to the Mojo CLI to which you’re accustomed. Use the exit command or press CTRL+D to exit the shell.
2. Use commands like magic run mojo main.mojo  to run a single command without entering a Magic shell. Learn more about Magic CLI commands.
3. Add tasks to your project’s mojoproject.toml file for commands you use often. Learn about tasks and more in our tutorial.

How can I migrate a Conda project to Magic?

If you have an existing Conda project, you can export an evironment.yml configuration file and import it with Magic. The following commands will create a new Magic project from the dependencies in a Conda environment:

Breaking it down, these commands do the following:

1. Navigate into the project directory.
2. Activate the Conda environment.
3. Export the Conda environment's dependencies into an environment.yml file.
4. Deactivate the Conda environment.
5. Initialize a Magic project based on the environment.yml file.

Can I use MAX and Mojo without Magic?

Yes, MAX and Mojo are available today through Conda. Adding MAX and Mojo to a Conda project is straightforward:

Breaking it down, these commands do the following:

1. Navigate to the location of a Conda project.
2. Activate the a Conda environment.
3. Add the MAX and conda-forge Conda channels (MAX requires the conda-forge community channel).
4. Install MAX and Mojo into the Conda environment.

Learn more about using MAX and Mojo with Conda

What’s next?

Magic opens up new possibilities for developing and sharing applications. It’s built on the Conda packaging ecosystem, and makes it possible for you to share your projects with others. We’re also adding new features into Magic that are designed to help make your journey with Modular more productive. We’re excited about what’s coming next.

If you have any questions that aren’t covered by this post, please share them in the #magic-cli channel in Discord. If you encounter any issues while working with Magic, please open an issue on Github.

Until next time! 🔥