Use CloudRepo’s PyPI index from Pixi

This section provides comprehensive documentation for using CloudRepo with Pixi, the modern cross-platform package and environment management tool.

Introduction to Pixi

What is Pixi?

Pixi is a revolutionary cross-platform package management tool that bridges the conda and PyPI ecosystems, offering developers a unified solution for managing dependencies, environments, and workflows across Windows, macOS, and Linux. Built in Rust for exceptional performance, Pixi represents a significant evolution in Python package management.

Key advantages of Pixi include:

Cross-platform by design: Single configuration works seamlessly across Windows, macOS, and Linux
Dual ecosystem support: Native integration with both conda-forge and PyPI packages
Blazing fast performance: Up to 10x faster than conda, 4x faster than micromamba
Deterministic environments: Lock files ensure reproducible builds across all platforms
Language agnostic: Manage Python, R, C++, Rust, and other language dependencies
Built-in task runner: Define and execute project tasks without additional tools
Modern configuration: Single pixi.toml file replaces multiple config files

Why Use Pixi with CloudRepo?

Combining Pixi’s modern workflow with CloudRepo’s private repository hosting provides:

Private package distribution: Securely share internal packages across your organization
Cross-platform consistency: Ensure teams on different OS platforms get identical environments
Predictable pricing: Flat plan pricing with no per-seat licensing
Simplified CI/CD: One configuration file works across all build environments
Mixed dependencies: Seamlessly combine public PyPI/conda packages with private CloudRepo packages

Prerequisites

Before configuring Pixi to work with CloudRepo, ensure you have:

CloudRepo Account and Repository
- An active CloudRepo organization account
- A Python repository created in the CloudRepo Admin Portal
- A repository user with appropriate permissions (upload/download)
Note

Your admin user cannot directly access repositories for security reasons. Always create a dedicated repository user in the CloudRepo Admin Portal.

If you haven’t completed these steps, please refer to:
- Creating a Repository
- Creating Users

Pixi Installation

Install Pixi using the official installer:

Installing Pixi (Recommended Method)

# macOS and Linux
curl -fsSL https://pixi.sh/install.sh | bash

# Windows (PowerShell)
iwr -useb https://pixi.sh/install.ps1 | iex

Or install via conda/mamba:

Installing Pixi via Conda

conda install -c conda-forge pixi
# or
mamba install -c conda-forge pixi

Python Environment
- Python 3.8 or higher (managed by Pixi)
- A project directory for your Pixi configuration

Configuration

Basic Pixi Configuration for CloudRepo

Initialize a new Pixi project or add CloudRepo to an existing project:

Initializing a Pixi Project

# Create new project
pixi init my-project
cd my-project

# Or initialize in existing directory
pixi init

This creates a pixi.toml file. Give each private package the CloudRepo index URL, and pixi fetches that package from CloudRepo alone:

pixi.toml - Basic CloudRepo Configuration

[project]
name = "my-project"
version = "0.1.0"
description = "Project using CloudRepo for private packages"
authors = ["Your Team <team@example.com>"]
channels = ["conda-forge"]
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

[dependencies]
python = ">=3.8,<3.12"

[pypi-dependencies]
# Public packages from PyPI
requests = ">=2.28.0"
pandas = "*"

# Private packages: each names the CloudRepo index, so pixi fetches it from there alone
acme-private-package = { version = ">=1.0.0", index = "https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple" }
acme-utils = { version = "*", index = "https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple" }

Do not list CloudRepo under [pypi-options] beside PyPI: an index there serves every package, and a package someone publishes on PyPI under your private package’s name can be installed instead of yours. Give every private package its own index, including the private packages that your private packages depend on, because pixi looks up any package you have not pinned on PyPI. See Installing Private and Public Packages Together.

Authentication Setup

Pixi supports multiple authentication methods for private repositories:

Method 1: A .netrc File (Recommended, including CI/CD)

pixi reads PyPI credentials from a .netrc file: ~/.netrc on Linux and macOS, %HOME%\_netrc on Windows, or the file the NETRC environment variable names. The login is the email address of the user that created the token, in lower case; the password is the token.

~/.netrc

machine [organization-id].mycloudrepo.io
login you@example.com
password YOUR_REPOSITORY_TOKEN

Secure .netrc Permissions

chmod 600 ~/.netrc

In CI, write the file from your secrets and point NETRC at it; the CI/CD examples below do this. pixi has no per-index username or password environment variables.

