Skip to main content

PIXI

Pixi Intro and Conda Migration Guide

What is Pixi?

Pixi is a modern environment and package manager for scientific Python, data science, geospatial work, machine learning, command-line tools, and other reproducible software stacks.

Pixi uses the Conda ecosystem, especially conda-forge, but avoids many of the problems users commonly hit with traditional Conda environments:

  • slow dependency solving

  • large memory use during conda install

  • fragile base environments

  • hard-to-reproduce environments

  • confusion caused by installing everything into one shared environment

Pixi is project-based. Instead of manually activating a random environment and installing packages into it, you create a project directory with a pixi.toml file. That file records the dependencies needed for that project.

A Pixi project usually contains:

my-project/
├── pixi.toml
├── pixi.lock
├── .pixi/
└── your files...

The important files are:

File Purpose
pixi.toml Human-readable list of dependencies, channels, platforms, and tasks
pixi.lock Exact solved package versions for reproducibility
.pixi/ The actual installed environment; this should not be committed to Git

Why use Pixi?

Pixi is a better default for user-managed software environments on shared systems and clusters.

It helps avoid common problems such as:

conda install -y -c conda-forge geopandas

Large packages like geopandas, gdal, rasterio, tensorflow, pytorch, and other scientific stacks may cause Conda to use a lot of memory while solving dependencies. On login nodes or memory-limited SSH sessions, that process may be killed.

Pixi is usually a better workflow because:

  • environments are tied to project directories

  • dependency solving is faster and more predictable

  • lock files make environments reproducible

  • users avoid polluting Conda base

  • it works well with conda-forge

  • it can install many command-line tools

  • it supports PyPI packages when needed

  • it works well in Slurm jobs and scripts

Installing Pixi

Run:

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

Then restart your shell, or log out and back in.

Check that Pixi works:

pixi --version

If pixi is not found after installation, check that Pixi’s binary directory is in your PATH.

Basic Pixi workflow

Create a new project:

mkdir my-project
cd my-project
pixi init

Add Python:

pixi add python=3.11

Add packages:

pixi add numpy pandas matplotlib

Run Python inside the environment:

pixi run python

Run a script:

pixi run python script.py

Start an interactive shell inside the environment:

pixi shell

Leave the Pixi shell:

exit

Replacing Conda with Pixi

Do not install project packages into Conda base

Avoid:

conda install -y -c conda-forge geopandas

Especially avoid installing large packages into base.

Use a Pixi project instead:

mkdir geopandas-project
cd geopandas-project
pixi init
pixi add python=3.11 geopandas

Run your code with:

pixi run python

or:

pixi run python analysis.py

Conda to Pixi command mapping

Conda / Mamba Pixi
conda create -n myenv python=3.11 mkdir my-project && cd my-project && pixi init && pixi add python=3.11
conda activate myenv pixi shell
conda install numpy pandas pixi add numpy pandas
conda install -c conda-forge geopandas pixi add geopandas
python script.py inside activated env pixi run python script.py
conda env export > environment.yml Use pixi.toml and pixi.lock
conda env create -f environment.yml pixi install
conda remove package pixi remove package
conda list pixi list

Migrating an existing Conda environment

Recommended method: start clean

This is usually the best approach.

Many Conda environments contain old packages, temporary packages, and dependencies that were installed during troubleshooting. Rather than migrating all of that history, create a clean Pixi project with only the packages you actually need.

Old Conda workflow:

conda create -n maps -c conda-forge python=3.11 geopandas matplotlib jupyterlab
conda activate maps

New Pixi workflow:

mkdir maps
cd maps
pixi init
pixi add python=3.11 geopandas matplotlib jupyterlab ipykernel

Run commands with:

pixi run python
pixi run jupyter lab

Import an existing environment.yml

If you already have an environment.yml, Pixi can import it.

First export your Conda environment:

conda activate myenv
conda env export --from-history > environment.yml

Using --from-history is important. It exports the packages you explicitly requested, not every low-level dependency that Conda solved.

Then create a Pixi project from it:

mkdir my-project
cd my-project
cp /path/to/environment.yml .
pixi init --import environment.yml

Then install and test:

pixi install
pixi run python

Replacing apt install with Pixi for user software

Pixi does not replace the operating system package manager for machine-level software.

However, Pixi can replace many cases where users would normally ask for:

sudo apt install some-tool

or where users would install software manually into their home directory.

On a shared system or cluster, users usually do not have sudo. Pixi gives users a safe way to install many tools and libraries into their own project environment without changing the system.

The short version

Use Pixi when the software belongs to your project.

Use apt when the software belongs to the machine.

Need Use
Python packages for a project Pixi
R packages for a project Pixi
GeoPandas, GDAL, PROJ, GEOS Pixi
ffmpeg for a project Pixi
jq, ripgrep, fd, imagemagick Pixi
compilers or build tools for one project Pixi
JupyterLab for one project Pixi
System SSH server Admin-managed apt
NVIDIA drivers Admin-managed apt
Slurm client/system config Admin-managed apt
SSSD, PAM, Kerberos login Admin-managed apt
NFS, autofs, FUSE setup Admin-managed apt
System services or daemons Admin-managed apt

