Use the Pixi Environment

Last modified 2026-03-11

Use the Pixi Environment

At a Glance

	Abbreviations Key
`CMD`	command
DESeq2	differential expression sequencing 2 (R package)
HISE	Human Immune System Explorer
IDE	integrated development environment
ML	machine learning
PyPI	Python Package Index
SDK	software development kit
YAML	Yet Another Markup Language

This document introduces you to the Pixi environment, a reusable IDE setup that keeps all your project tools and libraries in one place. Pixi opens quickly and behaves the same way every time. If you save your environment, Cloud Build uses a saved Pixi configuration (including files like pixi.toml and pixi.lock) to reconstruct that environment on demand. For details, see Save a Custom Pixi Environment (Tutorial).

When to Use This Feature

Use Pixi when you want to create a reusable IDE environment that's faster and more reliable than Conda-based environments. For details, see Save a Custom Pixi Environment (Tutorial) and Install a GitHub Package in a Pixi IDE Environment (Tutorial)

Start new projects quickly, without waiting dependency issues to resolve.
Share a standard analysis environment with your team so collaborators start from a consistent set of tools and libraries across IDEs.
Preserve environment state for important analyses so you can return to the same package versions for follow-up work or review.

Pixi Basics

Pixi is both an environment and a package manager. It determines which tools you use and manages how they’re installed. The pixi.toml file defines the environment, including its packages and settings. In HISE, you work inside an IDE created from a Pixi environment. Pixi is already initialized and ready to use when you open the IDE.

Pixi Packs

When you use a saved Pixi pack (Pixi environment) to create a new IDE, Cloud Build reconstructs the environment setup behind the scenes. The IDE management service sends the Pixi pack, including pixi.toml, pixi.lock, and any bundled Python wheel files, to Cloud Build, which adds a small set of required SDK packages to that manifest. Next, to install GitHub-hosted Python packages and any other task-specific dependencies, Cloud Build runs the tasks defined in pixi.toml.

Important Files
File	Description	Purpose
`pixi.toml`	Project configuration and environment definition file	Declares dependencies, tasks, and other settings for your Pixi environment
`pixi.lock`	Resolved dependency lock file	Records the exact versions of all packages in the environment so you can reconstruct the same setup later
`.pixi/`	Internal Pixi directory	Stores project environments and related metadata (for example `.pixi/envs/`) with the actual environment files

An IDE startup script unpacks the Pixi pack into your workspace, finds the environment YAML file needed for initialization, does minimal cleanup to match the IDE’s runtime environment, and then reconstructs the Pixi environment from that file. It sets environment variables and launches a Pixi shell so that the SDK and your tools can run inside the rebuilt environment.

In Python, any wheel files that the Pixi pack injected into the environment are unpacked into the workspace and installed automatically. In R, however, the tarballs you provided at build time are not reattached when the Pixi pack is unpacked. Unless you reinstall those R packages manually, the new IDE will not include them. For a list of required packages, see Save a Custom Pixi Environment (Tutorial)

IDE Workflow

To work with your Pixi IDE, you need just four simple commands: pixi add to install packages, pixi remove to uninstall them, pixi run to run your code or common tasks, and pixi shell to open a shell inside the environment. These and other commonly used commands are summarized in the following table.

Pixi Commands
Command	Example(s)	Description
General
`pixi add PACKAGE_NAME`	`pixi add numpy`	Install a package
`pixi remove PACKAGE_NAME`	`pixi remove seaborn`	Delete a package
`pixi run CMD`	`pixi run python pixi run pytest pixi run jupyter lab`	Run your code
`pixi list`	NA	Show installed packages
`pixi info [OPTIONS]`	`pixi info --json`	Show environment info
`pixi tree`	NA	Show dependency graph
`pixi clean [OPTIONS] [CMD]`	`pixi clean cache --yes`	Remove local data to reclaim space or reset environment
`pixi lock [OPTIONS]`	`pixi lock --check`	Regenerate or check the environment lockfile so collaborators can recreate the same set of packages in their IDEs
Common tasks
`pixi add PACKAGE_NAME`	`pixi add numpy`	Install a package
`pixi add PACKAGE_1 PACKAGE_2 PACKAGE_3`	`pixi add numpy pandas matplotlib`	Install multiple packages
`pixi add PACKAGE_NAME==VERSION`	`pixi add numpy==1.26.4`	Install a specific package version
`pixi add conda-forge::PACKAGE_NAME`	`pixi add conda-forge::scipy`	Install package from conda-forge explicitly
`pixi add wheel.whl`	`pixi add ./examples/pypi-wheel-packages/wheels/private-package-0.0.1-py3-none-any.whl`	Install the Python package contained in a local wheel file
Development mode
`pixi shell`	NA	Open a Pixi shell To activate a Pixi environment in a Conda IDE, you must use `pixi-shell`, not `pixi shell`
`pip install -e .`	Install the current project in editable (development) mode	Use the package as if it were installed, while reflecting code changes immediately without reinstalling
`exit`	NA	Close the Pixi shell
Python-specific commands
`pixi add requests fastapi torch`	NA	Serve an ML model over HTTP
`pixi run pip install pandas`	NA	Run `pip install pandas` inside the current Pixi environment to add the pandas package with `pip` instead of Pixi
R-specific commands
`pixi add r-ggplot2 r-dplyr r-data.table`	NA	Install common R packages for data manipulation and plotting
`pixi add bioconda::bioconductor-deseq2`	NA	Install the DESeq2 package from Bioconductor

Golden rules for working with Pixi

Never edit .pixi/ manually.
Avoid mixing Conda and pip randomly.
Take great care before deleting pixi.lock.
Never modify env with conda/mamba directly.
Don't use pip install outside of Pixi unless absolutely necessary.

Related Resources

Use HISE IDE Packages

Use HISE SDKs or Get Help in the IDE

Save a Custom Pixi Environment (Tutorial)

Install a GitHub Package in a Pixi Environment (Tutorial)