Method 2: Keyring Integration (Most Secure for Development)

Using System Keyring for Credentials

# Install keyring where pixi can run it
pixi global install keyring

# Store the token in the system keyring under your email address
keyring set https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple you@example.com
# Paste your repository token when prompted

# Ask pixi to use keyring when it installs
pixi install --pypi-keyring-provider subprocess

For keyring, the index URL in your manifest must carry the username (https://you%40example.com@...) and no password, so pixi knows which keyring entry to read.

Multiple Index Configuration

Packages from more than one CloudRepo repository each name their own index URL. Everything else comes from PyPI:

pixi.toml - Multiple PyPI Indices

[project]
name = "multi-index-project"
channels = ["conda-forge"]
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

[pypi-dependencies]
# From PyPI, the default index
numpy = ">=1.24.0"
scipy = "*"

# From your main CloudRepo repository
acme-core = { version = ">=2.0.0", index = "https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple" }

# From a second CloudRepo repository
acme-ml-toolkit = { version = ">=1.0.0", index = "https://[organization-id].mycloudrepo.io/repositories/[ml-repository-id]/simple" }

Publishing Packages for Pixi

Building Python Packages

Create a standard Python package structure for publishing:

Package Directory Structure

my-package/
├── pyproject.toml      # Package configuration
├── pixi.toml          # Pixi environment configuration
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
├── tests/
│   └── test_module.py
└── README.md

Configure your package’s pyproject.toml:

pyproject.toml - Package Configuration

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-package"
version = "1.0.0"
description = "Private package for our team"
authors = [{name = "Your Team", email = "team@example.com"}]
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
]

Build the package:

Building Packages with Pixi

# Add build dependencies
pixi add --pypi build twine

# Build the package
pixi run python -m build

# This creates:
# dist/my_package-1.0.0-py3-none-any.whl
# dist/my_package-1.0.0.tar.gz

Publishing to CloudRepo

Upload your package to CloudRepo using twine:

Publishing to CloudRepo

# Configure .pypirc for CloudRepo
cat > ~/.pypirc << EOF
[distutils]
index-servers = cloudrepo

[cloudrepo]
repository = https://[organization-id].mycloudrepo.io/repositories/[repository-id]
username = [repository-user-email]
password = YOUR_REPOSITORY_TOKEN
EOF

