ADR Suggestion Use Pixi for Project and Environment Management

[AndrewSazonov]

Note: We have already started using Pixi in some projects, so this suggestion is meant to capture and document the reasons behind this decision.

Across EasyScience projects, we rely on a mix of tools and conventions to manage Python versions, environments, dependencies, and project-specific commands. While this approach works, it often introduces unnecessary complexity - especially for onboarding new contributors.

A typical “traditional” setup usually involves the following steps:

• Installing the required Python version.
• Creating a virtual environment to avoid interfering with the system Python installation.
• Installing Python dependencies using Pip, and in some projects also using Conda packages, which results in mixing pip and conda.
• Managing repetitive or long-running tasks (tests, documentation builds, formatting, etc.) via shell or Python scripts, often with platform-specific differences.

While there are tools that address individual parts of this workflow, Pixi appears to be the only tool that covers all of these aspects in a single solution.

Suggestion

Use Pixi as the recommended tool for environment management, dependency management, and task execution across EasyScience projects.

This does not replace pyproject.toml as the source of truth for Python package metadata. Rather, Pixi complements it by providing a unified, reproducible development environment.

Main Benefits

• Ease of use
  One tool handles Python versions, environments, dependencies, and tasks, reducing setup friction.
• Python version management
  Python versions are explicitly declared per project, ensuring consistent behavior.
• Isolated environments
  Each project gets its own isolated environment with no risk of conflicts.
• PyPI + Conda support
  Pixi installs packages from both ecosystems cleanly, avoiding fragile pip + conda mixing.
• Performance
  Fast dependency resolution and environment creation compared to traditional workflows.
• Task management
  Common tasks (tests, docs, formatting, CI commands) can be declared once and run consistently via pixi run.

Example Workflow

Installing Pixi

• Follow the official guide:
  https://pixi.prefix.dev/latest/installation

Setting up a new project

• Initialize a new Pixi project and navigate into it:

  pixi init newproject
  cd newproject

• Set the Python version:

  pixi add python=3.12

• Add Conda dependencies (e.g. GSL):

  pixi add gsl

• Add PyPi dependencies (e.g. Numpy):

  pixi add --pypi numpy

• Define a task (example: tests with coverage):

  pixi task add cov "python -m pytest tests/unit/ --color=yes --cov=src/ --cov-report=term-missing"

• Run it:

  pixi run cov

Updating dependencies and Pixi

• Updating dependencies:

  pixi update

• Updating Pixi

  pixi self-update

Uninstalling Pixi

• See https://pixi.prefix.dev/latest/installation/#uninstall

Integration with Existing Projects

Note: In our projects, managing Python dependencies is a bit more involved, since they should remain defined in pyproject.toml to allow building the Python package independently of Pixi. That said, the overall idea and benefits of using Pixi for simplified, cross-platform project management should still be clear from the example above.

• Python dependencies should continue to live in pyproject.toml to allow:
  • standard Python packaging
  • PyPI builds independent of Pixi
• Pixi configuration focuses on:
  • environment definition
  • platform-specific dependencies
  • development and CI tasks

This keeps Pixi as an environment and workflow tool, not a replacement for Python packaging standards.

[rozyczko]

Versioning policy. Should pixi.lock be committed? We should point out that it should. What about .pixi/? We should point out that this dir should NOT be commited.

Migration plan - What happens to existing projects and workflows? We should mention that the new templating system (link to its ADR) will help sorting things out for EasyScience project. However, it would be wise to add a deadline - let's assume July 1, 2026 as the cutoff date for switching to pixi for all the projects. (date provided to foster discussion more than impose)

Rollback criteria. Under what circumstances would you abandon Pixi and revert? Maybe it would be useful to document rollback mechanisms to something else if/when Prefix-dev starts charging money or goes bust.

Scope clarity. Is this mandatory for all EasyScience repos? Or just the production ones?

[AndrewSazonov]

Thanks for the feedback.

1. Versioning policy
In the current approach, pixi.lock is expected to be committed and used in CI to ensure a fully reproducible environment. The .pixi/ directory, on the other hand, is excluded via .gitignore in the Copier templates. I agree this should be made explicit, and I will add this clarification to the ADR.

2. Migration plan
Personally, I’m fine with tying the migration to the rollout of the new Copier templates. Once all aspects are covered, discussed, implemented, and reviewed, we can then agree on a concrete deadline.

3. Rollback criteria
If Prefix were to start charging, my personal view is that Pixi would still likely be worth paying for, given how much it simplifies project setup, CI, and day-to-day development. We already rely on and pay for other commercial tools and services, so cost alone wouldn’t necessarily be a blocker.
If Pixi were to disappear entirely, we would of course need an alternative, but this feels more like a general risk-management question. We don’t currently document rollback strategies for most of our other core dependencies either, so I’m not sure this ADR needs to go much deeper here.

4. Scope clarity
I’ve started using Pixi not only for production repositories but also for templates, test repos, and other supporting projects under EasyScience - for exactly the same reasons outlined in the ADR. It simplifies setup and improves consistency regardless of project type. From my perspective, having two parallel approaches (Pixi for some repos, “traditional” tooling for others) would just increase complexity and maintenance effort, so I’d prefer a single, consistent approach across the organization.

[seventil]

At first I was going to write walls of complaints about pixi.lock, but it works well in my repo with the last update.

So, instead, my full-fledged support.