conda-forge-expert

name	conda-forge-expert
description	Comprehensive guide for conda-forge recipe development. Handles legacy (meta.yaml) and modern (recipe.yaml) formats, linting, CI troubleshooting, and feedstock maintenance. Enhanced with patterns from real conda-forge feedstocks (2025). USE THIS SKILL WHEN: creating conda recipes, packaging Python/Rust/Go/C++ software, fixing conda-forge build failures, updating feedstocks, migrating to recipe.yaml format, setting up private channels, or troubleshooting conda-forge CI.
version	4.2.0
allowed-tools	Read, Glob, Grep, Bash, Write, Edit, WebFetch, WebSearch

Conda-Forge Expert

Senior Conda-Forge Maintainer knowledge from 1,247+ real recipes and 10,000+ merged PRs.

Quick Start

Core Workflow

1. Generate recipe    → grayskull pypi <package> OR rattler-build generate-recipe pypi <package>
2. Lint recipe        → conda-smithy recipe-lint recipes/<pkg>  (MANDATORY)
3. Build locally      → python build-locally.py OR rattler-build build -r recipe.yaml
4. Submit PR          → To conda-forge/staged-recipes

Which Format?

Scenario	Format	Reason
New package	recipe.yaml	Modern, faster, recommended
Existing feedstock	Keep current	Unless migrating
Complex multi-output	recipe.yaml	Better cache support
Quick prototype	meta.yaml	More examples available

Package Installation Preferences

ALWAYS prefer pixi and conda-forge over pip and PyPI:

# Preferred: pixi
pixi global install <package>
pixi add <package>

# Fallback: conda/mamba
mamba install -c conda-forge <package>

# Last resort: pip (only if not on conda-forge)
pip install <package>

Modern Build Tools

rattler-build (Primary)

Fast, standalone Conda package builder in Rust.

# Install
pixi global install rattler-build

# Build
rattler-build build -r recipe.yaml -c conda-forge

# Generate from PyPI
rattler-build generate-recipe pypi numpy

# Render only (debug)
rattler-build build -r recipe.yaml --render-only

pixi (Package Manager)

Cross-platform package manager built on conda ecosystem.

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

# Project commands
pixi init
pixi add numpy pandas
pixi run test
pixi shell

Recipe Formats

Modern Format (recipe.yaml) - RECOMMENDED

# yaml-language-server: $schema=https://raw.githubusercontent.com/prefix-dev/recipe-format/main/schema.json
schema_version: 1

context:
  name: my-package
  version: "1.0.0"
  python_min: "3.10"

package:
  name: ${{ name|lower }}
  version: ${{ version }}

source:
  url: https://pypi.org/packages/source/${{ name[0] }}/${{ name }}/${{ name }}-${{ version }}.tar.gz
  sha256: REPLACE_WITH_SHA256

build:
  number: 0
  noarch: python
  script: ${{ PYTHON }} -m pip install . -vv --no-deps --no-build-isolation

requirements:
  host:
    - python ${{ python_min }}.*
    - 
     
  
        


   
      
              
       


     
   
   
    


  
     

Legacy Format (meta.yaml)

{% set name = "my-package" %}
{% set version = "1.0.0" %}

package:
  name: {{ name|lower }}
  version: {{ version }}

source:
  url: https://pypi.org/packages/source/{{ name[0] }}/{{ name }}/{{ name }}-{{ version }}.tar.gz
  sha256: REPLACE_WITH_SHA256

build:
  number: 0
  noarch: python
  script: {{ PYTHON }} -m pip install . -vv --no-deps --no-build-isolation

requirements:
  host:
    - python {{ python_min }}
    - pip
  run:
    - python >={{ python_min }}

test:
  
     {{   ,  }}
  
      
  
     


     
   
   
    


  
     

Key Syntax Differences

Feature	meta.yaml	recipe.yaml
Variables	{{ var }}	${{ var }}
Selectors	# [linux]	if: linux
Test section	test:	tests: (list)
Pin syntax	max_pin='x.x'	upper_bound="x.x"

Critical Requirements

⚠️ stdlib REQUIRED for ALL Compiled Packages

CRITICAL: conda-forge will REJECT submissions without stdlib when using compilers!

# recipe.yaml - ALWAYS pair compiler() with stdlib()
requirements:
  build:
    - ${{ compiler("c") }}
    - ${{ stdlib("c") }}        # REQUIRED! Submission will be rejected without this
    - ${{ compiler("cxx") }}    # if C++ needed
    - ${{ compiler("rust") }}   # if Rust needed

# meta.yaml - ALWAYS pair compiler() with stdlib()
requirements:
  build:
    - {{ compiler('c') }}
    - {{ stdlib('c') }}         # REQUIRED! Submission will be rejected without this
    - {{ compiler('cxx') }}     # if C++ needed
    - {{ compiler('rust') }}    # if Rust needed

