Skip to content

Issue: [Docs] Documentation displays dependencies for only one Python variant despite multiple builds existing #46

@rohan-ibn-tariq

Description

@rohan-ibn-tariq

Problem Description

The Bioconda documentation website only displays dependency information for a single Python variant (typically py310), even when packages have successfully built variants for multiple Python versions (py39, py310, py311, py312, py313).

This creates confusion for users who may think the package only supports one Python version, when in reality all variants are available and functional in the conda channel.

Affected Packages

This issue affects Python extension modules that require python in the host: requirements (packages that compile C/C++ code against Python's C API).

Verified affected packages include:

  • pyfastx
  • pysam
  • pybigwig
  • cutadapt
  • pybedtools
  • albatradis
  • b2btools
  • bialign

This likely affects hundreds of packages in Bioconda that are Python extension modules.

Examples include:

Example 1: pyfastx

Documentation page: https://bioconda.github.io/recipes/pyfastx/README.html

What the docs show:

depends python: >=3.10,<3.11.0a0
depends python_abi: 3.10.* *_cp310

What actually exists in the channel:

$ conda search -c bioconda "pyfastx=2.2.0" | grep "_1"
pyfastx 2.2.0 py310h397c9d8_1  bioconda            
pyfastx 2.2.0 py311h384fd50_1  bioconda            
pyfastx 2.2.0 py312h4711d71_1  bioconda            
pyfastx 2.2.0 py313h8eaa236_1  bioconda            
pyfastx 2.2.0  py39h0699b22_1  bioconda  

Verify with detailed info:

$ conda search -c bioconda "pyfastx=2.2.0" --info | grep -E "build|python|timestamp"
build       : py310h397c9d8_0
build number: 0
timestamp   : 2025-01-03 06:47:32 UTC
  - python >=3.10,<3.11.0a0
  - python_abi 3.10.* *_cp310
build       : py310h397c9d8_1
build number: 1
timestamp   : 2025-07-18 06:35:16 UTC
  - python >=3.10,<3.11.0a0
  - python_abi 3.10.* *_cp310
build       : py311h384fd50_0
build number: 0
timestamp   : 2025-01-03 06:51:45 UTC
  - python >=3.11,<3.12.0a0
  - python_abi 3.11.* *_cp311
build       : py311h384fd50_1
build number: 1
timestamp   : 2025-07-18 06:37:32 UTC
  - python >=3.11,<3.12.0a0
  - python_abi 3.11.* *_cp311
build       : py312h4711d71_0
build number: 0
timestamp   : 2025-01-03 06:49:04 UTC
  - python >=3.12,<3.13.0a0
  - python_abi 3.12.* *_cp312
build       : py312h4711d71_1
build number: 1
timestamp   : 2025-07-18 06:34:09 UTC
  - python >=3.12,<3.13.0a0
  - python_abi 3.12.* *_cp312
build       : py313h8eaa236_1
build number: 1
timestamp   : 2025-07-18 06:32:48 UTC
  - python >=3.13,<3.14.0a0
  - python_abi 3.13.* *_cp313
build       : py39h0699b22_0
build number: 0
timestamp   : 2025-01-03 06:50:24 UTC
  - python >=3.9,<3.10.0a0
  - python_abi 3.9.* *_cp39
build       : py39h0699b22_1
build number: 1
timestamp   : 2025-07-18 06:36:25 UTC
  - python >=3.9,<3.10.0a0
  - python_abi 3.9.* *_cp39

Example 2: pysam

Documentation page: https://bioconda.github.io/recipes/pysam/README.html

What the docs show:

depends python: >=3.10,<3.11.0a0
depends python_abi: 3.10.* *_cp310

What actually exists in the channel:

$ conda search -c bioconda pysam | tail -20
pysam                         0.23.1  py39hdd5828d_0  bioconda            
pysam                         0.23.2 py310h64e62c9_0  bioconda            
pysam                         0.23.2 py311hb456a96_0  bioconda            
pysam                         0.23.2 py312h47d5410_0  bioconda            
pysam                         0.23.2  py39hdd5828d_0  bioconda            
pysam                         0.23.3 py310h64e62c9_0  bioconda            
pysam                         0.23.3 py310h64e62c9_1  bioconda            
pysam                         0.23.3 py310haee4d61_0  pkgs/main           
pysam                         0.23.3 py311haee4d61_0  pkgs/main           
pysam                         0.23.3 py311hb456a96_0  bioconda            
pysam                         0.23.3 py311hb456a96_1  bioconda            
pysam                         0.23.3 py312h47d5410_0  bioconda            
pysam                         0.23.3 py312h47d5410_1  bioconda            
pysam                         0.23.3 py312haee4d61_0  pkgs/main           
pysam                         0.23.3 py313h7c062c9_1  bioconda            
pysam                         0.23.3 py313haee4d61_0  pkgs/main           
pysam                         0.23.3 py314h666adb2_0  pkgs/main           
pysam                         0.23.3  py39haee4d61_0  pkgs/main           
pysam                         0.23.3  py39hdd5828d_0  bioconda            
pysam                         0.23.3  py39hdd5828d_1  bioconda 

Root Cause Analysis

What Triggers Multiple Python-Specific Builds

Packages that include python in the host: requirements section create separate builds for each Python version:

# Recipe pattern that triggers multiple builds
requirements:
  build:
    - {{ compiler('c') }}
  host:
    - python  # This triggers Python-specific builds
  run:
    - python

Why this happens:

  • Python extension modules must compile against Python's C API
  • The compiled code (.so files on Linux, .pyd on Windows) is Python-version-specific
  • Conda-build creates separate packages for each Python version

Build result:

pyfastx-2.2.0-py39h0699b22_1.tar.bz2   # For Python 3.9
pyfastx-2.2.0-py310h397c9d8_1.tar.bz2  # For Python 3.10
pyfastx-2.2.0-py311h384fd50_1.tar.bz2  # For Python 3.11
[etc...]

Packages That Display Correctly

Pattern 1: noarch: python packages

Pure Python packages use noarch: python to create a single platform-independent build:

build:
  noarch: python

requirements:
  host:
    - python >=3.9
  run:
    - python >=3.9

Example: deeptools
Build: ******* (single build)
Docs show: python >=3.9

Pattern 2: Python only in run:, not in host:

Compiled programs that call Python as a subprocess (not Python extensions):

requirements:
  build:
    - {{ compiler('c') }}
  host:
    - zlib  # No python here
  run:
    - python >=3.12

Examples: BWISE, CenMAP
Build: **************** (no Python version in hash)
Docs show: python >=3.12

The Documentation Generator Problem

For packages with multiple Python-specific builds:

Current behavior:

  • Lists all version-build combinations in the "versions:" section
  • Arbitrarily picks ONE build's metadata to display (usually py310)
  • Does not indicate that other Python versions are available

Expected behavior:

  • Display metadata for all variants, OR
  • Show a generic range encompassing all builds (e.g., python >=3.9,<3.14.0a0), OR
  • Add a note indicating multiple Python-specific builds exist

Important: The conda channel metadata is correct - this issue only affects the documentation display layer.

Expected Behavior

The documentation should either:

Option 1: Show all variants (preferred)

Display dependency information for each Python variant, similar to how version-build combinations are listed:

Python 3.9 variant:
  depends python: >=3.9,<3.10.0a0
  depends python_abi: 3.9.* *_cp39

Python 3.10 variant:
  depends python: >=3.10,<3.11.0a0
  depends python_abi: 3.10.* *_cp310

Python 3.11 variant:
  depends python: >=3.11,<3.12.0a0
  depends python_abi: 3.11.* *_cp311

[etc...]

Option 2: Show generic range

Display a generic dependency range that encompasses all available builds:

depends python: >=3.9,<3.14.0a0
Note: Separate builds available for Python 3.9, 3.10, 3.11, 3.12, 3.13

Option 3: Add a note

Keep current display but add a clear note:

depends python: >=3.10,<3.11.0a0  (showing py310 variant)
Note: This package has separate builds for Python 3.9, 3.10, 3.11, 3.12, and 3.13.
      Conda will automatically select the appropriate build for your Python version.

Current Impact

User confusion:

  • Users may incorrectly believe packages only support one Python version
  • Users may unnecessarily seek alternative packages
  • Users may file incorrect bug reports

Reality:

  • All Python variants are built and functional
  • Conda/mamba automatically selects the correct variant based on the user's Python version
  • Users can install packages with any supported Python version successfully

Important: The misleading documentation does not affect package functionality - conda ignores the docs and correctly resolves dependencies based on the user's environment.

Verification:
Testing with multiple Python versions confirms conda auto-resolves correctly for (pyfastx):

  • Python 3.11 environment → installs py311h384fd50_1 build
  • Python 3.12 environment → installs py312h4711d71_1 build

The documentation showing python >=3.10,<3.11.0a0 is misleading but does NOT affect functionality.

Reproduction Steps

  1. Go to C extension package docs page (e.g., pyfastx, pysam), verified one listed already in Affected Packages
  2. Check the "depends python:" field
  3. Notice it shows only one specific Python version constraint
  4. Run conda search -c bioconda <package> to see multiple Python variants exist
  5. Observe the discrepancy

Environment

Related

This may be related to how recipe metadata is extracted and rendered. The conda channel metadata is correct; the issue is only in the documentation display layer.

Verification Commands

For any affected package, users can verify the actual available builds:

# List all builds
conda search -c bioconda 

# Show detailed dependency info for specific version
conda search -c bioconda "=" --info

# Filter for Python dependencies
conda search -c bioconda "=" --info | grep python

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions