Pixitainer

This banner placeholder was generated by Gemini 3 Banana Pro using already made asset like the pixi, apptainer and singularity logo

Why...

...pixi ?

Pixi is a fast, easy and fun to use tool that allows you to manage multiple dependencies in multiple environment very easily. It has a great support either by its developers or community on discord.

...using containers ?

Singularity/Apptainer is very used in bioinformatics, it's at the hearth of analyzes pipelines, but it's a headache to put in place. In another hand, pixi is fast, easy to use, but it's not a container and so harder to keep intact for a long period of time. The idea behind pixitainer is to put a pixi environment into an Apptainer container, so you can freeze your fast pace working environment into a container easily !

Apptainer vs Singularity

Apptainer is more the "public library" version of the software, while Singularity is more like a "corporate bookstore." Because Apptainer is hosted by the Linux Foundation, it is designed specifically for the scientific community to ensure that your research code remains free, accessible and without being tied to a private company’s profit goals.

Singularity is often found on high-performance computing (HPC) clusters and is maintained by Sylabs. Pixitainer supports both!

Projects using pixitainer

• FastDedup a PCR deduplication tool written in Rust optimized for speed and low memory usage.

How to install

1. Install pixi

curl -fsSL https://pixi.sh/install.sh | sh

Install pixitainer (Apptainer) or pixitainer-singularity (Singularity) globaly on pixi:

# For Apptainer
pixi global install -c https://prefix.dev/raphaelribes -c https://prefix.dev/conda-forge pixitainer

# For Singularity
pixi global install -c https://prefix.dev/raphaelribes -c https://prefix.dev/conda-forge pixitainer-singularity

Developer

1. Clone this repo

git clone https://github.com/RaphaelRibes/pixitainer.git
cd pixitainer

2. Build the pixitainer extension

pixi build

3. Install the pixitainer extension

# Apptainer
pixi global install pixitainer --path pixitainer-0.6.1*.conda --channel conda-forge

# Singularity
pixi global install pixitainer-singularity --path pixitainer-singularity-0.6.1*.conda --channel conda-forge

How to use

You actually have two ways of using pixitainer:

1. Manually
2. Seamlessly

We put ourselves in an environment with one task defined like

[tasks]
make_dir = 'mkdir testdir'

Manually

# For Apptainer
pixi containerize

# For Singularity
pixi containerize-singularity

Then you can use pixi in your image

# Apptainer
apptainer run -f pixitainer.sif pixi run --as-is -m /opt/conf/pixi.toml make_dir

# Singularity
singularity run -f pixitainer.sif pixi run --as-is -m /opt/conf/pixi.toml make_dir

We add --as-is to make sure it sticks to the pixi.lock file, and it only uses the installed binaries and doesn't try to install others.

WARNING: -m /opt/conf/pixi.toml is mandatory or pixi will use the default one in your current working directory.

Seamlessly

Use the pixitainer extension command after installing it with the seamless option (-s, --seamless).

# For Apptainer
pixi containerize -s

# For Singularity
pixi containerize-singularity -s

You can then turn your task like pixi is not even here

# Apptainer
apptainer run -f pixitainer.sif make_dir

# Singularity
singularity run -f pixitainer.sif make_dir

WARNING: the seamless mode makes that every commands run through the image are ran like so

pixi run --as-is -m /opt/conf/pixi.toml "$@"

Meaning that you only have access to pixi run.

TOML Configuration

Since v0.6.0, you can configure pixitainer options directly in your project manifest (pixi.toml or pyproject.toml) using the [tool.pixitainer] table. This avoids passing long command-line arguments every time you build.

[tool.pixitainer]
output = "my_image.sif"
base-image = "ubuntu:24.04"
seamless = true
env = ["default"]
add-file = ["data/config.yaml:/opt/config.yaml"]
post-command = ["echo 'Setup done' > /opt/setup.log"]
label = ["APP_VERSION:1.0.0", "AUTHOR:me"]
keep-def = false
dry-run = false
quiet = false
verbose = false

Note: All keys mirror the long-form CLI option names (without the -- prefix). Boolean options use true/false, and array options (env, add-file, post-command, label) use TOML array syntax.

CLI overrides TOML

Command-line arguments always take precedence over values set in the [tool.pixitainer] table. This lets you define sensible defaults in your manifest while overriding them on a per-build basis:

# Uses TOML defaults, but overrides the output path
pixi containerize -o custom_output.sif

Known problems

Pathing is... strange?

When launching a command in the pixi shell, the cwd of tasks will be changed into the one of the pixi workplace (PIXI_PROJECT_ROOT).

Let's create a task

[tasks]
make_dir = 'mkdir testdir'

If you run this task, it's going to create $PIXI_PROJECT_ROOT/testdir (/opt/conf/testdir) and not $INIT_CWD/testdir ($(pwd)/testdir). What you want is to run pixi in the INIT_CWD so take the time to change your ./something to $INIT_CWD/something.

Note: The container now defaults to /opt/conf as the working directory (pwd -P returns /opt/conf). This ensures compatibility with internal path resolutions, but you should rely on $INIT_CWD for input/output relative to where you run the container. If you have files to import in the container (ex: your build) you can put it in /opt/conf and it will allow normal execution. However, be conscious that your outputs will also be in /opt/conf and not in your current working directory. Since you cannot write in a container, you will have to specify the outputs with $INIT_CWD and bind the folder where you want your outputs to be.

Read-only file system (os error 30)

This is related to the previous problem: pixi is using PIXI_PROJECT_ROOT as the cwd. It's going to try to write in /opt/conf wich is not allowed because the sif image is in read only. To fix it, replace your mkdir test byt mkdir $INIT_CWD/test.

However, sometimes pixi may write something in its cache so don't hesitate to use --writable-tmpfs.

How ?

The best thing to do will be to add this way as a pixi extension, so we just have to type pixi containerize, some option and tada !

Note that pixitainer will install pixi with the same version that you have on your machine, you can change it with options look down below.

TODO:

• [x] Receipe that works.
• [x] Pixi package that I can add as an extension.
• [x] Adding options to the extension.
  • [x] Core Options
    • [x] Output image path (-o, --output)
    • [x] Working directory (-p, --path)
    • [x] Enable seamless execution (-s, --seamless)
  • [x] Environment & Image Setup
    • [x] Specify base image (-b, --base-image)
    • [x] Specific environment selection (-e, --env)
    • [x] No installation of environment in the container (-n, --no-install)
  • [x] Pixi Versioning
    • [x] Specify pixi version (-V, --pixi-version)
    • [x] Latest pixi version (-L, --latest)
  • [x] Advanced Modifications
    • [x] Add extra files/folders (-a, --add-file)
    • [x] Run extra post commands (-c, --post-command)
    • [x] Add extra labels (-l, --label)
    • [x] Export the .def file (-k, --keep-def)
  • [x] Output Options
    • [x] Dry-run (-d, --dry-run)
  • [x] General Options
    • [x] Quiet mode (-q, --quiet)
    • [x] Verbose mode (-v, --verbose)
• [x] Support the options in a [tool.pixitainer] table in the manifest
• [ ] Support of container solutions
  • [x] Apptainer
  • [x] Singularity
  • [ ] Docker

    Note that by default pixitainer is made with Apptainer in mind so it will be an option to install other container solutions.

• [x] Testings.
• [x] Publish
• [ ] Go back to step 3 until WW3, messiah or death of the internet

License

Pixitainer is licensed under the BSD 3-Clause License. See the LICENSE file for more details.