> For the complete documentation index, see [llms.txt](https://docs.modular.com/llms.txt).
> Markdown versions of all pages are available by appending .md to any URL (e.g. /max/get-started.md).

# Pixi basics

Pixi is a CLI tool [from Prefix.dev](https://prefix.dev/blog/launching_pixi)
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](https://forum.modular.com/t/migrating-from-magic-to-pixi/1530)
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](https://pixi.sh/latest/).

:::note

All our [GitHub code
examples](https://github.com/modular/modular/tree/main/max/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:

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

Then enable auto-completion:

**bash:**

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

---

**zsh:**

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

---

**fish:**

```sh
pixi completion --shell fish | source
```

If you're using a different terminal, see more options in [the Pixi
docs](https://pixi.sh/latest/installation/#autocompletion).

You can also update `pixi` with this command:

```sh
pixi self-update
```

For version information, see the [Pixi
changelog](https://pixi.sh/latest/CHANGELOG/).

:::caution
If you've used a package manager like brew, mamba, conda, paru etc. to
install pixi you must use the built-in update mechanism. For example:

```sh
brew upgrade pixi
```

:::

## Create a project and virtual environment

You can create a project with its own packages and virtual environment using
[`pixi init`](https://pixi.sh/latest/reference/cli/pixi/init/).

Normally, you must use the
[`--channel`](https://pixi.sh/latest/reference/cli/pixi/init/#arg---channel)
argument to specify where to get packages. Instead, we recommend you set
default channels in your [user config
file](https://pixi.sh/dev/reference/pixi_configuration/)
(`$HOME/.pixi/config.toml`).

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

```sh
mkdir -p $HOME/.pixi
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:

```sh
pixi init example-project
```

Then, enter the project directory to install `mojo`
(or [`modular`](https://docs.modular.com/max/packages.md#whats-included), which also installs `mojo`):

```sh
cd example-project
```

```sh
pixi add mojo
```

Check the installed version:

```sh
pixi run mojo --version
```

## Manage packages

Every Pixi project defines its own package dependencies in the local
[`pixi.toml`](https://pixi.sh/latest/reference/pixi_manifest/) file. When you
run [`pixi add`](https://pixi.sh/latest/reference/cli/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](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5):

```sh
pixi add "mojo~=0.26.1" "numpy<2.0"
```

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

```sh
pixi add "mojo=*"
```

To update a package, use [`pixi
update`](https://pixi.sh/latest/reference/cli/pixi/update/):

```sh
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`](https://pixi.sh/latest/reference/cli/pixi/remove/):

```sh
pixi remove mojo
```

For more about defining dependencies, read about
[Pixi dependency tables](https://pixi.sh/latest/reference/project_configuration/#the-dependencies-tables).

### Specify the Python version

Even the Python version is controlled like a package with a
[version specifier](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5):

```sh
pixi add "python==3.11"
```

```sh
pixi run python --version
```

```output
Python 3.11.0
```

## Execute code in the environment

When your working directory is in a Pixi project (a directory with a
[`pixi.toml`](https://pixi.sh/latest/reference/pixi_manifest/) file), you can
run any command inside the environment using [`pixi
run`](https://pixi.sh/latest/reference/cli/pixi/run/):

```sh
pixi run mojo --version
```

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

```sh
pixi shell
```

```sh
mojo --version
```

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

```sh
exit
```

## Clean up environments

You can remove Pixi environments using [`pixi
clean`](https://pixi.sh/dev/workspace/environment/#cleaning-up):

```sh
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`](https://pixi.sh/latest/reference/pixi_manifest/)) 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](https://packaging.python.org/en/latest/specifications/version-specifiers/#id5)
as less-than `<` or greater-than `>`).

The transitive dependencies and the actually-installed versions are specified
in the [`pixi.lock`](https://pixi.sh/latest/workspace/lockfile/) 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](https://pixi.sh/latest/features/lockfile/).

## More reading

There's a whole lot more you can do with Pixi, such as create multi-step
[tasks](https://pixi.sh/latest/workspace/advanced_tasks/), install [global
tools](https://pixi.sh/latest/global_tools/introduction/), define [multiple
environments](https://pixi.sh/latest/workspace/multi_environment/), and more.

For more information, see [official Pixi docs](https://pixi.sh/latest/) and
[pixi CLI reference](https://pixi.sh/latest/reference/cli/pixi/), or print
the help:

```sh
pixi -h
```