# Upload the package
pixi run twine upload -r cloudrepo dist/*

# Or upload with the credential in the environment
export TWINE_USERNAME=[repository-user-email]
export TWINE_PASSWORD=YOUR_REPOSITORY_TOKEN
pixi run twine upload --non-interactive \
  --repository-url https://[organization-id].mycloudrepo.io/repositories/[repository-id] \
  dist/*

Platform-Specific Packages

Build and publish platform-specific packages with binary extensions:

pixi.toml - Platform-Specific Build Configuration

[project]
name = "native-extension"
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]

[dependencies]
python = "3.11.*"
cython = ">=3.0.0"
numpy = ">=1.24.0"

[tasks]
build-extension = "python setup.py build_ext --inplace"
build-wheel = { cmd = "python -m build --wheel", depends_on = ["build-extension"] }

# Platform-specific build tasks
[target.win-64.tasks]
build-wheel = "python -m build --wheel --plat-name win_amd64"

[target.linux-64.tasks]
build-wheel = "python -m build --wheel --plat-name manylinux2014_x86_64"

[target.osx-arm64.tasks]
build-wheel = "python -m build --wheel --plat-name macosx_11_0_arm64"

Build for all platforms:

Multi-Platform Build Process

# Build for current platform
pixi run build-wheel

# Or use cibuildwheel for comprehensive platform support
pixi add --pypi cibuildwheel
pixi run cibuildwheel --platform linux

# Upload all platform wheels
pixi run twine upload -r cloudrepo dist/*.whl

Version Management

Manage package versions effectively:

Version Management with Pixi

# Install bump2version for version management
pixi add --pypi bump2version

# Configure version bumping in setup.cfg
cat > setup.cfg << EOF
[bumpversion]
current_version = 1.0.0
commit = True
tag = True

[bumpversion:file:pyproject.toml]
search = version = "{current_version}"
replace = version = "{new_version}"
EOF

# Bump versions
pixi run bump2version patch  # 1.0.0 -> 1.0.1
pixi run bump2version minor  # 1.0.1 -> 1.1.0
pixi run bump2version major  # 1.1.0 -> 2.0.0

# Pre-release versions
pixi run bump2version --new-version 2.0.0-alpha.1 prerelease
pixi run bump2version --new-version 2.0.0-beta.1 prerelease
pixi run bump2version --new-version 2.0.0-rc.1 prerelease

Consuming Packages from CloudRepo

Adding Private Dependencies

Add CloudRepo packages to your Pixi project:

Adding Private Dependencies

# Add a private package from CloudRepo, with its private dependencies in the same
# command: pixi installs at once, and a private dependency it meets unpinned comes
# from PyPI. --index takes the index URL.
pixi add --pypi acme-private-package acme-utils --index https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple

# Add with version constraints
pixi add --pypi "acme-private-package>=2.0.0,<3.0.0" --index https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple

# Add to specific feature/environment
pixi add --pypi acme-dev-tools --index https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple --feature dev

Alternatively, manually edit pixi.toml:

pixi.toml - Private Dependencies

[pypi-dependencies]
# Simple private dependency
my-private-lib = { version = "*", index = "cloudrepo" }

# With version constraints
company-framework = { version = ">=2.0,<3.0", index = "cloudrepo" }

# With extras
ml-toolkit = { version = ">=1.0.0", extras = ["gpu", "viz"], index = "cloudrepo" }

# Pre-release versions
experimental-lib = { version = ">=1.0.0a1", index = "cloudrepo" }

Mixing Public and Private Indices

Efficiently combine packages from multiple sources:

pixi.toml - Mixed Dependencies Configuration

[project]
name = "mixed-dependencies"
channels = ["conda-forge", "pytorch"]
platforms = ["linux-64", "win-64", "osx-64", "osx-arm64"]

# Conda dependencies (from conda-forge/pytorch)
[dependencies]
python = "3.11.*"
pytorch = ">=2.0.0"
cudatoolkit = "11.8.*"  # Platform-specific, managed by conda

# PyPI dependencies
[pypi-dependencies]
# Public packages (from PyPI)
transformers = ">=4.30.0"
datasets = "*"

# Private packages (from CloudRepo)
company-ml-utils = { version = ">=2.0.0", index = "cloudrepo" }
internal-datasets = { version = "*", index = "cloudrepo" }

# Mixed - public package with private plugin
fastapi = ">=0.100.0"  # From PyPI
fastapi-company-auth = { version = ">=1.0.0", index = "cloudrepo" }  # Private auth plugin

Lock File Management

Pixi automatically manages lock files for reproducible environments:

Lock File Management

# Install dependencies and create/update lock file
pixi install

# Update all dependencies to latest compatible versions
pixi update

# Update specific packages only
pixi update numpy pandas my-private-package

# Show current lock file status
pixi list

# Clean and regenerate lock file
pixi clean
pixi install

The pixi.lock file ensures all team members and CI/CD systems get identical dependencies:

pixi.lock Structure (Example)

version: 4
environments:
  default:
    channels:
      - conda-forge
    packages:
      linux-64:
        - python: 3.11.0
        - numpy: 1.24.0
    pypi:
      - my-private-package:
          version: 2.1.0
          index: cloudrepo
          hash: sha256:abc123...

Note

Always commit pixi.lock to version control for reproducible builds.

Environment Specifications

Define multiple environments for different use cases:

pixi.toml - Multiple Environments

[project]
name = "multi-env-project"
channels = ["conda-forge"]
platforms = ["linux-64", "win-64", "osx-64"]

# Default environment dependencies
[dependencies]
python = "3.11.*"

[pypi-dependencies]
requests = "*"
my-core-lib = { version = ">=1.0.0", index = "cloudrepo" }

# Development environment
[feature.dev.dependencies]
pytest = ">=7.0.0"
black = ">=22.0.0"

[feature.dev.pypi-dependencies]
my-test-utils = { version = "*", index = "cloudrepo" }
pytest-cov = "*"

# Production environment
[feature.prod.dependencies]
gunicorn = "*"

[feature.prod.pypi-dependencies]
my-prod-monitor = { version = ">=2.0.0", index = "cloudrepo" }

# Data science environment
[feature.datascience.dependencies]
jupyter = "*"
scikit-learn = "*"

[feature.datascience.pypi-dependencies]
company-ml-lib = { version = ">=3.0.0", index = "cloudrepo" }

# Define environment combinations
[environments]
dev = ["dev"]
prod = ["prod"]
datascience = ["dev", "datascience"]

Activate and use environments:

Working with Environments

# Install default environment
pixi install

# Install specific environment
pixi install -e dev
pixi install -e prod
pixi install -e datascience

# Run commands in specific environment
pixi run -e dev pytest
pixi run -e prod gunicorn app:main
pixi run -e datascience jupyter notebook

# Shell into environment
pixi shell -e dev

Advanced Topics

Multi-Project Workspaces

Manage multiple related projects in a workspace:

Workspace Directory Structure

my-workspace/
├── pixi.toml           # Workspace configuration
├── pixi.lock
├── packages/
│   ├── core-lib/
│   │   ├── pyproject.toml
│   │   └── src/
│   ├── web-api/
│   │   ├── pyproject.toml
│   │   └── src/
│   └── cli-tool/
│       ├── pyproject.toml
│       └── src/
└── apps/
    ├── frontend/
    └── backend/

Workspace pixi.toml configuration:

Workspace pixi.toml

[workspace]
name = "my-workspace"
channels = ["conda-forge"]
platforms = ["linux-64", "win-64", "osx-64"]

# Workspace members
members = [
    "packages/core-lib",
    "packages/web-api",
    "packages/cli-tool",
]

# Shared dependencies across workspace
[dependencies]
python = "3.11.*"

[[pypi-indices]]
name = "cloudrepo"
url = "https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple"

# Workspace-wide tasks
[tasks]
test-all = "pytest packages/*/tests"
build-all = "python -m build packages/*"
publish-all = """
for pkg in packages/*; do
    cd $pkg && pixi run twine upload -r cloudrepo dist/*
    cd ../..
done
"""