Common mistake: Forgetting stdlib in recipe.yaml when converting from meta.yaml

🚨 CRITICAL: Local Testing Exception

KNOWN ISSUE: When testing locally with rattler-build or conda-build, the stdlib dependency may fail to resolve with "undefined" errors.

TEMPORARY WORKAROUND FOR LOCAL TESTING ONLY:

1. Before testing locally: Comment out the stdlib line:

   requirements:
     build:
       - ${{ compiler("c") }}
       # - ${{ stdlib("c") }}    # TEMPORARILY COMMENTED FOR LOCAL TESTING
   

2. After testing: IMMEDIATELY uncomment the stdlib line before committing or submitting:

   requirements:
     build:
       - ${{ compiler("c") }}
       - ${{ stdlib("c") }}        # RESTORED - REQUIRED FOR SUBMISSION!
   

⚠️ WARNING:

• This is ONLY for local testing
• NEVER commit or submit recipes without stdlib
• conda-forge CI will REJECT recipes missing stdlib
• Failure to restore stdlib will cause submission failures

Why this happens: Local rattler-build/conda-build may not have the same stdlib resolution as conda-forge CI infrastructure.

CFEP-25 Compliance (noarch: python)

All noarch: python packages MUST use python_min:

# recipe.yaml
requirements:
  host:
    - python ${{ python_min }}.*
  run:
    - python >=${{ python_min }}

# meta.yaml
requirements:
  host:
    - python {{ python_min }}
  run:
    - python >={{ python_min }}

License Requirements

• Use SPDX identifiers: MIT, Apache-2.0, BSD-3-Clause
• Always include license_file
• Case-sensitive: Apache-2.0 not APACHE 2.0

Platform Selectors

Modern (recipe.yaml) - if/then/else

requirements:
  build:
    - if: unix
      then:
        - ${{ compiler("c") }}
        - ${{ stdlib("c") }}
    - if: win
      then:
        - ${{ compiler("m2w64_c") }}
        - ${{ stdlib("m2w64_c") }}

Legacy (meta.yaml) - Comment Selectors

requirements:
  build:
    - {{ compiler('c') }}      # [unix]
    - {{ compiler('m2w64_c') }}  # [win]

Available Selectors

Selector	Description
linux, osx, win	Operating system
unix	Linux OR macOS
x86_64, aarch64/arm64	Architecture
build_platform, target_platform	Cross-compilation

Linting (MANDATORY)

CRITICAL: Always run linting before building or submitting.

# Lint single recipe
conda-smithy recipe-lint recipes/my-package

