Package Source Configuration

Configure where your package source code is located

Learn how to specify package source locations using paths, git repositories, or URLs.

Default Behavior

By default, build backends look for source code in the directory containing the package manifest:

my_package/
├── pixi.toml          # Package manifest
├── src/               # Source code here
│   └── my_code.cpp
└── include/
    └── my_code.h

Build backends have reasonable defaults:

• pixi-build-cmake looks for CMakeLists.txt in the package directory
• pixi-build-python looks for pyproject.toml or setup.py in the package directory
• pixi-build-rust looks for Cargo.toml in the package directory

The exception is pixi-build-rattler-build, where you specify the source directly in recipe.yaml.

Using a Custom Path

If your source is in a different location, use package.build.source.path:

Subdirectory

my_package/
├── pixi.toml
└── source/            # Source in subdirectory
    ├── src/
    │   └── my_code.cpp
    └── include/
        └── my_code.h

pixi.toml

[package.build.source]
path = "source"

Relative Path

Source can be outside the package directory:

workspace/
├── packages/
│   └── my_package/
│       └── pixi.toml
└── shared_source/     # Shared source code
    └── src/

packages/my_package/pixi.toml

[package.build.source]
path = "../../shared_source"

Relative paths are resolved from the package manifest location.

Git Submodules

This works great with git submodules:

git submodule add https://github.com/user/library.git external/library

pixi.toml

[package.build.source]
path = "external/library"

Using Git Repositories

Build directly from git repositories:

Basic Git Source

pixi.toml

[package.build.source]
git = "https://github.com/user/repo.git"

Pixi clones the repository and builds from it.

Pinning to a Branch

pixi.toml

[package.build.source]
git = "https://github.com/user/repo.git"
branch = "main"

Always builds from the latest commit on the specified branch.

Using branches creates non-reproducible builds. Prefer tags or revisions for production.

Pinning to a Tag

pixi.toml

[package.build.source]
git = "https://github.com/user/repo.git"
tag = "v1.0.0"

Builds from a specific release tag - recommended for reproducibility.

Pinning to a Commit

pixi.toml

[package.build.source]
git = "https://github.com/user/repo.git"
rev = "abc123def456"

Builds from an exact commit hash - most reproducible option.

Git Subdirectory

If the package is in a subdirectory of the repository:

pixi.toml

[package.build.source]
git = "https://github.com/user/repo.git"
tag = "v1.0.0"
subdirectory = "packages/mypackage"

Common in monorepos:

repo/
├── packages/
│   ├── package-a/
│   │   └── pixi.toml
│   └── package-b/
│       └── pixi.toml
└── README.md

Complete Examples

SDL Example from Git

pixi.toml

[package.build.source]
git = "https://github.com/prefix-dev/pixi-build-testsuite.git"
subdirectory = "tests/data/pixi_build/cpp-with-path-to-source/project"

[package.build.backend]
channels = [
  "https://prefix.dev/pixi-build-backends",
  "https://prefix.dev/conda-forge",
]
name = "pixi-build-cmake"
version = "*"

[package]
name = "sdl_example"
version = "0.1.0"

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

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

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

Python Package with Custom Path

pixi.toml

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

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

[package]
name = "my_package"
version = "0.1.0"

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

[package.build.source]
path = "python_src"  # Source in python_src/ subdirectory

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

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

Multiple Packages from Different Sources

pixi.toml

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

[dependencies]
local_pkg = { path = "." }              # (1)!
vendor_lib = { path = "packages/vendor" } # (2)!
upstream = { path = "packages/upstream" } # (3)!

1. Local package in root directory
2. Vendored third-party library
3. Upstream package with custom source configuration

packages/upstream/pixi.toml

[package]
name = "upstream"
version = "2.5.0"

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

[package.build.source]
git = "https://github.com/upstream/project.git"
tag = "v2.5.0"

Source Configuration Patterns

Local Development

# Default - source in same directory as pixi.toml
# No [package.build.source] needed

Use Cases

Depending on unreleased changes

Use a git branch to depend on development versions:

[package.build.source]
git = "https://github.com/user/library.git"
branch = "feature/new-api"