Cross-Platform Builds

Configure platform-specific dependencies and builds:

pixi.toml - Cross-Platform Configuration

[project]
name = "cross-platform-app"
platforms = ["linux-64", "win-64", "osx-64", "osx-arm64"]

# Shared dependencies
[dependencies]
python = "3.11.*"

# Platform-specific dependencies
[target.linux-64.dependencies]
gtk = "*"  # Linux-only GUI toolkit

[target.win-64.dependencies]
pywin32 = "*"  # Windows-specific APIs

[target.osx-64.dependencies]
pyobjc = "*"  # macOS framework bindings

[target.osx-arm64.dependencies]
pyobjc = "*"
tensorflow-metal = "*"  # Apple Silicon acceleration

# Platform-specific PyPI packages from CloudRepo
[target.linux-64.pypi-dependencies]
company-linux-drivers = { version = "*", index = "cloudrepo" }

[target.win-64.pypi-dependencies]
company-windows-utils = { version = "*", index = "cloudrepo" }

# Platform-specific build tasks
[target.linux-64.tasks]
build = "gcc -shared -fPIC -o lib.so src/native.c"

[target.win-64.tasks]
build = "cl /LD src\\native.c /Fe:lib.dll"

[target.osx-64.tasks]
build = "clang -shared -o lib.dylib src/native.c"

Build for all platforms:

Cross-Platform Build Commands

# Install for current platform
pixi install

# Build for all platforms using CI
for platform in linux-64 win-64 osx-64 osx-arm64; do
    pixi install --platform $platform
    pixi run --platform $platform build
done

Conda Integration Alongside PyPI

Leverage both conda and PyPI packages effectively:

pixi.toml - Conda and PyPI Integration

[project]
name = "scientific-computing"
channels = ["conda-forge", "bioconda", "pytorch"]
platforms = ["linux-64", "osx-64"]

# Complex binary dependencies from conda
[dependencies]
python = "3.11.*"
numpy = ">=1.24.0"  # Optimized builds from conda
scipy = "*"
pytorch = ">=2.0.0"
cudatoolkit = "11.8.*"
mkl = "*"  # Intel Math Kernel Library
gdal = "*"  # Geospatial libraries
r-base = ">=4.0"  # R language support

# Python-only packages from PyPI/CloudRepo
[pypi-dependencies]
# Public PyPI packages
pandas = ">=2.0.0"
scikit-learn = "*"

# Private CloudRepo packages
company-ml-models = { version = ">=3.0.0", index = "cloudrepo" }
internal-bio-tools = { version = "*", index = "cloudrepo" }

# Use conda for system dependencies, PyPI for Python packages
[feature.bioinfo.dependencies]
blast = "*"  # NCBI BLAST from bioconda
samtools = "*"
bedtools = "*"

[feature.bioinfo.pypi-dependencies]
biopython = "*"
company-genomics = { version = ">=1.0.0", index = "cloudrepo" }

