Using the pixi package manager

This document provides a quick overview of using pixi. For more detailed information, please check the official documentation.

Installation

On Mac OS X or Linux, you can install pixi with the following shell command:

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

On Windows, you can use this PowerShell command instead:

powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex"

These commands will download pixi, install it on your system and add it to the path. You can test the installation with

pixi --version

Configure pixi to use the official mirrors

Let's configure pixi to use the official conda-forge and bioconda channels. (Other channels are hosted by Anaconda and require a license if you are working in a commercial setting.)

Place paste the following text into the ~/.pixi/config.toml file. (This file might not exist, yet, so please create it if necessary - see below for instructions.)

default-channels = ["conda-forge", "bioconda"]

[mirrors]
"https://conda.anaconda.org/conda-forge" = [
    "https://prefix.dev/conda-forge"
]

"https://conda.anaconda.org/bioconda" = [
    "https://prefix.dev/bioconda"
]

For example, you can create & open the ~/.pixi/config.toml file with the following command in the terminal of your Mac:

Open the file using the nano editor:

nano ~/.pixi/config.toml
Paste the entire content of the box shown above (with the default-channels and [mirrors] sections) into the editor.
Save and close the file by pressing: Ctrl + x followed by Y (to confirm).
Verify that pixi is using the mirrors with the following command: pixi config list

(This command should return the same information you pasted into the config file.)

Removing pixi from your system

To remove pixi from your system, simply delete the installed file:

On Mac OS X or Linux:

rm ~/.pixi/bin/pixi

On Windows

$PIXI_BIN = "$Env:LocalAppData\pixi\bin\pixi"; Remove-Item -Path $PIXI_BIN

Usage

To see pixi's sub-commands, simply execute it in your shell:

pixi

We won't cover all of the available sub-command here (as the documentation is excellent). Instead, we will focus on the most frequently used steps:

Creating a new project

pixi installs dependencies within your project folder. To create a new project, use pixi init.

To see the options of this sub-command:

pixi init --help

For example, to create a new project that accesses the conda-forge and bioconda channels:

pixi init -c bioconda -c conda-forge my_project

This command will create the my_project directory, and within it the pixi.toml configuration file. It has recorded e.g. my username and the platform I am working on..

Because I haven't specified / installed any dependencies, yet, the [dependencies] section is empty.

cat my_project/pixi.toml

[project]
name = "my_project"
version = "0.1.0"
description = "Add a short description here"
authors = ["Thomas Sandmann"]
channels = ["bioconda", "conda-forge"]
platforms = ["osx-arm64"]

[tasks]

[dependencies]

To install dependencies / tools into my project:

Let's install e.g. the samtools suite that is available from bioconda.

cd my_project
pixi add samtools  # samtools is a bioinformatics tool hosted on bioconda

This command downloads and installs samtools and all its dependencies. It also tracks the exact version of the newly installed tools in a new pixi.lock file within the project folder.

Activating a project

To actually use the tools installed in our project, we need one more command pixi shell. (This command is similar to conda activate or source myvenv/bin/activate used by other package managers.)

pixi shell

This will place the tools that are installed in this project into the PATH.

which samtools
/Users/sandmann/my_project/.pixi/envs/default/bin/samtools

and samtools is now ready for use!

Deactivating a project

The pixi shell command actually starts a new shell, so we can exist it using the usual exit command.

Installing tools globally

Sometimes, we don't want tools to be installed specifically for a specific project, but would like to make them available anywhere on the system. pixi can help with that,too!

The pixi global command and its sub-commands install tools globally on your system, similar e.g. to manually installing a tool on Mac OS X or Windows.

pixi global --help

For example, the following command will install the btop tool (a tool to monitor your system):

pixi global install btop
which btop  # /Users/sandmann/.pixi/bin/btop

We can remove the tool with the pixi global remove sub-command:

pixi global remove btop
which btop  # not found

tomsing1/using_pixi.md