Useful for:

• Testing unreleased features
• Contributing to upstream projects
• Coordinating changes across projects

Pinning to specific versions

Use tags for reproducible builds:

[package.build.source]
git = "https://github.com/user/library.git"
tag = "v1.2.3"

Best for:

• Production deployments
• Published packages
• Reproducible research

Monorepo packages

Build multiple packages from one repository:

# Package A
[package.build.source]
git = "https://github.com/org/monorepo.git"
subdirectory = "packages/package-a"

# Package B
[package.build.source]
git = "https://github.com/org/monorepo.git"
subdirectory = "packages/package-b"

Vendoring dependencies

Keep third-party sources in your repository:

# Add as git submodule
git submodule add https://github.com/vendor/lib.git vendor/lib

[package.build.source]
path = "vendor/lib"

Separate source and build configs

Keep build configuration separate from source:

project/
├── build-configs/
│   └── pixi.toml          # Build config
└── src/                     # Source code

[package.build.source]
path = "../src"

Authentication for Private Repositories

For private git repositories, use SSH or credentials:

SSH Keys

[package.build.source]
git = "[e-mail]:user/private-repo.git"
tag = "v1.0.0"

Ensure your SSH keys are configured:

ssh-add ~/.ssh/id_rsa

Git Credentials

Configure git credentials manager:

git config --global credential.helper store

Then use HTTPS URLs:

[package.build.source]
git = "https://github.com/user/private-repo.git"

Best Practices

Prefer tags over branches

For reproducibility:

# Good - reproducible
[package.build.source]
git = "https://github.com/user/repo.git"
tag = "v1.0.0"

# Risky - changes over time
[package.build.source]
git = "https://github.com/user/repo.git"
branch = "main"

Document source choices

Comment why you’re using a specific source:

# Using development branch until PR #123 is merged
[package.build.source]
git = "https://github.com/user/repo.git"
branch = "fix/critical-bug"

Keep source close to config

When possible, keep source and config together:

package/
├── pixi.toml
└── src/

Rather than:

project/
├── configs/pixi.toml
└── sources/my_pkg/

Use submodules for vendored deps

For vendored dependencies:

git submodule add https://github.com/vendor/lib.git vendor/lib

Better than copying source directly.

Source Configuration Reference

Path Source

[package.build.source]
path = "relative/or/absolute/path"

• Relative paths: From package manifest location
• Absolute paths: Full system paths (not recommended)
• Works with: All backends

Git Source

[package.build.source]
git = "https://github.com/user/repo.git"  # Required
branch = "main"                           # Optional
tag = "v1.0.0"                            # Optional (prefer over branch)
rev = "abc123"                            # Optional (most specific)
subdirectory = "path/in/repo"            # Optional

• git: Repository URL (HTTPS or SSH)
• branch: Branch name (changes over time)
• tag: Tag name (stable, recommended)
• rev: Commit hash (most specific)
• subdirectory: Path within repository

Only one of branch, tag, or rev can be specified. If none is given, uses the default branch.

Next Steps

Workspaces

Manage multiple packages with different sources

Build Backends

How backends locate and use source code

Getting Started

Complete build configuration guide

C++ Packages

Building C++ from custom sources

Troubleshooting

Source not found

Verify the path is correct relative to the manifest:

ls -la path/to/source  # From manifest directory

[package.build.source]
path = "./correct/relative/path"

Git clone fails

Check:

1. Repository URL is correct
2. Repository is accessible (public or authenticated)
3. Branch/tag/revision exists

# Test manually
git clone https://github.com/user/repo.git
git checkout v1.0.0

Subdirectory not found

Ensure the subdirectory exists at the specified location:

# Clone and check
git clone https://github.com/user/repo.git
ls -la repo/packages/mypackage

[package.build.source]
git = "https://github.com/user/repo.git"
subdirectory = "packages/mypackage"  # Must exist!

Build can't find source files

Backends look for specific files:

• cmake: CMakeLists.txt
• python: pyproject.toml or setup.py
• rust: Cargo.toml

Ensure these exist in the source location.