User-facing rule

If you were going to install a tool with apt just so your project can use it, try Pixi first.

For example, instead of asking for:

sudo apt install jq

use:

mkdir my-project
cd my-project
pixi init
pixi add jq
pixi run jq --version

Instead of asking for:

sudo apt install ffmpeg

use:

mkdir video-project
cd video-project
pixi init
pixi add ffmpeg
pixi run ffmpeg -version

Instead of asking for:

sudo apt install gdal-bin

use:

mkdir gis-project
cd gis-project
pixi init
pixi add gdal
pixi run gdalinfo --version

Common apt to Pixi examples

Instead of asking for... Try this
sudo apt install jq pixi add jq
sudo apt install ripgrep pixi add ripgrep
sudo apt install ffmpeg pixi add ffmpeg
sudo apt install imagemagick pixi add imagemagick
sudo apt install gdal-bin pixi add gdal
sudo apt install cmake pixi add cmake
sudo apt install ninja-build pixi add ninja
sudo apt install pkg-config pixi add pkg-config
sudo apt install nodejs pixi add nodejs
sudo apt install rustc cargo pixi add rust
sudo apt install r-base pixi add r-base

Run installed tools with:

pixi run tool-name

For example:

pixi run jq --version
pixi run ffmpeg -version
pixi run gdalinfo --version

Or enter the Pixi shell:

pixi shell

Then run the tool normally:

jq --version
ffmpeg -version
gdalinfo --version

Example: replacing apt install gdal-bin

Old local-machine workflow:

sudo apt install gdal-bin python3-geopandas

Pixi workflow:

mkdir gis-project
cd gis-project
pixi init
pixi add python=3.11 geopandas gdal

Test it:

pixi run python -c "import geopandas as gpd; print(gpd.__version__)"
pixi run gdalinfo --version

This installs the GIS stack inside the project environment instead of relying on system packages.

Example: replacing apt install ffmpeg

Old local-machine workflow:

sudo apt install ffmpeg

Pixi workflow:

mkdir video-tools
cd video-tools
pixi init
pixi add ffmpeg

Run:

pixi run ffmpeg -version

Use it in a script:

pixi run ffmpeg -i input.mp4 output.webm

Example: replacing apt install jq ripgrep

Old local-machine workflow:

sudo apt install jq ripgrep

Pixi workflow:

mkdir text-tools
cd text-tools
pixi init
pixi add jq ripgrep

Run:

pixi run jq --version
pixi run rg --version

Example: replacing apt install cmake ninja-build

Old local-machine workflow:

sudo apt install cmake ninja-build pkg-config

Pixi workflow:

mkdir build-project
cd build-project
pixi init
pixi add cmake ninja pkg-config compilers

Build inside the Pixi environment:

pixi run cmake -S . -B build
pixi run cmake --build build

When Pixi is the right replacement for apt

Pixi is a good replacement when:

  • you need a command-line tool for one project

  • you need a newer version than the system provides

  • you need reproducible versions

  • you do not have sudo

  • you want other users to recreate the same environment

  • the software does not need to run as a system service

  • the software does not need to modify /etc

  • the software does not need kernel modules or drivers

Good examples:

pixi add jq
pixi add ripgrep
pixi add ffmpeg
pixi add gdal
pixi add imagemagick
pixi add cmake ninja pkg-config
pixi add nodejs
pixi add rust
pixi add r-base

When Pixi is not a replacement for apt

Pixi should not be used for machine-level system software.

Ask an administrator for help if the software involves:

  • kernel modules

  • GPU drivers

  • system daemons

  • login services

  • PAM

  • SSSD

  • Kerberos login

  • SSH server configuration

  • Slurm system configuration

  • NFS or autofs

  • FUSE configuration

  • systemd services

  • software that modifies /etc

  • software that must be available globally to every user

  • software that needs privileged installation

Examples that should remain admin-managed:

sudo apt install openssh-server
sudo apt install sssd
sudo apt install krb5-user
sudo apt install nfs-common
sudo apt install slurm-client
sudo apt install nvidia-driver-XXX

Important warning: avoid mixing Pixi and system libraries

Avoid mixing random system libraries with Pixi libraries unless you know what you are doing.

This matters especially for compiled software stacks such as:

  • GDAL

  • GEOS

  • PROJ

  • HDF5

  • NetCDF

  • MPI

  • CUDA-related tools

  • scientific Python packages with compiled dependencies

Prefer one of these approaches:

  1. Install the full stack in Pixi.

  2. Use the full system/admin-provided stack.

  3. Use a cluster module, if one is provided.

Avoid half-Pixi, half-system environments unless there is a specific reason.

Adding Jupyter support

For notebook use:

pixi add jupyterlab ipykernel

Start JupyterLab:

pixi run jupyter lab

To register the environment as a Jupyter kernel:

pixi run python -m ipykernel install --user --name my-project --display-name "Python my-project"

Replace my-project with a meaningful name.

Adding tasks

