Pixi basics

Pixi is a CLI tool from Prefix.dev that we recommend you use to manage your package dependencies and virtual environments when developing with the Modular Platform and Mojo language.

We like Pixi so much, we created a fork called Magic, but Magic is now deprecated because Pixi can do everything we need. So we created this page to help you get started with Pixi. For more details, see the official Pixi docs.

All our GitHub code examples include a pixi.toml file. This file configures the environment to make sure we all use the same packages and get the same results—you just need to install pixi.

Install Pixi

You can install Pixi with this command:

curl -fsSL https://pixi.sh/install.sh | bash

Then enable auto-completion:

bash

eval "$(pixi completion --shell bash)"

zsh

autoload -Uz compinit && compinit  # redundant with Oh My Zsh
eval "$(pixi completion --shell zsh)"

fish

pixi completion --shell fish | source

If you're using a different terminal, see more options in the Pixi docs.

You can also update pixi with this command:

pixi self-update

For version information, see the Pixi changelog.

Create a project and virtual environment

You can create a project with its own packages and virtual environment using pixi init.

Normally, you must use the --channel argument to specify where to get packages. Instead, we recommend you set default channels in your user config file ($HOME/.pixi/config.toml).

For example, here's how to add the Modular and conda-forge channels as defaults:

echo 'default-channels = ["https://conda.modular.com/max-nightly", "conda-forge"]' \
  >> $HOME/.pixi/config.toml

Now those channels are always included in your pixi.toml when you create a project:

pixi init example-project

Then, enter the project directory to install mojo (or modular, which also installs mojo):

cd example-project

pixi add mojo

Check the installed version:

pixi run mojo --version

Manage packages

Every Pixi project defines its own package dependencies in the local pixi.toml file. When you run pixi add from the project directory, it adds that package name to your pixi.toml dependencies.

You can optionally specify the version with a version specifier:

pixi add "mojo~=0.25.6" "numpy<2.0"

If you always want the latest version, you can use the wildcard specifier:

pixi add "mojo=*"

To update a package, use pixi update:

pixi update mojo

This updates the package if there's a new version that adheres to the version you defined (via pixi add and as shown in the pixi.toml file).

To remove a package, use pixi remove:

pixi remove mojo

For more about defining dependencies, read about Pixi dependency tables.

Specify the Python version

Even the Python version is controlled like a package with a version specifier:

pixi add "python==3.11"

pixi run python --version

Python 3.11.0

Execute code in the environment

When your working directory is in a Pixi project (a directory with a pixi.toml file), you can run any command inside the environment using pixi run:

pixi run mojo --version

Or, you can open a shell in the environment to run your commands:

pixi shell

mojo --version

Be sure to exit the shell when you're done:

exit

Clean up environments

You can remove Pixi environments using pixi clean:

pixi clean

This removes everything in the Pixi environment, including cached data and built packages. This is particularly useful when iterating on graph builds, as it will clear the MEF cache from the graph compiler.

Caution

pixi clean removes more than just the MEF cache—it removes the entire Pixi environment. You'll need to reinstall packages after running this command.

The pixi.lock file

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

The transitive dependencies and the actually-installed versions are specified in the pixi.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.

More reading

There's a whole lot more you can do with Pixi, such as create multi-step tasks, install global tools, define multiple environments, and more.

For more information, see official Pixi docs and pixi CLI reference, or print the help:

pixi -h

Was this page helpful?

Thank you! We'll create more content like this.

Thank you for helping us improve!

😔 What went wrong?

Some code doesn’t work

It includes inaccurate information

It's missing information I need

It was difficult to understand

Other

Submit