Skip to content

Getting started

Introduction#

Next to managing workflows and environments, pixi can also build packages. This is useful for the following reasons:

  • Building and uploading a package to a conda channel
  • Allowing users to directly depend on the source and build it automatically
  • Managing multiple packages in a workspace

We've been working to support these use-cases with the build feature in pixi. The vision is to enable building of packages from source, for any language, on any platform.

Known limitations

Currently, the build feature has a number of limitations:

  1. Limited set of build-backends.
  2. Build-backends are probably missing a lot of parameters/features.
  3. Recursive source dependencies are not supported. ( source dependencies that have source dependencies )
  4. Workspace dependencies cannot be inherited.

Setting up the Manifest#

This is an overview of the pixi manifest using pixi-build.

pixi.toml
# Specifies properties for the whole workspace
[workspace]
preview = ["pixi-build"]
channels = ["https://prefix.dev/conda-forge"]
platforms = ["win-64", "linux-64", "osx-arm64", "osx-64"]

# There can be multiple packages in a workspace
# In `package` you specify properties specific to the package
[package]
name = "simple_python"
version = "0.1.0"

# Here the build system of the package is specified
# We are using `pixi-build-python` in order to build a Python package
[package.build]
backend = { name = "pixi-build-python", version = "0.1.*" }
channels = [
  "https://prefix.dev/pixi-build-backends",
  "https://prefix.dev/conda-forge",
]


# The Python package `simple_python` uses `hatchling` as Python build backend
[package.host-dependencies]
hatchling = "*"

# We add our package as dependency to the workspace
[dependencies]
simple_python = { path = "." }
# pixi also support git dependencies
boost-check = { git = "https://github.com/wolfv/pixi-build-examples", branch = "main", subdirectory = "boost-check" }

[package.run-dependencies]
rich = ">=13.9.4,<14"

Under the [workspace] section, you can specify properties like the name, channels, and platforms. This is currently an alias for project.

Since the build feature is still in preview, you have to add "pixi-build" to workspace.preview.

[workspace]
preview = ["pixi-build"]

In package you specify properties specific to the package you want to build.

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

Packages are built by using build backends. By specifying package.build-system.build-backend and package.build-system.channels you determine which backend is used and from which channel it will be downloaded. There are different build backends. Pixi backends can describe how to build a conda package, for a certain language or build tool. In this example, we are using pixi-build-python backend in order to build a Python package.

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

We need to add our package simple_python as dependency to the workspace.

pixi also supports git dependencies, allowing you to specify a branch, tag, or rev to pin the dependency. If none are specified, the latest commit on the default branch is used. The subdirectory is optional and specifies the location of the package within the repository.

# We add our package as dependency to the workspace
[dependencies]
simple_python = { path = "." }
# pixi also support git dependencies
boost-check = { git = "https://github.com/wolfv/pixi-build-examples", branch = "main", subdirectory = "boost-check" }

simple_python uses hatchling as Python build backend, so this needs to be mentioned in host-dependencies.

Python PEP517 backends like hatchling know how to build a Python package. So hatchling creates a Python package, and pixi-build-python turns the Python package into a conda package.

Read up on host-dependencies in the dependency types chapter

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

We add rich as a run dependency to the package. This is necessary because the package uses rich during runtime. You can read up on run-dependencies in the dependency types chapter

[package.run-dependencies]
rich = ">=13.9.4,<14"

CLI Commands#

Using the preview feature you can now build packages from source.

  • pixi build has been added and will build a .conda file out of your package.
  • Other commands like pixi install and pixi run automatically make use of the build feature when a path, git or url dependency is present.