Save a Custom Pixi Environment (Tutorial)

Abbreviations Key

At a Glance

A Pixi environment is a directory that contains your curated set of packages plus a manifest used to resolve dependencies. Your custom Pixi environment can be saved and reused when you or your collaborators create new IDEs. The environment is also easy to export and trace for transparency and reproducibility. This tutorial explains how to use the SDK, Pixi, and Google Cloud Build to create a custom Pixi environment for your IDE. If you have questions or need help, contact Support. 

The new HISE environment-selection prompt now handles many scenarios that previously required the save_custom_pixi_environment() workaround. If you upload files while more than one Pixi environment is available, HISE prompts you to choose which environment to associate with your data, which reduces the need to save a custom environment just to keep files and results tied to the correct setup. Use save_custom_pixi_environment() when you need to formally save or share a custom environment for reuse in HISE.

When to Use This Feature

Use this feature when you want to create a reusable Pixi-based IDE environment that other users can select from the HISE UI:

• Capture a Pixi environment from an existing IDE so others can reproduce the same configuration.

• Share a standard analysis environment with your team so that collaborators start with 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.

• Maintain separate Pixi environments for different workflows (for example, quick exploration vs. publication-ready analysis).

Don't use this feature if your project still relies on a Conda-only environment. If you don't need to reuse or share your environment, use Conda tools or create a one-off Pixi setup instead.

Required Configuration

To avoid build errors when you save a custom Pixi environment, the R version must be 4.4.1 or higher, and the Python version must be between 3.10 and 3.13. Your pixi.toml must include both conda-forge and bioconda in channels. It must also include python or r-base in dependencies that match the languages you specify when you call save_custom_pixi_environment(). For example, languages=["python"] requires python in your dependencies list. Here's an example of a pixi.toml file:

[project]
name = "my-env"

[dependencies]
python = ">=3.10"
pandas = "*"

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

SDK Method

This SDK call saves a custom Pixi environment with additional metadata.

Signature

The box below shows the method signature for save_custom_pixi_environment() (Python) | saveCustomPixiEnvironment (R).

hp.save_custom_pixi_environment(
    env_name: str,
    description: str,
    languages: list[str],
)

hp.saveCustomPixiEnvironment(
    envName: str,
    description: str,
    languages: list[str],
)

Parameters

The parameters for this method are listed in the following table. In each key:value pair, the value must be of type list.

  Get Help

If you get stuck while creating your custom Pixi environment, refer to the steps of this tutorial (examples are in Python unless otherwise specified). To use the baked-in help in your IDE, try one of the following commands.

Still not working? File a Support ticket.

Instructions

 Configure a Pixi environment

1. Navigate to HISE, and use your organizational email address to sign in.

2. From the top navigation menu in HISE, click RESEARCH > Manage Evironment Packages.

3. On the Manage Environment Packages page, click CREATE ENVIRONMENT.

4. On the Select Package Manager page, toggle to the Pixi tab.

5. In the Create Pixi Environment dialog box, enter the requested details: 

A. In the Name field, enter a name for yor IDE (for example, "Single-cell RNA-seq – Pixi")

B. In the Description field, enter a brief description of the key packages or analysis tasks included in your custom environment and the languages you tested in this environment.

C. In the Language field, keep the default language, Python, or click the arrow and select R from the drop-down menu. If applicable, you can select both.

D. In the Privacy Settings field, keep the default PRIVATE, or click SHARED to share your IDE with all colleagues who have access to this project. To share your IDE with specified users, click SELECT USERS, and add add their email addresses to the Share with users field. 

E. To improve the discoverability of your shared IDE, enter one or more tags into the Tags field. Use the key:value format.

F. Click CHOOSE FILE, and upload a pixi.toml or pyproject.toml configuration file. 

G. Click SAVE CHANGES.

 Create a Pixi IDE 

1.  Refresh your screen, and click the card that represents the Pixi environment you created in Step 1.

A chip on the front of the card verifies that it's a Pixi environment.

2. On the Environment Details page, click CREATE IDE.

3. On the IDE Settings page, enter the requested information, and click CREATE. 

    (Optional) Install R packages

