Pixi-Pack

Package and distribute Pixi environments as portable archives

pixi-pack is a tool that packages Pixi environments into compressed archives that can be shipped to target machines. The corresponding pixi-unpack tool recreates the environment without requiring Pixi, conda, or micromamba.

Installation

1. Install globally

   Install both tools using Pixi’s global installation:

   pixi global install pixi-pack pixi-unpack
   

   Or download pre-built binaries from the releases page.

2. Use with pixi exec

   Alternatively, run without installation:

   pixi exec pixi-pack
   pixi exec pixi-unpack environment.tar
   

If you have pixi, pixi-pack, and pixi-unpack installed globally, you can also use the shorter commands pixi pack and pixi unpack.

Creating a Pack

Package an environment for distribution:

pixi-pack --environment prod --platform linux-64 pixi.toml

This creates an environment.tar file containing all conda packages required for the environment:

environment.tar
├── pixi-pack.json
├── environment.yml
└── channel
    ├── noarch
    │   ├── tzdata-2024a-h0c530f3_0.conda
    │   ├── ...
    │   └── repodata.json
    └── linux-64
        ├── ca-certificates-2024.2.2-hbcca054_0.conda
        ├── ...
        └── repodata.json

Unpacking an Environment

Extract and recreate the environment on the target system:

pixi-unpack environment.tar

This creates:

• ./env/ - The conda environment
• activate.sh (or activate.bat on Windows) - Activation script

Bash/Zsh

$ pixi-unpack environment.tar
$ ls
env/
activate.sh
environment.tar

$ cat activate.sh
export PATH="/home/user/project/env/bin:..."
export CONDA_PREFIX="/home/user/project/env"
. "/home/user/project/env/etc/conda/activate.d/activate_custom_package.sh"

Cross-Platform Packs

Create packs for different platforms without running on that platform:

pixi-pack --platform win-64
pixi-pack --platform osx-arm64
pixi-pack --platform linux-64

You can only unpack a pack on a system with the same platform it was created for.

Self-Extracting Binaries

Create standalone executables that unpack without requiring pixi-unpack:

Linux/macOS

$ pixi-pack --create-executable
$ ls
environment.sh

$ ./environment.sh
$ ls
env/
activate.sh
environment.sh

Custom pixi-unpack Source

Specify a custom location for the pixi-unpack executable:

URL

pixi-pack --create-executable \
  --pixi-unpack-source https://my.mirror/pixi-pack/pixi-unpack-x86_64-unknown-linux-musl

The produced executable is a shell script containing both the pixi-unpack binary and the packed environment.

Advanced Features

Inject Additional Packages

Add packages not specified in pixi.lock:

pixi-pack --inject local-package-1.0.0-hbefa133_0.conda pixi.toml

This is useful for including locally built packages while using the workspace’s lockfile.

PyPI Support

Pack PyPI wheel packages into your environment:

pixi-pack --ignore-pypi-non-wheel --inject my_webserver-0.1.0-py3-none-any.whl

• Only wheel packages are supported (not source distributions)
• Use --ignore-pypi-non-wheel to skip source distributions
• Pixi-pack cannot verify wheel compatibility with the target environment

Mirror and S3 Configuration

Use custom mirrors or S3 buckets:

config.toml

[mirrors]
"https://conda.anaconda.org/conda-forge" = ["https://my.artifactory/conda-forge"]

[s3-options.my-s3-bucket]
endpoint-url = "https://s3.eu-central-1.amazonaws.com"
region = "eu-central-1"
force-path-style = false

pixi-pack --config config.toml

See the S3 documentation for more details.

Concurrency Control

Limit parallel downloads:

config.toml

[concurrency]
downloads = 5

Package Caching

Cache downloaded packages for faster subsequent operations:

pixi-pack --use-cache ~/.pixi-pack/cache

Benefits:

• Reuse packages across multiple packs
• Reduce bandwidth usage
• Speed up CI/CD pipelines
• Handle large packages efficiently

The cache follows the conda channel structure, organizing packages by platform subdirectories.

Unpacking Without pixi-pack

If pixi-pack is unavailable on the target system, use conda or micromamba:

1. Extract the archive

   tar -xvf environment.tar
   
2. Create the environment

   Micromamba

   micromamba create -p ./env --file environment.yml
   

The environment.yml and repodata.json files are only for this compatibility mode. pixi-unpack does not use them.

Both conda and mamba automatically install pip alongside Python, which differs from Pixi’s behavior. This can cause solver errors. Fix by either:

• Adding pip to your pixi.lock: pixi add pip
• Disabling pip auto-install: conda config --set add_pip_as_python_dependency false

Use Cases

Production Deployment

Package development environments for production deployment without internet access on target servers.

Air-Gapped Systems

Distribute software to air-gapped or restricted network environments.

Reproducibility

Ensure exact dependency versions across different machines and time periods.

CI/CD Optimization

Cache and reuse packages across pipeline runs to reduce build times.