Skip to content

[DOCS] Modernize installation page to cover uv, pixi, and pip #717

@EKtheSage

Description

@EKtheSage

Current state

docs/getting_started/install.md only covers pip install chainladder. Modern Python projects (e.g. https://ibis-project.org/install) typically present a matrix of package managers so users can choose the one that matches their environment.

Proposal

Restructure the install page into three sections, in this order, with uv and pixi recommended for new users and pip retained for backward compatibility and existing workflows:

  1. uv: uv add chainladder (recommended, fastest, modern default)
  2. pixi: pixi add chainladder (recommended for conda/mamba users)
  3. pip: pip install chainladder (works everywhere, including legacy environments)

Verified install commands

Manager Command Version installed Source
pip pip install chainladder 0.9.1 PyPI
uv uv add chainladder 0.9.1 PyPI
pixi pixi add chainladder 0.8.26 conda-forge

All three resolve and import cleanly. The pixi version is older (see below).

Prerequisite: keep the conda-forge feedstock in sync with PyPI

The conda-forge recipe (https://github.com/conda-forge/chainladder-feedstock) is currently at 0.8.26, while PyPI is at 0.9.1. The autotick bot (regro-cf-autotick-bot) is already enabled on the feedstock and has opened PR #31 with the v0.9.1 update, but the PR has not yet been merged.

Two related fixes would close the gap:

  1. Merge feedstock PR Propagate bootstrap process risk #31 (chainladder v0.9.1 conda-forge/chainladder-feedstock#31) so pixi users get the current version today.
  2. Enable conda-forge bot automerge on the feedstock by opening an issue with @conda-forge-admin, please add bot automerge in the title. Once added, future autotick bot PRs (one per release) will merge automatically if the recipe lints clean and tests pass, eliminating manual review delay.

With automerge in place, every PyPI release would land on conda-forge within hours, and the install page can confidently recommend pixi without a version-lag caveat.

Out of scope for this issue

  • Recommending a specific manager as "blessed" or preferred. The goal is to document multiple working paths, not to push users to one.
  • Developer environment instructions. docs/library/contributing.md already documents the uv sync dev workflow.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Documentation 📚Changes to docstrings or the documentation site. No codebase changes.Effort > Moderate 🐕Mid-sized tasks estimated to take a few days to a few weeks.Impact > Minor 🔷Small, backward compatible change. Treat like a patch release (e.g., 0.5.8 → 0.5.9).

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions