GitHub Actions

Integrate Pixi with GitHub Actions for CI/CD workflows

The prefix-dev/setup-pixi action makes it easy to use Pixi in GitHub Actions workflows.

Quick Start

.github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: prefix-dev/setup-pixi@v0.9.4
        with:
          pixi-version: v0.65.0
          cache: true
      
      - run: pixi run test

Pin the action version (e.g., prefix-dev/setup-pixi@v0.9.4) to avoid breaking changes. Use Dependabot to keep it updated.

Version Pinning with Dependabot

Automatically update the action version:

.github/dependabot.yml

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: monthly
    groups:
      dependencies:
        patterns:
          - "*"
    cooldown:
      default-days: 7

Key Features

Caching

Automatic caching speeds up workflows by reusing installed environments.

Project Environment Caching

Enabled by default when pixi.lock exists:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    cache: true  # Default when pixi.lock exists

Global Environment Caching

Disabled by default, expires monthly:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    cache: true
    global-cache: true

Custom Cache Keys

Customize cache key prefixes:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    cache: true
    cache-key: my-custom-key-
    global-cache-key: my-global-key-

Save Caches Only on Main

Prevent hitting the 10GB cache limit:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    cache: true
    cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}

Multiple Environments

Test across different Python versions or configurations.

Environment Configuration

pixi.toml

[workspace]
name = "my-package"
channels = ["conda-forge"]
platforms = ["linux-64"]

[dependencies]
python = ">=3.11"
polars = ">=0.14.24,<0.21"

[feature.py311.dependencies]
python = "3.11.*"

[feature.py312.dependencies]
python = "3.12.*"

[environments]
py311 = ["py311"]
py312 = ["py312"]

Matrix Strategy

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        environment: [py311, py312]
    steps:
      - uses: actions/checkout@v4
      
      - uses: prefix-dev/setup-pixi@v0.9.4
        with:
          environments: ${{ matrix.environment }}
      
      - run: pixi run test

Multiple Environments in One Job

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    environments: >-
      py311
      py312

- run: |
    pixi run -e py311 test
    pixi run -e py312 test

If you don’t specify environments, only the default environment is cached, even if you use others.

Global Environments

Install tools needed before pixi install runs:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    global-cache: true
    global-environments: |
      google-cloud-sdk
      keyring --with keyrings.google-artifactregistry-auth

- run: |
    gcloud --version
    keyring --list-backends

Authentication

Token Authentication

For prefix.dev and similar services:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    auth-host: prefix.dev
    auth-token: ${{ secrets.PREFIX_DEV_TOKEN }}

Always use GitHub secrets for sensitive information. Never commit credentials to your repository.

Username and Password

For Artifactory and enterprise environments:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    auth-host: custom-artifactory.com
    auth-username: ${{ secrets.PIXI_USERNAME }}
    auth-password: ${{ secrets.PIXI_PASSWORD }}

Conda Token

For anaconda.org and Quetz:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    auth-host: anaconda.org
    auth-conda-token: ${{ secrets.CONDA_TOKEN }}

S3 Authentication

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    auth-host: s3://my-s3-bucket
    auth-s3-access-key-id: ${{ secrets.ACCESS_KEY_ID }}
    auth-s3-secret-access-key: ${{ secrets.SECRET_ACCESS_KEY }}
    auth-s3-session-token: ${{ secrets.SESSION_TOKEN }}  # Optional

See the S3 documentation and authentication guide for details.

PyPI Keyring Provider

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    pypi-keyring-provider: subprocess

Custom Shell Wrapper

Run commands inside the Pixi environment without pixi run:

Bash

- run: |
    python --version
    pip install --no-deps -e .
  shell: pixi run bash -e {0}

The {0} placeholder is replaced with a temporary script file created by GitHub Actions.

One-off Commands with pixi exec

Run commands in a temporary environment:

Bash

- run: |
    zstd --version
  shell: pixi exec --spec zstd -- bash -e {0}

Environment Activation

Activate the environment for all subsequent steps:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    activate-environment: true

- run: python --version  # No 'pixi run' needed

- run: pytest tests/     # Directly use installed tools

With Multiple Environments

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    environments: >-
      py311
      py312
    activate-environment: py311

- run: python --version  # Uses py311 environment

This is useful for non-shell steps that need binaries on the PATH.

Lock File Management

—frozen Flag

Reject any changes to the lockfile:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    frozen: true

—locked Flag

Only install if lockfile is up-to-date:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    locked: true

By default, the action runs:

• pixi install --locked if pixi.lock exists
• pixi install otherwise

See the official documentation for more details.

Debugging

Action Debug Logging

Enable by re-running the workflow in debug mode via the GitHub UI.

Pixi Debug Logging

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    log-level: vvv  # Options: q, default, v, vv, vvv

The log level defaults to vv when action debug logging is enabled.

Self-Hosted Runners

Configure cleanup and custom paths for self-hosted runners:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    post-cleanup: true  # Default: true
    pixi-bin-path: ${{ runner.temp }}/bin/pixi

Post-cleanup removes:

• .pixi environment
• Pixi binary
• Rattler cache
• Other rattler files in ~/.rattler

Use Pre-installed Pixi

If Pixi is already installed on the runner, omit version configuration:

- uses: prefix-dev/setup-pixi@v0.9.4
  # No pixi-version, pixi-url, or pixi-bin-path

The action will use the Pixi found in PATH.

Advanced Configuration

pyproject.toml as Manifest

Use pyproject.toml instead of pixi.toml:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    manifest-path: pyproject.toml

The action auto-detects pyproject.toml if it contains [tool.pixi.workspace] and no pixi.toml exists.

Working Directory for Monorepos

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    working-directory: ./packages/my-project

- run: pixi run test
  working-directory: ./packages/my-project

Custom Download URL

Download Pixi from a custom mirror:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    pixi-url: https://pixi-mirror.example.com/releases/download/v0.48.0/pixi-x86_64-unknown-linux-musl
    pixi-url-headers: '{"Authorization": "Bearer ${{ secrets.PIXI_MIRROR_TOKEN }}"}'

Install-Only Mode

Only install Pixi without running pixi install:

- uses: prefix-dev/setup-pixi@v0.9.4
  with:
    run-install: false

- run: pixi info

Complete Example

.github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: [py311, py312]
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: prefix-dev/setup-pixi@v0.9.4
        with:
          pixi-version: v0.65.0
          cache: true
          cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
          environments: ${{ matrix.python-version }}
          locked: true
      
      - name: Run tests
        run: pixi run -e ${{ matrix.python-version }} test
      
      - name: Run linting
        run: pixi run -e ${{ matrix.python-version }} lint
      
      - name: Build package
        if: matrix.os == 'ubuntu-latest' && matrix.python-version == 'py312'
        run: pixi run build

Best Practices

Pin Versions

Always pin the action version and use Dependabot for updates.

Cache Wisely

Only save caches on main branch to avoid hitting the 10GB limit.

Use Secrets

Store all sensitive data in GitHub Secrets, never in code.

Matrix Testing

Test across multiple OS and Python versions for better coverage.

Locked Installs

Use locked: true in CI to ensure reproducible builds.

More Examples

For additional examples, see the setup-pixi test workflows.