Multi-Package Workspaces

Develop multiple interdependent packages in a single Pixi workspace

Learn how to manage multiple packages within a single workspace, enabling local development of interdependent libraries.

pixi-build is a preview feature and will change until stabilized. Keep this in mind when using it for your projects.

Why Use Workspaces?

Workspaces solve several development challenges:

• Local development - Work on multiple packages simultaneously
• Source dependencies - Depend on unreleased versions
• Monorepo support - Manage related packages in one repository
• Cross-language projects - Mix Python, C++, Rust, and more
• Shared configuration - Common channels, platforms, and settings

Normally, conda packages come pre-built from channels. Workspaces let you depend on the source code directly, which is built automatically as needed.

Creating a Multi-Package Workspace

Workspace Patterns

Python-Only Workspace

Multiple Python packages:

pixi.toml

[workspace]
channels = [
  "https://prefix.dev/pixi-build-backends",
  "https://prefix.dev/conda-forge",
]
name = "recursive-run-deps"
platforms = ["win-64", "osx-arm64", "linux-64"]
preview = ["pixi-build"]

[dependencies]
root = { path = "src/root" }

[tasks]
start = "python -c 'import root'"
test = [{ task = "start" }]

With sub-packages:

src/root/pyproject.toml

[project]
name = "root"
version = "0.1.0"
dependencies = ["depend"]
requires-python = ">= 3.11"

[build-system]
build-backend = "hatchling.build"
requires = ["hatchling"]

[tool.pixi.package.build]
backend = { name = "pixi-build-python", version = "0.4.*" }

[tool.pixi.package.host-dependencies]
hatchling = ">=1.27,<2.0"

[tool.pixi.package.run-dependencies]
depend = { path = "../depend" }  # (1)!

1. Depend on another package in the workspace

src/depend/pyproject.toml

[project]
name = "depend"
version = "0.1.0"
requires-python = ">= 3.11"

[build-system]
build-backend = "hatchling.build"
requires = ["hatchling"]

[tool.pixi.package.build]
backend = { name = "pixi-build-python", version = "0.4.*" }

[tool.pixi.package.host-dependencies]
hatchling = ">=1.27,<2.0"

[tool.pixi.package.run-dependencies]
boltons = "*"  # (2)!

2. External conda dependencies

Workspace with Dev Dependencies

Use [dev] instead of [dependencies] to install only build-time dependencies:

pixi.toml

[workspace]
channels = [
  "https://prefix.dev/pixi-build-backends",
  "https://prefix.dev/conda-forge",
]
platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]
preview = ["pixi-build"]

[tasks]
start = "cmake --version && python -VV && bat --version"
test = [{ task = "start" }]

[dev]  # (1)!
minimal-example = { path = "." }

[package]
name = "minimal-example"
version = "0.1.0"

[package.build.backend]
name = "pixi-build-cmake"
version = "0.3.*"

[package.build-dependencies]
cmake = ">=3.27.8,<4.0"

[package.host-dependencies]
python = ">=3.12.4,<4"
sdl2 = ">=2.26.5,<3.0"

[package.run-dependencies]
bat = "*"

1. [dev] installs build and host dependencies but not the package itself

When to use [dev] vs [dependencies]?

Use [dependencies] when:

• You want the built package installed in the environment
• You’re creating a library for others to use
• You need to test the installed package

Use [dev] when:

• You only need build-time dependencies
• You’re developing the package and don’t need it installed
• You want faster iteration without package installation

Complete Workspace Example

Here’s the C++ package configuration:

packages/cpp_math/CMakeLists.txt

cmake_minimum_required(VERSION 3.20...3.27)
project(cpp_math)

find_package(Python 3.8 COMPONENTS Interpreter Development.Module REQUIRED)

execute_process(
  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
  OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT
)