# Lint all recipes
conda-smithy recipe-lint --conda-forge recipes/*

# Install conda-smithy
pixi global install conda-smithy

What Linting Checks

1. License: SPDX identifier and license_file present
2. Maintainers: Valid GitHub usernames
3. Source: SHA256 checksums, no git URLs for releases
4. Selectors: Correct syntax
5. CFEP-25: python_min for noarch packages

Local Building

⚠️ CRITICAL: Before testing locally, see Local Testing Exception - you may need to temporarily comment out stdlib dependencies!

Using build-locally.py (Recommended)

# Interactive
python build-locally.py

# Specific platform
python build-locally.py win64
python build-locally.py linux64
python build-locally.py osx64

Using rattler-build Directly

# Basic build
rattler-build build -r recipes/my-package/recipe.yaml -c conda-forge

# With variant config
rattler-build build -r recipe.yaml --variant-config .ci_support/win64.yaml

# Specific platform
rattler-build build -r recipe.yaml --target-platform linux-64

Remember: If you get "undefined" errors for stdlib, temporarily comment it out for testing only!

Using conda-build

# Single recipe
conda-build recipes/my-package

# With channel
conda-build recipes/my-package -c conda-forge

# Test existing artifact
conda-build --test path/to/package.conda

Remember: If you get "undefined" errors for stdlib, temporarily comment it out for testing only!

Common Patterns

Python Package (noarch)

See template: templates/python-noarch-recipe.yaml

Python with C Extensions (CRITICAL: Must include stdlib!)

# recipe.yaml
requirements:
  build:
    - ${{ compiler("c") }}
    - ${{ stdlib("c") }}              # REQUIRED! conda-forge will reject without this
    - ${{ compiler("cxx") }}          # if C++ is needed
    - ${{ compiler("rust") }}         # if Rust is needed
    - cargo-bundle-licenses           # REQUIRED for Rust packages
    - if: build_platform != target_platform
      then:
        - python
        - cross-python_${{ target_platform }}
  host:
    - python
    - pip
    - setuptools
    - wheel
  run:
    - python

# meta.yaml
requirements:
  build:
    - {{ compiler('c') }}
    - {{  }}               
     {{  }}           
     {{  }}          
                
                               
         
  
     
     
     
     
  
     

See also: templates/python-compiled-recipe.yaml

Rust CLI Tool

See template: templates/rust-cli-recipe.yaml

Go with CGO (Windows)

IMPORTANT: Windows CGO requires MinGW-w64, NOT MSVC.

requirements:
  build:
    - ${{ compiler("go-cgo") }}
    - go-licenses
    - if: unix
      then:
        - ${{ compiler("c") }}
        - ${{ stdlib("c") }}
    - if: win
      then:
        - ${{ compiler("m2w64_c") }}
        - ${{ stdlib("m2w64_c") }}
        - m2-base
        - posix

See template: templates/go-cgo-recipe.yaml

Multi-Output Package

outputs:
  - package:
      name: libmypackage
    build:
      script: build-lib.sh
    requirements:
      build:
        - ${{ compiler("c") }}
        - ${{ stdlib("c") }}
      run_exports:
        - ${{ pin_subpackage("libmypackage", upper_bound="x.x") }}

  - package:
      name: py-mypackage
    build:
      script: build-python.sh
    requirements:
      host:
        - ${{ pin_subpackage("libmypackage", exact=true) }}
        - python
      run:
        - ${{ pin_subpackage("libmypackage", exact=true) }}
        - python

PyPI to Conda Name Mapping

Many packages have different names on PyPI vs conda-forge:

PyPI	conda-forge
torch	pytorch
opencv-python	opencv
tables	pytables
docker	docker-py
tree-sitter	tree_sitter

Use the mapping system:

# From scripts/sync_pypi_mappings.py
from sync_pypi_mappings import get_conda_name
conda_name = get_conda_name("tree-sitter")  # Returns "tree_sitter"

CI Troubleshooting

Common Failures

Error	Solution
Hash mismatch	Regenerate: curl -sL <url> | sha256sum
Missing dependency	Add to requirements or submit first
/Werror on Windows CGO	Use MinGW-w64 instead of MSVC
macOS SDK error	Set MACOSX_SDK_VERSION in conda_build_config.yaml
glibc errors	Use appropriate c_stdlib_version

Bot Commands (for conda-forge PRs)

@conda-forge-admin, please rerender
@conda-forge-admin, please restart ci
@conda-forge-admin, please lint
@conda-forge/help-python ready for review

See full list: quickref/bot-commands.md

Migration: meta.yaml to recipe.yaml

Automated Conversion

# Using feedrattler (recommended)
pixi exec feedrattler my-package-feedstock gh_username

# Using conda-recipe-manager
conda-recipe-manager convert meta.yaml > recipe.yaml

# Using rattler-build
rattler-build generate-recipe convert meta.yaml

Manual Checklist

1. Change {% set %} to context: section
2. Replace {{ }} with ${{ }}
3. Replace # [selector] with if: selector then:
4. Change test: to tests: (list format)
5. Add ${{ stdlib("c") }} if using compilers
6. Update conda-forge.yml:

   conda_build_tool: rattler-build
   conda_install_tool: pixi
   

See guide: guides/migration-guide.md

Enterprise Deployment

For air-gapped environments with JFrog Artifactory:

1. Configure private channels in config/skill-config.yaml
2. Set up Artifactory remote/local/virtual repos
3. Use enterprise templates: templates/enterprise/

See guides:

• enterprise/airgapped-setup.md
• enterprise/artifactory-integration.md

Reference Documentation

Detailed Guides

• Getting Started
• Migration Guide
• CI Troubleshooting
• Multi-Output Recipes

Reference

• recipe.yaml Reference
• meta.yaml Reference
• Selectors Reference
• Jinja Functions

Quick Reference

• Commands Cheatsheet
• Bot Commands
• Common Errors

Templates

• Python noarch
• Python compiled
• Rust CLI
• Go CGO
• C++ CMake

External Resources

• conda-forge Documentation
• rattler-build Documentation
• pixi Documentation
• CFEP-25: python_min
• Recipe Format Schema
• conda-forge Staged Recipes

Version History

• v4.2.0 (2025-12-26): Added CRITICAL local testing exception for stdlib - must comment out for local builds, restore before submission
• v4.1.0 (2025-12-26): Enhanced stdlib requirement visibility with warnings and inline examples
• v4.0.0 (2025-12): Modular architecture, enterprise support, portability
• v3.0.0 (2025-01): PyPI mappings, rattler-build focus
• v2.0.0 (2024): Added modern recipe.yaml support
• v1.0.0 (2024): Initial release