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
curl -fsSL https://pixi.sh/install.sh | bash
Then enable auto-completion:
- bash
- zsh
- fish
eval "$(pixi completion --shell bash)"
eval "$(pixi completion --shell bash)"
autoload -Uz compinit && compinit # redundant with Oh My Zsh
eval "$(pixi completion --shell zsh)"
autoload -Uz compinit && compinit # redundant with Oh My Zsh
eval "$(pixi completion --shell zsh)"
pixi completion --shell fish | source
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
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 specify the Conda channels from which to get packages, using
the
--channel
argument. Instead, we recommend you specify default channels in your user
config file
($HOME/.pixi/config.toml).
For example, use this command to add the Modular and conda-forge channels:
echo 'default-channels = ["https://conda.modular.com/max-nightly", "conda-forge"]' >> $HOME/.pixi/config.toml
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 new project:
pixi init example-project
pixi init example-project
Then, enter the project directory to install modular:
cd example-project
cd example-project
pixi add modular
pixi add modular
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 "modular~=25.4" "numpy<2.0"
pixi add "modular~=25.4" "numpy<2.0"
If you always want the latest version, you can use the wildcard specifier:
pixi add "modular=*"
pixi add "modular=*"
To update a package, use pixi update:
pixi update modular
pixi update modular
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 modular
pixi remove modular
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 add "python==3.11"
pixi run python --version
pixi run python --version
Python 3.11.0
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
pixi run mojo --version
Or, you can open a shell in the environment to run your commands:
pixi shell
pixi shell
mojo --version
mojo --version
Be sure to exit the shell when you're done:
exit
exit
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
pixi -h
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!