Pixi can store common commands as tasks.

For example:

pixi task add start "python script.py"

Then run:

pixi run start

You can also add a Jupyter task:

pixi task add lab "jupyter lab"

Then run:

pixi run lab

Tasks make projects easier to share because users do not need to remember long commands.

Using PyPI packages with Pixi

Use Conda packages from conda-forge when possible, especially for packages with compiled dependencies.

For pure Python packages that are only available from PyPI, use Pixi’s PyPI support:

pixi add --pypi some-python-package

General rule:

  • prefer pixi add package-name first

  • use pixi add --pypi package-name only when the package is not available from Conda/conda-forge or when you specifically need the PyPI version

For geospatial, numerical, and compiled packages, prefer Conda/conda-forge packages.

Using Pixi with Slurm

Pixi works well in Slurm jobs because you can run commands directly inside the project environment.

Example Slurm script:

#!/bin/bash
#SBATCH --job-name=geopandas-test
#SBATCH --partition=grit_nodes
#SBATCH --time=01:00:00
#SBATCH --mem=8G
#SBATCH --cpus-per-task=2
#SBATCH --output=slurm-%j.out

cd ~/projects/geopandas-example

pixi run python analysis.py

For interactive setup work:

salloc -p grit_nodes --mem=16G --cpus-per-task=4 --time=01:00:00

Then:

cd ~/projects/geopandas-example
pixi install
pixi run python

Building or solving large environments on a login node may be discouraged. If an environment is large, use an interactive Slurm allocation.

Using Pixi with GeoPandas

GeoPandas is a good example of why Pixi is useful.

The geospatial Python stack often includes compiled libraries such as:

  • GDAL

  • GEOS

  • PROJ

  • Fiona

  • Shapely

  • Pyogrio

  • Rtree

Installing these from random combinations of pip, conda, and system packages can be painful.

mkdir geopandas-project
cd geopandas-project
pixi init
pixi add python=3.11 geopandas matplotlib jupyterlab ipykernel

Test:

pixi run python -c "import geopandas as gpd; print(gpd.__version__)"

Start JupyterLab:

pixi run jupyter lab

Common examples

Python data science

mkdir data-project
cd data-project
pixi init
pixi add python=3.11 numpy pandas matplotlib scipy scikit-learn jupyterlab ipykernel

Run:

pixi run jupyter lab

GeoPandas

mkdir geopandas-project
cd geopandas-project
pixi init
pixi add python=3.11 geopandas matplotlib jupyterlab ipykernel

Run:

pixi run python -c "import geopandas as gpd; print(gpd.__version__)"

R environment

mkdir r-project
cd r-project
pixi init
pixi add r-base r-essentials

Run:

pixi run R

Mixed Python and command-line tools

mkdir cli-project
cd cli-project
pixi init
pixi add python=3.11 pandas ripgrep jq

Run:

pixi run python script.py
pixi run rg "search text" .
pixi run jq . file.json

Troubleshooting

pixi: command not found

Log out and back in.

If it still fails, check your PATH:

echo "$PATH"

Environment install is slow

The first install may take time because Pixi has to solve and download packages.

After that, pixi run should reuse the environment.

I changed pixi.toml; how do I update the environment?

Run:

pixi install

How do I remove a package?

pixi remove package-name

How do I see installed packages?

pixi list

Should I still use conda activate?

Usually, no.

Use:

pixi run command

or:

pixi shell

Should I delete Conda?

No. You do not need to delete Conda immediately.

  1. Stop installing new packages into Conda base.

  2. Create new projects with Pixi.

  3. Migrate old Conda environments only when you need to use them.

  4. Keep Conda around temporarily for old workflows.

  5. Remove old Conda environments after the Pixi version works.

Practical migration checklist

For each old Conda environment:

  1. Identify what the environment is used for.

    conda env list

  2. Activate it.

    conda activate old-env

  3. Export only the explicitly requested packages.

    conda env export --from-history > environment.yml

  4. Create a Pixi project.

    mkdir old-env-pixi
cd old-env-pixi
pixi init --import ../environment.yml

  5. Install and test.

    pixi install
pixi run python

  6. Run your actual script or notebook.

    pixi run python analysis.py

  7. Commit the Pixi files.

    git add pixi.toml pixi.lock
git commit -m "Add Pixi environment"

  8. Stop using the old Conda environment once the Pixi project works.

Use Pixi for new projects.

Do not install large packages into Conda base.

Do not ask for apt packages if the software only needs to exist inside your project. Try Pixi first.

For GeoPandas, use:

mkdir geopandas-project
cd geopandas-project
pixi init
pixi add python=3.11 geopandas jupyterlab ipykernel
pixi run python -c "import geopandas as gpd; print(gpd.__version__)"

For command-line tools, use:

mkdir tools-project
cd tools-project
pixi init
pixi add jq ripgrep ffmpeg
pixi run jq --version
pixi run rg --version
pixi run ffmpeg -version

For existing Conda environments, export with:

conda env export --from-history > environment.yml

Then import into Pixi:

pixi init --import environment.yml
pixi install
Back to top