Task Runners and Scripts

Define reusable tasks in your Pixi configuration:

pixi.toml - Task Configuration

[project]
name = "task-runner-example"

[tasks]
# Simple tasks
test = "pytest tests/"
lint = "ruff check src/"
format = "black src/ tests/"

# Complex multi-step tasks
ci = { depends_on = ["lint", "test", "build"] }

# Tasks with arguments
test-verbose = "pytest -vvs tests/"
test-coverage = "pytest --cov=src --cov-report=html"

# Shell scripts
deploy = """
echo "Building package..."
python -m build
echo "Uploading to CloudRepo..."
twine upload -r cloudrepo dist/*
echo "Deployment complete!"
"""

# Python scripts
process-data = { cmd = "python scripts/process.py", inputs = ["data/*.csv"], outputs = ["processed/"] }

# Platform-specific tasks
[target.linux-64.tasks]
system-info = "uname -a && lscpu"

[target.win-64.tasks]
system-info = "systeminfo"

# Environment-specific tasks
[feature.dev.tasks]
watch = "watchdog src/ --command='pixi run test'"
debug = "python -m pdb src/main.py"

[feature.prod.tasks]
start-server = "gunicorn app:main --bind 0.0.0.0:8000"
health-check = "curl http://localhost:8000/health"

Execute tasks:

Running Pixi Tasks

# Run single task
pixi run test
pixi run lint

# Run task with dependencies
pixi run ci  # Runs lint, test, and build in order

# Run environment-specific task
pixi run -e dev watch
pixi run -e prod start-server

# Pass arguments to tasks
pixi run test -- --maxfail=1
pixi run python -- script.py --arg value

Features and Environments

Create flexible feature combinations:

pixi.toml - Advanced Features Configuration

[project]
name = "feature-example"

# Base dependencies
[dependencies]
python = "3.11.*"

[pypi-dependencies]
core-lib = { version = ">=1.0.0", index = "cloudrepo" }

# Testing feature
[feature.test.dependencies]
pytest = ">=7.0.0"

[feature.test.pypi-dependencies]
pytest-cov = "*"
test-fixtures = { version = "*", index = "cloudrepo" }

[feature.test.tasks]
test = "pytest"
test-ci = "pytest --junitxml=report.xml"

# Documentation feature
[feature.docs.dependencies]
sphinx = ">=5.0.0"

[feature.docs.pypi-dependencies]
company-sphinx-theme = { version = ">=1.0.0", index = "cloudrepo" }

[feature.docs.tasks]
build-docs = "sphinx-build docs/ docs/_build"
serve-docs = "python -m http.server --directory docs/_build"

# GPU feature
[feature.gpu.dependencies]
cuda = "11.8.*"
cudnn = "8.9.*"

[feature.gpu.pypi-dependencies]
torch = { version = ">=2.0.0", index = "pytorch" }
company-gpu-utils = { version = "*", index = "cloudrepo" }

# CPU-only feature (mutual exclusive with gpu)
[feature.cpu.pypi-dependencies]
torch = { version = ">=2.0.0+cpu", index = "pytorch-cpu" }

# Define environment combinations
[environments]
default = []
test = ["test"]
docs = ["docs"]
dev = ["test", "docs"]
gpu-dev = ["test", "gpu"]
cpu-dev = ["test", "cpu"]
prod-gpu = ["gpu"]
prod-cpu = ["cpu"]

Use different feature combinations:

Working with Features

# Install specific environment
pixi install -e gpu-dev
pixi install -e cpu-dev

# Run in specific environment
pixi run -e gpu-dev python train_model.py
pixi run -e docs build-docs

# List available environments
pixi info

# Clean specific environment
pixi clean -e test

CI/CD Integration

GitHub Actions

.github/workflows/pixi-package.yml

