Recipe Validation for modular-community

This guide explains how to validate your packaging/recipe.yaml locally before submitting to modular-community, ensuring it passes CI on the first try.

Why Validate Locally?

modular-community uses rattler-build to parse and build packages. Running the same validation locally catches schema errors before submission, saving time and iteration cycles.

Setup

Prerequisites

pixi - Package manager

curl -fsSL https://pixi.sh/install.sh | bash

rattler-build - Recipe builder (installed automatically by script)
```
pixi global install rattler-build
```

Validation Methods

Method 1: Local Script (Recommended)

Run the validation script from your package root:

./scripts/validate-recipe.sh packaging/recipe.yaml

This runs the exact same validation as modular-community CI in --render-only mode (no actual build).

Example output:

🔍 Validating packaging/recipe.yaml against modular-community schema...

🏗️  Running rattler-build validation...
✅ Recipe validation passed!

Your recipe file follows the modular-community schema.
It should pass CI when submitted.

Method 2: GitHub Actions (Automated)

The .github/workflows/validate-recipe.yml workflow runs automatically when you: - Push changes to packaging/recipe.yaml - Create a PR that modifies packaging/recipe.yaml

View results in the “Actions” tab of your repo.

Method 3: Manual rattler-build

For advanced users who want full control:

pixi exec rattler-build build \
    --recipe packaging/recipe.yaml \
    --channel conda-forge \
    --channel https://conda.modular.com/max \
    --channel https://prefix.dev/modular-community \
    --render-only

Common Schema Errors

❌ Wrong: Singular `test:`

test:
  commands:
    - test -f $PREFIX/lib/mojo/package/__init__.mojo

✅ Correct: Plural `tests:` with `script:`

tests:
  - script:
      - test -f $PREFIX/lib/mojo/package/__init__.mojo

❌ Wrong: `doc_url` and `dev_url`

about:
  doc_url: https://github.com/user/package/blob/main/README.md
  dev_url: https://github.com/user/package

✅ Correct: `documentation` and `repository`

about:
  documentation: https://github.com/user/package/blob/main/README.md
  repository: https://github.com/user/package

❌ Wrong: Missing `script:` in tests

tests:
  - commands:  # Should be 'script:'
      - test -f $PREFIX/lib/mojo/package/__init__.mojo

✅ Correct: Proper test structure

tests:
  - script:
      - test -f $PREFIX/lib/mojo/package/__init__.mojo

Integration with Your Workflow

Pre-commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: validate-recipe
        name: Validate packaging/recipe.yaml
        entry: ./scripts/validate-recipe.sh
        language: system
        files: ^packaging/recipe\.yaml$
        pass_filenames: false

Then install: pre-commit install

Just Recipe

Add to justfile:

# Validate packaging/recipe.yaml against modular-community schema
validate-recipe:
    ./scripts/validate-recipe.sh packaging/recipe.yaml

Usage: just validate-recipe

Pixi Task

Add to pixi.toml:

[tasks]
validate-recipe = "./scripts/validate-recipe.sh packaging/recipe.yaml"

Usage: pixi run validate-recipe

Troubleshooting

“pixi not found”

Install pixi: curl -fsSL https://pixi.sh/install.sh | bash

“rattler-build not found”

The script auto-installs it, or manually: pixi global install rattler-build

Recipe fails validation

Read the error output carefully - it tells you exactly which line/field is problematic. Common issues: - Field names (test vs tests, doc_url vs documentation) - Missing script: section - Incorrect YAML structure (indentation, list format)

Need more details?

Run with verbose output:

RATTLER_BUILD_LOG=debug ./scripts/validate-recipe.sh packaging/recipe.yaml