Pixi is a modern package manager built on top of the conda ecosystem. It provides reproducible environments consisting of cross-platform packages for any language.
Normally, development tooling and package publishing live in separate worlds: you use one workflow to build and test your software locally, and a completely different one to publish it. Wouldn't it be great to use the same manifest that describes your project environment to also define how the package is built, versioned, and released?
Pixi-build is solution to this problem. It lets you describe how your software should be built directly in the manifest and uses a backend to turn that description into a full package recipe. This means you can develop, test, and publish from the same project without rewriting metadata or juggling multiple tools.
Backends are standalone servers that implement the actual build process and communicate with Pixi over a simple JSON-RPC protocol. This design makes Pixi extensible: any language ecosystem can define its own build rules without changing Pixi itself.
Pixi-build
Recipe generation
Usually, recipes are written manually and built using a program like rattler-build. If you’ve ever written a package recipe — of any kind — you’ve probably noticed how repetitive they can be.
Every C++ package that uses CMake looks roughly like this — same compilers, same build script, same boilerplate:
And if you want to write recipes for several packages, it gets even more cumbersome and tedious. For each recipe, you have to manually copy this structure, modify parameters, and if you plan to share it — submit it for a review to conda-forge.
A natural reaction is to introduce templates for common ecosystems such as CMake, Rust, or Python. That helps, but you still end up editing variables by hand.
A more ambitious solution is a recipe generator that fills in defaults automatically from project metadata. This reduces work, yet you still need to maintain the generated files themselves.
Pixi-build backend solves the final step. Instead of dozens of recipes, you maintain one backend capable of generating them on demand. The same tool can build both your internal and external packages, simplifying the development process. That’s what pixi-build does.
Showcase
Let’s take a look at our sample package from above and how it would be written using pixi-build. We will use the pixi-build-cmake backend that encodes best practices to build CMake packages. With it, our definition shrinks down to just following the pixi.toml content in the root directory of the corresponding project repository.
Pretty neat, isn’t it? Our backend is responsible for discovering package name, version and other metadata required for a top-notch package. Though, it still may require some assistance since we can not necessarily find all metadata or dependencies required for building and running our program. Let’s say that we want to compile small C++ program that uses SDL2. We have to add it manually. This can be done by adding the following to our manifest:
Not only this, but we can also depend on those packages from source. It is as simple as adding the following source dependency
to your dependencies table.
This will make it compile successfully. You can find a more in-depth overview of building your package from this awesome blog post from Ruben.
Nowadays you can also have a pixi-build package that depends on a package that again depends on package and so on like in the example above! This is called a recursive source dependency in the documentation.
Why and how write your own backend?
The short answer: if you need to package "typical" software and want to do less, then pixi-build backends are for you! Now let's focus on the more interesting part — writing your own backend.
First of all, you should check out our documentation for pixi-build backends to see if we already have a backend for your use-case. If not, then now I'll teach you how to easily write your own backend using Python.
We will be more specific from now on and write a build backend. On today's menu: the Go programming language!
Note: Most of the backends that we currently have are written in Rust and very similar in structure to what we will do in Python. You can compare implementation difference yourself as pixi-build-go repository contains both Rust and Python versions. Find a link in the exercises sections.
Writing a backend
A backend consists of two components:
A server that will accept and respond to JSON-RPC requests from Pixi.
A generator of the recipe that will create rattler-build recipe based on the package configuration and source directory.
And that's it! Thankfully, we already implemented all server logic for you, so your task is only to implement the recipe generator.
Creating a project
Start by creating a new Python project using Pixi and adding the dependencies:
We're eating our own dog food, so we will use pixi-build-python to build our backend:
The generator is defined in Python by creating a class that inherits from GenerateRecipeProtocol. It is responsible for converting a project model into an intermediate recipe, which will be used for the build. You can think of the intermediate recipe as a regular rattler-build recipe that you write by hand.
Structure of recipe generation
The main method of the generator is generate_recipe, which accepts all information that you might need to generate a recipe. We will focus only on this method, but don't forget to provide blank implementations for other methods.
The implementation of generate_recipe method typically consists of the following steps:
Initialize a metadata provider. This structure scans source code to obtain project metadata. It is responsible for automatic filling of the fields name, version, license, license_file, repository, etc. For the full list of values it provides, check out the MetadataProvider class definition.
Generate the skeleton of the recipe from the project model and metadata provider. This can be achieved by calling the GeneratedRecipe.from_model method.
Add dependencies. This part consists of resolving dependencies from the project model (they can be target-specific); adding compilers, standard libraries and custom dependencies.
Create the build script. Here we have to render and assign rendered script string to the recipe. The content must be valid cmd.exe code on Windows and valid bash code on UNIX systems correspondingly.
Return the generated recipe.
Process may slightly vary depending on complexity of your backend, but this is a good starting point.
Now, let's go through the process in chronological order.
Implementation
We start by creating the metadata provider. We will provide only a blank implementation for now and return to field discovery later.
It looks like this:
Another important component is a configuration that we parse from the manifest package description. Therefore, we declare it as follows:
We return to our generator and generate a skeleton of our recipe from the project model
This generated recipe doesn't contain any dependencies yet, let's add the compiler. First, we obtain the requirements section of the recipe and then resolve them. We do this to get the dependencies specified in the manifest file in place. After that, we add the compilers to the requirements.
After specifying dependencies, we have to get build script. As stated above, the build script is platform native shell code — bash on UNIX platforms and cmd.exe on windows. To dynamically generate those scripts and avoid as much boilerplate as possible, we will use jinja2 template engine. We define BuildScriptContext and implement the render function as follows:
We will show only build_script.j2, all missing names should be self-evident:
The only thing that is remaining is to update generate_recipe to call rendering in the generator, return our recipe and we're done!
And that's it! We have a simple working build backend at our hands. Let's proceed to testing it.
Testing our backend
Let's look at a couple of cherry-picked examples and assume that it will work for different packages! For the sake of simplicity, we will focus only on CLI programs, but theoretically nothing stops us from building graphical applications.
Initial trials
We start with picking the simplest possible program that matches our current build script and on which I looked when I was writing it. Gojq is a rewrite of the famous jq program in Go. Its main features are:
Statically linked,
Arbitrary precision arithmetic,
Support of yaml files.
Start by globally installing pixi-build-go: change your directory to its root directory (where pixi.toml at), then run
similar to cargo install --path . to install backend globally. We needed this to try it out hassle-free.
Clone gojq repository locally and put this pixi.toml in it
Now we run
and then
Success! But let's try something different. Now I want to measure how productive I was. The ideal tool for solving my problem is scc — a line counter program that also outputs some (maybe) useful statistics.
We clone scc repository and put a similar pixi.toml with the following difference
Then run pixi build and… hit an error! We only support the main module at ./cmd/${PKG_NAME}. That is not the case for scc, which has its main module at the root directory of its repository. Let's tweak the backend to support this (quite common) case as well.
Improving metadata discovery
Start by imagining how we should tweak the recipe build script to match our expectations. It should look something like this:
So we somehow have to obtain a path for the main_package. We extend BuildScriptContext with this field and then add a simple function to the metadata provider to obtain it.
Logic is pretty simple — we check if ./cmd/${PKG_NAME} contains main module and fallback to the current directory otherwise.
Notice that we've used self.name(). Since we need the package name to obtain correct path, let's also provide simple name discovery. We will implement a simplest possible logic and just use the name of the directory where the manifest at, as the name of our package. Extend MetadataProvider constructor to store project root and implement our method
Now we initialize BuildScriptContext with
and go back to scc.
Testing-out improved version
Now we try to build scc again, and this time we again get total success!
For the sake of completeness, let's also try fzf. We clone repository, add our typical pixi.toml without package.name field (only with version), run pixi build and
obtain total satisfaction!
Exercises
You can't learn something well without doing exercises, so here are a few ideas for you to experiment and improve this backend. All sources can be found in the pixi-build-go repository.
Currently, we don't specify license type and license file. Extend metadata provider to discover both automatically.
Add proper error handling for metadata extractor. Now it doesn't give proper errors on tools failure from the previous exercise, for example.
Add support for specifying which binary we want to build in the manifest.
Add support for Cgo packages.
Conclusion
At this point you have a minimal backend that can receive build requests from Pixi, translate them into rattler-build recipes, and return the results. From here, the possibilities open up quickly.
You can encode best practices for your language ecosystem (compilers, flags, layout conventions).
You can integrate external metadata sources.
You can experiment with hybrid builds that combine Python, C++, or Rust code in one project.
In short, pixi-build turns repetitive packaging work into a programmable layer. Instead of writing and maintaining dozens of recipes, you write logic once and reuse it everywhere.
requirements = generated_recipe.recipe.requirementsresolved_build = requirements.resolve(host_platform).buildcompilers = config_model.compilers or ["go-nocgo"]for language in compilers: language_compiler = _default_compiler(host_platform, language) if language_compiler in resolved_build: continue requirements.build.append(ItemPackageDependency(f"${{{{ compiler('{language}') }}}}"))
$ pixi exec -s $(pwd)/gojq-0.12.17-hbf21a9e_0.conda gojq --helpgojq - Go implementation of jqVersion: 0.12.17 (rev: HEAD/go1.25.3)Synopsis: % echo '{"foo": 128}' | gojq '.foo'Usage: gojq [OPTIONS]Command Options: -r, --raw-output output raw strings --raw-output0 implies -r with NUL character delimiter -j, --join-output implies -r with no newline delimiter -c, --compact-output output without pretty-printing --indent number number of spaces for indentation --tab use tabs for indentation --yaml-output output in YAML format -C, --color-output output with colors even if piped -M, --monochrome-output output without colors -n, --null-input use null as input value -R, --raw-input read input as raw strings --stream parse input in stream fashion --yaml-input read input as YAML format -s, --slurp read all inputs into an array -f, --from-file load query from file -L, --library-path dir directory to search modules from --arg name value set a string value to a variable --argjson name value set a JSON value to a variable --slurpfile name file set the JSON contents of a file to a variable --rawfile name file set the contents of a file to a variable --args consume remaining arguments as positional string values --jsonargs consume remaining arguments as positional JSON values -e, --exit-status exit 1 when the last value is false or null -v, --version display version informationHelp Option: -h, --help display this help information
:focal(smart))
