Description

I propose adding support for including sub-projects' pixi.toml files in the main project's pixi.toml, while preserving the ability for each sub-project's pixi.toml to work independently. When resolving the main project's configuration, all included sub-project pixi.toml files will be merged into a single unified configuration, which is then used for dependency resolution, environment setup, and other Pixi-related workflows.

Background & Use Case

In monorepo or multi-module projects, we often split code into independent sub-projects (e.g., packages/module-a, tools/utils), where each sub-project:

• Has its own pixi.toml (defines dependencies, scripts, environment settings specific to the sub-project).

• Needs to work independently (e.g., running pixi install directly in the sub-project directory should install its own dependencies and work as expected).

However, when working on the main project, we need a way to:

• Aggregate all sub-project configurations into the main project's workflow (e.g., install all dependencies from main + sub-projects in one command, run cross-sub-project scripts, or set up a unified development environment).
• Avoid duplicating dependencies/configurations across the main and sub-project pixi.toml files.
• Ensure consistent dependency resolution across the entire project (via unified merging of all configurations before parsing).

Currently, Pixi only parses a single pixi.toml per project, which forces us to either:

• Duplicate configuration across files (error-prone, hard to maintain).
• Manually manage dependencies across main + sub-projects (risk of version conflicts).
• Lose the ability to run sub-projects independently.
  This feature solves these pain points by enabling modular, composable pixi.toml files while preserving independent sub-project functionality.

other tools

uv workspace

Proposed Feature Details

1. Explicit Inclusion of Sub-Project pixi.toml
   Add a new field (e.g., includes) to the main project's pixi.toml to list paths to sub-project pixi.toml files. Paths can be relative to the main pixi.toml or absolute:

# Main project's pixi.toml
[project]
name = "main-project"
version = "1.0.0"
# New field: list sub-project pixi.toml paths
includes = [
"./packages/module-a/pixi.toml",
"./tools/utils/pixi.toml",
"./examples/demo/pixi.toml"
]

[dependencies]
# Main project's core dependencies
python = ">=3.10"
foo = "2.1.0"

2. Preserve Sub-Project Independence

   • Each sub-project's pixi.toml remains a valid, standalone configuration. Running Pixi commands (e.g., pixi install, pixi run) directly in the sub-project directory will only use that sub-project's pixi.toml (ignores the main project's includes field).

   • Sub-project pixi.toml files do not need to include the main project or other sub-projects (no circular dependency risk by default).

3. Merging Rules for Unified Configuration

   When resolving the main project's pixi.toml, Pixi will merge the main configuration with all included sub-project pixi.toml files into a single "super config" with rules we agree on, i propose the following merging logic:

   • Dependencies: Union of all dependencies from main + sub-projects. Version conflict resolution follows Pixi's existing rules (e.g., all project dependencies are considered without precedence).
     • Example: If main project has foo == "2.1.0" and sub-project has foo = "2.0.0", the merged config will raise conflict.

       main project	sub-project1	sub-project2	merged config
       foo>=2.0.0	_	_	foo>=2.0.0
       _	foo>=2.0.0	_	foo>=2.0.0
       foo=2.1.0	foo=2.0.0	_	conflict(foo)
       _	foo=2.0.0	foo=2.1.0	conflict(foo)
       foo>=2.0.0	foo=2.1.0	_	foo=2.1.0
       foo>=2.0.0	foo>=2.1.0	foo=2.2.0	foo=2.2.0
       foo>=2.0.0	foo>=2.1.0	foo<=2.2.0	foo>=2.1.0,<=2.2.0

   • pypi-dependencies: Merged similarly to dependencies.
   • features: Only features defined in the main pixi.toml are considered for merging, while sub-project specific features are ignored unless explicitly included. see "Sub-Project Specific Dependencies" under Potential Edge Cases & Solutions.
   • Scripts/Commands: ignored, only main project's scripts are used.
   • pypi-options: Merged with main project's options taking precedence in case of conflicts.

4. Unified Workflow for Main Project
   After merging, all Pixi commands run in the main project directory use the merged unified configuration:

   • pixi install: Installs all dependencies from main + sub-projects (no duplicate installations for shared dependencies).
   • Lockfile: Generates/uses a single pixi.lock in the main project directory that tracks all resolved dependencies from the merged configuration (sub-projects do not generate their own lockfiles when used via the main project's includes—only when run independently).

Benefits

• Modularity: Keep sub-project configurations isolated and maintainable.
• Independence: Sub-projects work as standalone Pixi projects (no lock-in to the main project).
• Unified Workflow: Main project can orchestrate all sub-projects with a single command (e.g., one pixi install for all dependencies).
• Consistency: Avoids version conflicts via centralized merging and resolution.
• No Duplication: Reuse sub-project dependencies/configurations in the main project without copying.

Potential Edge Cases & Solutions

• Version Conflicts: Clearly report version conflicts during merging with details on which sub-projects caused the conflict.
• Missing Sub-Project pixi.toml: Throw a clear error when an included path does not exist (or allow optional inclusions with a ! prefix, e.g., !./optional-subproject/pixi.toml).
• Nested Includes: Allow sub-projects to have their own includes field (for deep sub-modules) by resolving includes recursively (with a depth limit to prevent infinite loops).
• Sub-Project Specific Dependencies: The sub-project may have some dependencies that are not relevant to the main project; which should be placed beyond the default features in pixi.toml. We can add a new rule that only features defined in the main pixi.toml are considered for merging, while sub-project specific dependencies are ignored unless explicitly included.

Example Structure

1. Project Structure

main-project/
├── pixi.toml (main)
├── pixi.lock (generated for merged config)
├── packages/
│   ├── module-a/
│   │   └── pixi.toml (sub-project)
│   ├── module-b/
│   │   └── pixi.toml (sub-project)
|   └── module-c/
│       └── pixi.toml (sub-project)
├── tools/​
└── utils/

The above content was generated with ai assistance, with my review and edits.