name: Pixi Package CI/CD

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  release:
    types: [published]

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python: ["3.9", "3.10", "3.11"]

    runs-on: ${{ matrix.os }}

    steps:
    - uses: actions/checkout@v4

    - name: Setup Pixi
      uses: prefix-dev/setup-pixi@v0.4.0
      with:
        pixi-version: latest
        cache: true
        cache-dependency-path: pixi.lock

    - name: Configure CloudRepo Authentication
      shell: bash
      env:
        CLOUDREPO_USERNAME: ${{ secrets.CLOUDREPO_USERNAME }}
        CLOUDREPO_API_TOKEN: ${{ secrets.CLOUDREPO_API_TOKEN }}
      run: |
        (umask 077 && printf 'machine %s\nlogin %s\npassword %s\n' "[organization-id].mycloudrepo.io" \
          "$CLOUDREPO_USERNAME" "$CLOUDREPO_API_TOKEN" > "$RUNNER_TEMP/.netrc")
        echo "NETRC=$RUNNER_TEMP/.netrc" >> "$GITHUB_ENV"

    - name: Install Dependencies
      run: pixi install -e test

    - name: Run Tests
      run: pixi run -e test test-ci

    - name: Upload Test Results
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: test-results-${{ matrix.os }}-${{ matrix.python }}
        path: report.xml

  build:
    needs: test
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Setup Pixi
      uses: prefix-dev/setup-pixi@v0.4.0
      with:
        pixi-version: latest

    - name: Configure CloudRepo Authentication
      shell: bash
      env:
        CLOUDREPO_USERNAME: ${{ secrets.CLOUDREPO_USERNAME }}
        CLOUDREPO_API_TOKEN: ${{ secrets.CLOUDREPO_API_TOKEN }}
      run: |
        (umask 077 && printf 'machine %s\nlogin %s\npassword %s\n' "[organization-id].mycloudrepo.io" \
          "$CLOUDREPO_USERNAME" "$CLOUDREPO_API_TOKEN" > "$RUNNER_TEMP/.netrc")
        echo "NETRC=$RUNNER_TEMP/.netrc" >> "$GITHUB_ENV"

    - name: Build Package
      run: |
        pixi run python -m build

    - name: Upload Build Artifacts
      uses: actions/upload-artifact@v4
      with:
        name: dist
        path: dist/

  publish:
    needs: build
    runs-on: ubuntu-latest
    if: github.event_name == 'release'

    steps:
    - uses: actions/checkout@v4

    - name: Download Build Artifacts
      uses: actions/download-artifact@v4
      with:
        name: dist
        path: dist/

    - name: Setup Pixi
      uses: prefix-dev/setup-pixi@v0.4.0

    - name: Publish to CloudRepo
      # twine reads its login from these three variables, so no .pypirc holds it
      env:
        TWINE_REPOSITORY_URL: https://${{ secrets.CLOUDREPO_ORG }}.mycloudrepo.io/repositories/${{ secrets.CLOUDREPO_REPO }}
        TWINE_USERNAME: ${{ secrets.CLOUDREPO_USERNAME }}
        TWINE_PASSWORD: ${{ secrets.CLOUDREPO_API_TOKEN }}
      run: |
        pixi add --pypi twine
        pixi run twine upload --non-interactive dist/*

GitLab CI

.gitlab-ci.yml

stages:
  - test
  - build
  - publish

variables:
  PIXI_CACHE_DIR: ${CI_PROJECT_DIR}/.pixi_cache

default:
  image: ghcr.io/prefix-dev/pixi:latest
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - .pixi_cache/
      - .pixi/
  # CLOUDREPO_USERNAME and CLOUDREPO_API_TOKEN are masked CI/CD variables
  before_script:
    - export NETRC="$HOME/.netrc"
    - (umask 077 && printf 'machine %s\nlogin %s\npassword %s\n' "[organization-id].mycloudrepo.io" "$CLOUDREPO_USERNAME" "$CLOUDREPO_API_TOKEN" > "$NETRC")

test:linux:
  stage: test
  script:
    - pixi install -e test
    - pixi run -e test test-ci
  artifacts:
    when: always
    reports:
      junit: report.xml

test:windows:
  stage: test
  tags:
    - windows
  before_script:
    - $env:NETRC = "$env:USERPROFILE\_netrc"
    - Set-Content -Path $env:NETRC -Value "machine [organization-id].mycloudrepo.io`nlogin $env:CLOUDREPO_USERNAME`npassword $env:CLOUDREPO_API_TOKEN"
  script:
    - pixi install -e test
    - pixi run -e test test-ci

build:
  stage: build
  script:
    - pixi install
    - pixi run python -m build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

publish:
  stage: publish
  only:
    - tags
  dependencies:
    - build
  script:
    - pixi add --pypi twine
    - |
      # twine reads its login from these three variables, so no .pypirc holds it
      export TWINE_REPOSITORY_URL="$CLOUDREPO_URL"
      export TWINE_USERNAME="$CLOUDREPO_USERNAME"
      export TWINE_PASSWORD="$CLOUDREPO_API_TOKEN"
      pixi run twine upload --non-interactive dist/*

Azure DevOps

azure-pipelines.yml

trigger:
  branches:
    include:
      - main
      - develop
  tags:
    include:
      - v*

pool:
  vmImage: 'ubuntu-latest'

stages:
- stage: Test
  jobs:
  - job: TestMatrix
    strategy:
      matrix:
        Linux_Python39:
          imageName: 'ubuntu-latest'
          pythonVersion: '3.9'
        Windows_Python311:
          imageName: 'windows-latest'
          pythonVersion: '3.11'
        macOS_Python310:
          imageName: 'macOS-latest'
          pythonVersion: '3.10'
    pool:
      vmImage: $(imageName)
    steps:
    - task: UsePythonVersion@0
      inputs:
        versionSpec: '$(pythonVersion)'

    - script: |
        curl -fsSL https://pixi.sh/install.sh | bash
        echo "##vso[task.prependpath]$HOME/.pixi/bin"
      displayName: 'Install Pixi'
      condition: ne(variables['Agent.OS'], 'Windows_NT')

    - pwsh: |
        iwr -useb https://pixi.sh/install.ps1 | iex
        echo "##vso[task.prependpath]$env:USERPROFILE\.pixi\bin"
      displayName: 'Install Pixi (Windows)'
      condition: eq(variables['Agent.OS'], 'Windows_NT')

    - bash: |
        (umask 077 && printf 'machine %s\nlogin %s\npassword %s\n' "[organization-id].mycloudrepo.io" \
          "$CLOUDREPO_USERNAME" "$CLOUDREPO_API_TOKEN" > "$(Agent.TempDirectory)/.netrc")
        echo "##vso[task.setvariable variable=NETRC]$(Agent.TempDirectory)/.netrc"
      env:
        CLOUDREPO_USERNAME: $(CloudRepoUsername)
        CLOUDREPO_API_TOKEN: $(CloudRepoApiToken)
      displayName: 'Configure CloudRepo Authentication'

    - script: |
        pixi install -e test
        pixi run -e test test-ci
      displayName: 'Run Tests'

    - task: PublishTestResults@2
      inputs:
        testResultsFiles: 'report.xml'
        testRunTitle: 'Python $(pythonVersion) - $(Agent.OS)'
      condition: always()

- stage: Build
  dependsOn: Test
  jobs:
  - job: BuildPackage
    steps:
    - bash: |
        (umask 077 && printf 'machine %s\nlogin %s\npassword %s\n' "[organization-id].mycloudrepo.io" \
          "$CLOUDREPO_USERNAME" "$CLOUDREPO_API_TOKEN" > "$(Agent.TempDirectory)/.netrc")
        echo "##vso[task.setvariable variable=NETRC]$(Agent.TempDirectory)/.netrc"
      env:
        CLOUDREPO_USERNAME: $(CloudRepoUsername)
        CLOUDREPO_API_TOKEN: $(CloudRepoApiToken)
      displayName: 'Configure CloudRepo Authentication'

    - script: |
        curl -fsSL https://pixi.sh/install.sh | bash
        export PATH="$HOME/.pixi/bin:$PATH"
        pixi install
        pixi run python -m build
      displayName: 'Build Package'

    - task: PublishPipelineArtifact@1
      inputs:
        targetPath: 'dist'
        artifactName: 'packages'

- stage: Publish
  dependsOn: Build
  condition: and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/tags/v'))
  jobs:
  - job: PublishToCloudRepo
    steps:
    - task: DownloadPipelineArtifact@2
      inputs:
        artifactName: 'packages'
        targetPath: 'dist'

    - script: |
        curl -fsSL https://pixi.sh/install.sh | bash
        export PATH="$HOME/.pixi/bin:$PATH"
        pixi add --pypi twine

        pixi run twine upload --non-interactive dist/*
      displayName: 'Publish to CloudRepo'
      # twine reads its login from these three variables, so no .pypirc holds it
      # (a secret variable reaches a script only through env:)
      env:
        TWINE_REPOSITORY_URL: $(CloudRepoUrl)
        TWINE_USERNAME: $(CloudRepoUsername)
        TWINE_PASSWORD: $(CloudRepoApiToken)

Troubleshooting

Common Issues and Solutions

Authentication Failures

Debugging Authentication Issues

# Check the .netrc entry without printing the token
sed -E 's/(password)[[:space:]]+[^[:space:]]+/\1 ***/g' "${NETRC:-$HOME/.netrc}"

