Package Source Configuration

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)!

Local package in root directory
Vendored third-party library
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

# 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 = "git@github.com: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:

Repository URL is correct
Repository is accessible (public or authenticated)
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.

Get Started

Core Concepts

Tutorials

Building Packages

Distribution

Integration

Advanced

Package Source Configuration

Default Behavior

Using a Custom Path

Subdirectory

Relative Path

Git Submodules

Using Git Repositories

Basic Git Source

Pinning to a Branch

Pinning to a Tag

Pinning to a Commit

Git Subdirectory

Complete Examples

SDL Example from Git

Python Package with Custom Path

Multiple Packages from Different Sources

Source Configuration Patterns

Use Cases

Authentication for Private Repositories

SSH Keys

Git Credentials

Best Practices

Source Configuration Reference

Path Source

Git Source

Next Steps

Workspaces

Build Backends

Getting Started

C++ Packages

Troubleshooting

Get Started

Core Concepts

Tutorials

Building Packages

Distribution

Integration

Advanced

​Default Behavior

​Using a Custom Path

​Subdirectory

​Relative Path

​Git Submodules

​Using Git Repositories

​Basic Git Source

​Pinning to a Branch

​Pinning to a Tag

​Pinning to a Commit

​Git Subdirectory

​Complete Examples

​SDL Example from Git

​Python Package with Custom Path

​Multiple Packages from Different Sources

​Source Configuration Patterns

​Use Cases

​Authentication for Private Repositories

​SSH Keys

​Git Credentials

​Best Practices

​Source Configuration Reference

​Path Source

​Git Source

​Next Steps

Workspaces

Build Backends

Getting Started

C++ Packages

​Troubleshooting

Default Behavior

Using a Custom Path

Subdirectory

Relative Path

Git Submodules

Using Git Repositories

Basic Git Source

Pinning to a Branch

Pinning to a Tag

Pinning to a Commit

Git Subdirectory

Complete Examples

SDL Example from Git

Python Package with Custom Path

Multiple Packages from Different Sources

Source Configuration Patterns

Use Cases

Authentication for Private Repositories

SSH Keys

Git Credentials

Best Practices

Source Configuration Reference

Path Source

Git Source

Next Steps

Troubleshooting