You can add R packages to your Pixi environment in one of two ways, depending on where the package lives.

1. For R packages hosted on GitHub, use the installGithubPackageToPixiEnv() SDK instead of relying on Pixi Packs. This SDK call is the supported way to install R GitHub packages into a Pixi environment. It replaces the oldj tarball‑based approach. For details and examples, see Install a Github Package in a Pixi IDE Environment (Tutorial) .

2. For R packages available from standard R repositories (for example, CRAN or Bioconductor), declare them directly in your pixi.toml so the solver picks them up when the environment is built. In the [dependencies] section, include entries such as r-lifecycle = “*”, which instructs Pixi to install the most recent version that doesn't conflict with other dependencies.
   
   After you edit pixi.toml, rebuild or refresh your Pixi environment from HISE. Then open an IDE that uses this environment and confirm that you can load the packages from R (for example, library(lifecycle)).

 Save your Pixi environment

When you're satisfied with your custom Pixi IDE environment, save a Pixi pack to capture it for future use. This tutorial assumes Cloud Build and the IDE management service are already configured to handle Pixi packs. At a high level, the Pixi pack environment save flow takes the pixi.toml and pixi.lock files from your active environment, injects any Python package files (wheels) from the environment’s PyPI directory, and sends these files to the IDE management service. This service stores them and configures Cloud Build tasks that install the packages when the IDE is created. Pixi pack supports only PyPI wheels, not source distributions, such as most R tarballs.

1. Open the Pixi-based IDE you created in Step 3,

2. To confirm that the IDE is using a Pixi environment, open a terminal in the IDE, and run the following command:

pixi info

3. To activate the Pixi environment and deactivate Conda environment variables, run the following command: 

pixi-shell

4. To ensure you don't inadvertently install packages into the wrong environment, run conda deactivate (once per IDE).

5. Install any additional GitHub-hosted Python packages you need. For details, see Install a GitHub Package (Tutorial). Be sure to import the package and confirm that it's installed correctly. See the tutorial for instructions.

6. Open a Python notebook. In the first cell, use the following command to import the HISE SDK. Then press Shift+Enter to run the cell.
   
   import hisepy as hp

7. To make the SDK call, enter the following code and run the cell. This creates a card you can select from the IDE creation workflow in order to reuse this environment.

hp.save_custom_pixi_environment(
    env_name="myCustomPixi",
    description="Pixi environment for testing and analysis. Includes project-specific GitHub utilities and is compatible with Python.",
    languages=["python"]
)

When your pixi.toml includes more than one Pixi environment option, HISE prompts you to choose which Pixi one to save when you call hp.save_custom_pixi_environment(). This ensures that environment you capture matches the specific Pixi environment you used in the IDE.


   Use the saved custom Pixi environment in a new IDE

After you save your custom Pixi environment with hp.save_custom_pixi_environment(), HISE makes it available as a reusable saved custom Pixi environment card you can select from the IDE creation workflow. You can use it to create additional IDEs with the same configuration.

1. From the top navigation menu, click RESEARCH, and choose IDEs from the drop-down menu.

2. To use your new saved Pixi environment, click the card that represents the environment you captured in Step 5.

3. On the Create an IDE with this package page, click CREATE IDE.

4. On the IDE Settings page, enter the requested information (Name, Description, and HISE Billing Project), and click CREATE. 

5. Wait while the IDE is provisioned. You can monitor its status on the IDE Details page.

6. Click the boxed arrow icon in the lower-left corner of the card to open the IDE.

7. To verify that your custom environment is in use, open a terminal in your IDE, and run pixi info. The output should looks something like the block below:

pixi 0.0.7

Platform: osx-arm64
...

Workspace
---------
Manifest file: /path/to/pixi.toml
Last updated: 25-01-2024 10:29:08

Environments
------------
default
  Features: default
  Channels: conda-forge
  Dependency count: 10
  Dependencies: pre-commit, rust, openssl, pkg-config, git, mkdocs, ...
  Target platforms: linux-64, osx-arm64, win-64, osx-64

Related Resources

 Use HISE SDK Methods and Get Help in the IDE

Install a GitHub Package in a Pixi Environment (Tutorial)