|
1 | | -# `pixi-pack` 📦 |
| 1 | +# `pixi-pack` |
| 2 | + |
| 3 | +<br /> |
| 4 | +<p align="center"> |
| 5 | + <h3 align="center">📦 A tool to pack and unpack conda environments created with pixi</h3> |
| 6 | +</p> |
| 7 | + |
| 8 | +## 🗂 Table of Contents |
| 9 | + |
| 10 | +- [Introduction](#-introduction) |
| 11 | +- [Installation](#-installation) |
| 12 | +- [Usage](#-usage) |
| 13 | + |
| 14 | +## 📖 Introduction |
| 15 | + |
| 16 | +Starting with a [pixi](https://pixi.sh) lockfile `pixi.lock`, you can create a packed environment that can be shared with others. |
| 17 | +This environment can be unpacked on any system using `pixi-pack` to recreate the original environment. |
| 18 | + |
| 19 | +In contrast to [`conda-pack`](https://conda.github.io/conda-pack/), `pixi-pack` does not require the original conda environment to be present on the system for packing. |
| 20 | +Instead, it uses the lockfile to download the required packages and puts them into a `.tar.zstd` archive. |
| 21 | +This archive can then be shared with others and installed using `pixi-pack unpack` to recreate the original environment. |
| 22 | + |
| 23 | +The original motivation behind `pixi-pack` was to create a `conda-pack` alternative that does not have the same reproducibility issues as `conda-pack`. |
| 24 | +It also aims to allow cross-platform building packs, so you can create a pack for `win-64` on a `linux-64` system. |
| 25 | + |
| 26 | +## 💿 Installation |
| 27 | + |
| 28 | +You can install `pixi-pack` using `pixi`: |
| 29 | + |
| 30 | +```bash |
| 31 | +pixi global install pixi-pack |
| 32 | +``` |
| 33 | + |
| 34 | +Or using `cargo`: |
| 35 | + |
| 36 | +```bash |
| 37 | +cargo install --locked --git https://github.com/quantco/pixi-pack.git |
| 38 | +``` |
| 39 | + |
| 40 | +## 🎯 Usage |
| 41 | + |
| 42 | +### `pixi-pack pack`: Packing an environment |
| 43 | + |
| 44 | +With `pixi-pack pack`, you can pack a conda environment into a `environment.tar.zstd` file: |
| 45 | + |
| 46 | +```bash |
| 47 | +pixi-pack pack --manifest-file pixi.toml --environment prod --platform linux-64 |
| 48 | +``` |
| 49 | + |
| 50 | +This will create a `environment.tar.zstd` file that contains all conda packages required to create the environment. |
| 51 | + |
| 52 | +``` |
| 53 | +# environment.tar.zstd |
| 54 | +| pixi-pack.json |
| 55 | +| environment.yml |
| 56 | +| channel |
| 57 | +| ├── noarch |
| 58 | +| | ├── tzdata-2024a-h0c530f3_0.conda |
| 59 | +| | ├── ... |
| 60 | +| | └── repodata.json |
| 61 | +| └── linux-64 |
| 62 | +| ├── ca-certificates-2024.2.2-hbcca054_0.conda |
| 63 | +| ├── ... |
| 64 | +| └── repodata.json |
| 65 | +``` |
| 66 | + |
| 67 | +### `pixi-pack unpack`: Unpacking an environment |
| 68 | + |
| 69 | +With `pixi-pack unpack environment.tar.zstd`, you can unpack the environment on your target system. |
| 70 | +This will create a new conda environment in `./env` that contains all packages specified in your `pixi.toml`. |
| 71 | +It also creates an `activate.sh` (or `activate.bat` on Windows) file that lets you activate the environment |
| 72 | +without needing to have `conda` or `micromamba` installed. |
| 73 | + |
| 74 | +```bash |
| 75 | +$ pixi-pack unpack environment.tar.zstd |
| 76 | +$ ls |
| 77 | +env/ |
| 78 | +activate.sh |
| 79 | +environment.tar.zstd |
| 80 | +$ cat activate.sh |
| 81 | +export PATH="/home/user/project/env/bin:..." |
| 82 | +export CONDA_PREFIX="/home/user/project/env" |
| 83 | +. "/home/user/project/env/etc/conda/activate.d/activate_custom_package.sh" |
| 84 | +``` |
| 85 | + |
| 86 | +### Cross-platform packs |
| 87 | + |
| 88 | +Since `pixi-pack` just downloads the `.conda` and `.tar.bz2` files from the conda repositories, you can trivially create packs for different platforms. |
| 89 | + |
| 90 | +```bash |
| 91 | +pixi-pack pack --platform win-64 |
| 92 | +``` |
| 93 | + |
| 94 | +> [!NOTE] |
| 95 | +> You can only `unpack` a pack on a system that has the same platform as the pack was created for. |
| 96 | +
|
| 97 | +### Inject additional packages |
| 98 | + |
| 99 | +You can inject additional packages into the environment that are not specified in `pixi.lock` by using the `--inject` flag: |
| 100 | + |
| 101 | +```bash |
| 102 | +pixi-pack pack --inject local-package-1.0.0-hbefa133_0.conda --manifest-pack pixi.toml |
| 103 | +``` |
| 104 | + |
| 105 | +This can be particularly useful if you build the project itself and want to include the built package in the environment but still want to use `pixi.lock` from the project. |
| 106 | + |
| 107 | +### Unpacking without `pixi-pack` |
| 108 | + |
| 109 | +If you don't have `pixi-pack` available on your target system, you can still install the environment if you have `conda` or `micromamba` available. |
| 110 | +Just decompress the `environment.tar.zstd`, then you have a local channel on your system where all necessary packages are available. |
| 111 | +Next to this local channel, you will find an `environment.yml` file that contains the environment specification. |
| 112 | +You can then install the environment using `conda` or `micromamba`: |
| 113 | + |
| 114 | +```bash |
| 115 | +tar --zstd -xvf environment.tar.zstd |
| 116 | +micromamba create -p ./env --file environment.yml --override-channels -c "file://$(pwd)/channel" |
| 117 | +# or |
| 118 | +conda create -p ./env --file environment.yml --override-channels -c "file://$(pwd)/channel" |
| 119 | +``` |
| 120 | + |
| 121 | +> [!NOTE] |
| 122 | +> The `environment.yml` and `repodata.json` files are only for this use case, `pixi-pack unpack` does not use them. |
0 commit comments