Skip to main content

Conda Package Management

This guide explains how PyMomentum conda packages are managed and published to conda-forge.

Overview​

PyMomentum is available on conda-forge, making it accessible through conda, mamba, pixi, and other conda-compatible package managers. The package is automatically built and published for multiple platforms (Linux, macOS, Windows) with support for both CPU and CUDA-accelerated variants.

Key Resources:

How It Works​

1. Release Process​

When a new version is released:

  1. Git Tag: Repository maintainers manually create and push a tag matching v* pattern (e.g., v0.2.0) to the main repository
    • Tags are typically created weekly or more frequently when requested
  2. Automated PR: conda-forge's bot detects the new tag and creates a PR in the momentum-feedstock repository
  3. Build & Test: CI builds packages for all supported platforms and runs tests
  4. Merge: After approval, the PR is merged and packages are published to conda-forge
  5. Availability: Users can install via conda install -c conda-forge pymomentum within hours

2. Feedstock Structure​

The momentum-feedstock contains:

  • recipe/meta.yaml: Package metadata, dependencies, build configurations
  • recipe/build.sh: Unix build script (Linux/macOS)
  • recipe/bld.bat: Windows build script
  • .ci_support/: Platform-specific build configurations (PyTorch, CUDA versions, etc.)
    • Auto-generated by conda-smithy when running conda smithy rerender locally or commenting "@conda-forge-admin, please rerender" on PRs

3. Version and Dependency Management​

PyTorch and CUDA Pinning​

conda-forge uses global pinning to ensure compatible versions across the ecosystem:

  • PyTorch versions: Managed in conda-forge-pinning-feedstock
  • CUDA versions: Also globally pinned to avoid "dependency islands"
  • PyMomentum: Automatically builds against all pinned PyTorch/CUDA combinations

Example: If conda-forge supports PyTorch 2.8 with CUDA 12.9 and 12.6, momentum-feedstock automatically builds:

  • pymomentum-0.2.0-cuda129_py312_* (PyTorch 2.8 + CUDA 12.9 + Python 3.12)
  • pymomentum-0.2.0-cuda126_py312_* (PyTorch 2.8 + CUDA 12.6 + Python 3.12)
  • pymomentum-0.2.0-cpu_py312_* (PyTorch 2.8 CPU + Python 3.12)
  • ... and more combinations for different Python versions and platforms

Adding Support for Older Dependencies​

If you need an older CUDA or PyTorch version not currently supported:

  1. Read conda-forge documentation on pinning and build matrices to understand how to configure version combinations
  2. Update recipe/conda_build_config.yaml (if needed) to specify version constraints
  3. Run rerender: The .ci_support/ files are automatically generated by conda-smithy
  4. Submit PR to momentum-feedstock
  5. Example PR: Supporting CUDA 12.6

Since momentum-feedstock is open source, community contributions are welcome!

Updating the Feedstock​

When to Update​

You typically need to update the feedstock when:

  1. New release: Automated bot creates PR (usually no manual intervention needed)
  2. Build fixes: Fixing build failures on specific platforms
  3. Dependency updates: Adding support for new PyTorch/CUDA versions
  4. Platform support: Adding new OS or architecture support

Making Changes​

  1. Fork the momentum-feedstock repository
  2. Update recipe: Modify recipe/meta.yaml or build scripts
  3. Test locally (optional but recommended): 
    # Install conda-build
    conda install conda-build

    # Build locally
    conda build recipe/
  4. Create PR: Submit to momentum-feedstock
  5. CI Review: conda-forge CI automatically tests all platforms
  6. Merge: After approval, packages are published

Troubleshooting​

Finding Package Details​

Inspect installed files and metadata for any package version using conda-metadata-app.

Or locally:

# Show package info
conda info pymomentum

# List installed files
conda list pymomentum --show-channel-urls

Installing Specific Versions​

# Install specific version
conda install -c conda-forge pymomentum=0.1.77

# Install specific version with CUDA constraint
conda install -c conda-forge "pymomentum=0.1.77=cuda129*"

# Install specific Python version
conda install -c conda-forge "pymomentum=0.1.77=*py312*"

Build Failures​

If conda builds fail:

  1. Check CI logs in the feedstock PR
  2. Test locally with conda build recipe/
  3. Check dependency availability: Ensure PyTorch/CUDA versions exist on conda-forge
  4. Review recent changes: Check if upstream momentum changes broke the build

Dependency Conflicts​

If users report dependency conflicts:

  1. Verify pinning: Check conda-forge-pinning-feedstock
  2. Update constraints: Relax version constraints in recipe/meta.yaml if too strict
  3. Test resolution: Use conda-tree or pixi tree to visualize dependency graphs

Alternative: Building from Source​

If conda packages don't meet your requirements (e.g., custom PyTorch build, unreleased CUDA version), you can:

  1. Clone momentum: git clone https://github.com/facebookresearch/momentum
  2. Setup environment: pixi install or create custom conda environment
  3. Build: pip install . (see Getting Started)

This gives you full control over dependency versions at the cost of manual maintenance.

Contributing​

We welcome contributions to improve conda packaging! Areas where help is appreciated:

  • Platform support: Adding ARM64 Linux, new OS versions
  • Dependency backports: Supporting older PyTorch/CUDA for legacy systems
  • Build optimizations: Reducing package size, improving build times
  • Documentation: Clarifying build procedures, troubleshooting guides

Submit PRs to momentum-feedstock or open issues for discussion.