# Test authentication directly (curl prompts for the token)
curl -u you@example.com \
  https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple/

# Clear Pixi cache and retry
pixi clean
pixi install

# Use verbose mode for debugging
PIXI_VERBOSITY=3 pixi install

SSL/TLS Certificate Issues

Resolving SSL Issues

# Point pixi at a CA bundle containing the public roots AND your corporate CA.
#
# SET BOTH VARIABLES -- they reach different consumers:
#   SSL_CERT_FILE       pixi itself (a Rust binary); ignored by requests
#   REQUESTS_CA_BUNDLE  pip / requests running INSIDE the environment. requests
#                       never reads SSL_CERT_FILE, and on macOS and Windows nothing
#                       else supplies it either -- so dropping this one silently
#                       strips the corporate CA from `pixi run pip install`.
pixi add certifi
CERTIFI_PEM="$(pixi run python -m certifi)" && \
  cat "$CERTIFI_PEM" /path/to/corporate-ca.crt > /path/to/ca-bundle.pem
export SSL_CERT_FILE=/path/to/ca-bundle.pem
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem

# Configure git for corporate certificates
git config --global http.sslCAInfo /path/to/ca-bundle.pem

Package Resolution Conflicts

Debugging Package Conflicts

# Show detailed solver information
PIXI_VERBOSITY=3 pixi install

