Skip to content

Add a new recipe

  1. Pick a sibling recipe with a similar shape (CMake project? Header-only? Python package?) and copy its directory:

    cp -r recipes/random123 recipes/<new-pkg>

  2. Edit recipes/<new-pkg>/recipe.yaml:

  3. context.version — current upstream release.
  4. source.url — tarball URL (GitHub archive/refs/tags/, GitLab CERN archive, etc.). Use the same template variables as the surrounding recipes so Renovate can update it automatically.
  5. source.sha256 — curl -fsSL <url> | sha256sum.
  6. requirements.{build,host,run} — declare every sibling recipe this package depends on by name. rattler-build resolves the build order from these lists, so this is the only place to express ordering.
  7. tests: — at minimum a package_contents: block listing the headers / libs / CMake configs the build is expected to produce. For runtime-executable packages add a script: test that runs a Python import or root -l -q invocation.
  8. about: — populate homepage, repository, summary, description, license (SPDX), license_file.

  9. extra.recipe-maintainers: — your GitHub handle, plus at least one co-maintainer where possible.

  10. Adjust recipes/<new-pkg>/build.sh for the build system in use.

  11. From the repo root, dry-run the build locally:

    pixi run rattler-build build --recipe recipes/<new-pkg> \
    --channel https://prefix.dev/ship --channel conda-forge

  12. Open a PR. CI runs pixi run build-all (rattler-build build --recipe-dir recipes/ --skip-existing=all), which rebuilds every recipe whose dependencies changed. Uploads to prefix.dev/ship are gated on push to main.

  13. After merge, decide whether the recipe is an upstream candidate and update the table.

Notes

  • Recipe directory name must equal the package.name in recipe.yaml. rattler-build's cross-recipe dependency resolution keys off the name in requirements:.
  • Don't add the recipe to a separate manifest file — there isn't one. The requirements: block is the single source of truth for dependency order.

  • For a single-recipe local iteration, run the inline form:

    pixi run rattler-build build --recipe recipes/<new-pkg> \
    --channel https://prefix.dev/ship --channel conda-forge

or, for the recipe currently most under churn, the build-<name> pixi task shortcut.