execute_process(
    COMMAND ${Python_EXECUTABLE} -c "import sysconfig; print(sysconfig.get_path('purelib'))"
    OUTPUT_VARIABLE PYTHON_SITE_PACKAGES
    OUTPUT_STRIP_TRAILING_WHITESPACE
)

find_package(nanobind CONFIG REQUIRED)

nanobind_add_module(${PROJECT_NAME} src/math.cpp)

install(
    TARGETS ${PROJECT_NAME}
    EXPORT ${PROJECT_NAME}Targets
    LIBRARY DESTINATION ${PYTHON_SITE_PACKAGES}
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${BINDIR}
)

packages/cpp_math/src/math.cpp

#include <nanobind/nanobind.h>

int add(int a, int b) { return a + b; }

NB_MODULE(cpp_math, m)
{
    m.def("add", &add);
}

Workspace Commands

Install All Packages

pixi install

Advanced Workspace Configuration

Multiple Workspace Packages

You can have multiple packages at the root level:

workspace/
├── pixi.toml              # Workspace configuration only
├── packages/
│   ├── package-a/
│   │   └── pixi.toml
│   ├── package-b/
│   │   └── pixi.toml
│   └── package-c/
│       └── pyproject.toml  # With [tool.pixi.package]

pixi.toml

[workspace]
channels = ["https://prefix.dev/conda-forge"]
platforms = ["linux-64", "osx-arm64", "win-64"]
preview = ["pixi-build"]

[dependencies]
package-a = { path = "packages/package-a" }
package-b = { path = "packages/package-b" }
package-c = { path = "packages/package-c" }

Workspace with Variants

Build packages against multiple versions:

pixi.toml

[workspace]
channels = ["https://prefix.dev/conda-forge"]
platforms = ["osx-arm64", "osx-64", "linux-64", "win-64"]
preview = ["pixi-build"]

[workspace.build-variants]  # (1)!
python = ["3.11.*", "3.12.*"]

[dependencies]
python_rich = { path = "." }

[feature.py311.dependencies]
python = "3.11.*"

[feature.py312.dependencies]
python = "3.12.*"

[environments]  # (2)!
py311 = ["py311"]
py312 = ["py312"]

1. Define allowed Python versions
2. Create environments for each variant

See the variants guide for details.

Best Practices

Organize packages logically

Group related packages:

workspace/
├── pixi.toml
├── libs/              # Shared libraries
│   ├── core/
│   └── utils/
├── services/          # Applications
│   ├── api/
│   └── worker/
└── tools/             # Development tools

Use consistent versions

Keep package versions synchronized:

[workspace]
version = "0.1.0"  # Shared version

[package]
version = "0.1.0"  # Same as workspace

Minimize workspace configuration

Keep sub-packages minimal - they inherit from the workspace:

packages/subpkg/pixi.toml

# Just package-specific config
[package]
name = "subpkg"
version = "0.1.0"

[package.build]
backend = { name = "pixi-build-cmake", version = "0.3.*" }

[package.host-dependencies]
sdl2 = "*"

Document dependencies

Comment why packages depend on each other:

[package.run-dependencies]
# Needed for fast numerical operations
core_math = { path = "../core_math" }
# UI components
ui_toolkit = { path = "../ui_toolkit" }

Next Steps

Build Variants

Build against multiple dependency versions

Dependency Types

Understand build, host, and run dependencies

Package Sources

Use git, path, or URL sources

Python Packages

Build Python packages in workspaces

Troubleshooting

Package not found

Ensure the path is correct relative to the workspace root:

[dependencies]
my_package = { path = "./packages/my_package" }  # Relative to workspace root

Circular dependencies

Pixi doesn’t support circular dependencies between packages. Restructure to have a clear dependency hierarchy.

Build order issues

Pixi automatically determines build order based on dependencies. If builds fail, check that all dependencies are properly declared.

Workspace settings not inherited

Only packages within the same workspace root inherit settings. External path dependencies don’t inherit workspace configuration.