# Clean all caches and reinstall
pixi clean --all
rm pixi.lock
pixi install

# Show dependency tree
pixi list --explicit

# Update specific packages only
pixi update numpy pandas

# Force reinstall
pixi install --force-reinstall

Platform-Specific Issues

Platform-Specific Debugging

# Check current platform
pixi info

# Install for specific platform
pixi install --platform linux-64

# List platform-specific packages
pixi list --platform win-64

# Clear platform-specific cache
pixi clean --platform osx-arm64

A Private Package Installs from PyPI

pixi takes each package from the first index that has it, and ranks extra-index-urls above index-url. Reordering the indexes protects only the names CloudRepo already has, so pin the package to CloudRepo instead:

Pinning a private package to CloudRepo

[pypi-dependencies]
acme-private-package = { version = "*", index = "https://[organization-id].mycloudrepo.io/repositories/[repository-id]/simple" }

Lock File Corruption

Fixing Lock File Issues

# Backup current lock file
cp pixi.lock pixi.lock.backup

# Remove and regenerate
rm pixi.lock
pixi install

# Compare with backup if needed
diff pixi.lock pixi.lock.backup

# Update lock without installing
pixi lock

Slow Package Downloads

Improving Download Performance

# Use parallel downloads
export PIXI_MAX_WORKERS=10

# Configure timeout
export PIXI_REQUEST_TIMEOUT=60

# Use a local cache server (if available). Serve it over TLS with a certificate your
# machines already trust -- your internal CA is fine, import it once per machine.
export PIP_INDEX_URL=https://local-cache:8443/simple

# Pre-download packages for offline use
pixi install --frozen
pixi list --json > packages.json

If the cache can only speak plaintext today, keep it bound to the loopback interface so nothing off-host can reach it, and put TLS in front of it before it serves anything on a shared network. Do not reach for a flag that turns certificate verification off – that trades a local problem for one that applies to every host the tool talks to.

Best Practices

Version Control: Always commit both pixi.toml and pixi.lock files
Environment Isolation: Use features and environments for different contexts
Security: Never commit credentials; use a .netrc file or keyring
Cross-Platform: Test on all target platforms before releasing
Caching: Leverage Pixi’s caching in CI/CD for faster builds
Documentation: Document custom indices and authentication in README
Updates: Regularly update dependencies with pixi update
Reproducibility: Use pixi install --frozen in production

Performance Tips

Index Configuration: Place CloudRepo as primary index if most packages are private
Parallel Installation: Enable with PIXI_MAX_WORKERS environment variable
Cache Management: Use pixi clean periodically to manage disk space
Minimal Dependencies: Use features to avoid installing unnecessary packages
Platform-Specific Builds: Build native extensions per platform for best performance

Getting Help

If you encounter issues not covered in this documentation:

Check the Pixi documentation
Review CloudRepo’s Knowledge Base
Visit the Pixi Discord community
Contact CloudRepo support at support@cloudrepo.io

CloudRepo support is included with all plans - we respond within one business day and are here to help you succeed with your cross-platform package management.