Dependency Issues

Relevant source files

• .github/workflows/ci.yml
• pixi.lock
• pixi.toml
• pyproject.toml
• src/afterpython/cli/commands/bump.py
• src/afterpython/templates/ci-workflow-template.yml
• uv.lock

This page documents common dependency-related problems in afterpython and their solutions. The system uses a dual dependency management strategy with both uv and pixi, which can lead to specific issues around lock file synchronization, version constraints, and platform-specific resolution. For general build errors, see Build Errors. For CI/CD-specific dependency failures, see CI/CD Failures.

Dual Dependency Manager Architecture

The afterpython system manages dependencies through two parallel systems that must remain synchronized:

Diagram: Dual Dependency System and Conflict Points

Sources: pyproject.toml1-74 pixi.toml1-78 uv.lock1-10 pixi.lock1-40

Common Dependency Issues

Issue 1: mystmd Version Constraint Conflicts

Symptom: Installation fails with version conflict errors related to platformdirs or nodeenv packages.

Root Cause: The mystmd package on PyPI has restrictive version constraints (platformdirs~=4.2.2, nodeenv~=1.9.1) that conflict with other packages requiring newer versions.

Resolution Strategy:

The system employs different strategies depending on the package manager:

Manager	Strategy	Configuration Location
uv	Override dependencies	[tool.uv] in pyproject.toml
pixi	Install from conda-forge	[dependencies] in pixi.toml

For uv users:

The override mechanism in pyproject.toml63-65 relaxes mystmd's constraints:

This override is reflected in uv.lock6-9:

[manifest]
overrides = [
    { name = "nodeenv", specifier = ">=1.9.1" },
    { name = "platformdirs", specifier = ">=4.5.0" },
]

For pixi users:

The system installs mystmd from conda-forge instead of PyPI, as documented in pixi.toml21-23:

Manual Fix:

If you encounter this issue:

1. Verify override presence: Check that pyproject.toml63-65 contains the override configuration
2. Regenerate uv.lock: Run uv lock --upgrade-package platformdirs --upgrade-package nodeenv
3. For pixi: Ensure mystmd is in [dependencies] not [pypi-dependencies]

Sources: pyproject.toml63-65 pixi.toml18-24 uv.lock6-9

---

Issue 2: Lock File Synchronization After Version Bump

Symptom: After running ap bump, the repository has uncommitted pixi.lock changes, or subsequent pixi commands fail.

Root Cause: The version bump updates pyproject.toml version, which affects the editable installation reference in pixi.lock. The lock file must be regenerated to reflect the new version.

Diagram: Automatic Lock File Update During Version Bump

The ap bump command automatically handles this in src/afterpython/cli/commands/bump.py94-118:

Manual Fix:

If lock file is out of sync:

1. Run pixi install to regenerate the lock
2. Check changes: git diff pixi.lock
3. Commit if necessary: git add pixi.lock && git commit -m "build: update pixi.lock"

Sources: src/afterpython/cli/commands/bump.py94-118

---

Issue 3: Platform-Specific Dependency Resolution Failures

Symptom: Dependencies install successfully on one platform but fail on another (e.g., works on Linux but fails on Windows or macOS ARM).

Root Cause: pixi.lock contains platform-specific package resolutions. Different platforms may have different available packages or versions from conda-forge.

Diagram: Platform-Specific Resolution in pixi.lock

The lock file contains separate resolution trees for each platform as seen in pixi.lock9-40 for Linux:

packages:
  linux-64:
  - conda: https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2
  - conda: https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-2_gnu.tar.bz2
  ...
  osx-64:
  - conda: https://conda.anaconda.org/conda-forge/osx-64/bzip2-1.0.8-h500dc9f_8.conda

Resolution:

Issue Type	Solution
Missing package	Check if package is available on conda-forge for target platform
Version unavailable	Relax version constraint in pixi.toml or use platform-specific overrides
Architecture mismatch	Use PyPI fallback in [pypi-dependencies] if conda package unavailable

Manual Fix:

1. Identify missing package: Read error message from pixi install
2. Check conda-forge: Visit https://anaconda.org/conda-forge/<package-name>
3. Options:
   • If available: Update platform list in pixi.toml5 to match available platforms
   • If unavailable: Move dependency to [pypi-dependencies] which has better cross-platform support
4. Regenerate lock: pixi lock --revalidate

Sources: pixi.toml5 pixi.lock9-174

---

Issue 4: Lock File Divergence Between Managers

Symptom: uv.lock and pixi.lock contain different versions of the same package, leading to inconsistent behavior depending on which manager is used.

Root Cause: The two package managers use different dependency resolution algorithms and package sources (PyPI vs conda-forge). Updates to one lock file don't automatically propagate to the other.

Detection Matrix:

Condition	uv Environment	pixi Environment	Issue Indicator
Package versions match	✓ Works	✓ Works	No issue
uv newer, pixi older	✓ Works	⚠ May fail	Version mismatch warnings
pixi newer, uv older	⚠ May fail	✓ Works	Import errors, API changes
Both outdated	⚠ May fail	⚠ May fail	Security vulnerabilities

Resolution Process:

Diagram: Lock File Synchronization Workflow

Manual Synchronization:

1. Compare package versions:

2. Update source configurations to match:

   • pyproject.toml34-52 for uv dependencies
   • pixi.toml27-44 for pixi PyPI dependencies

3. Regenerate both locks:

4. Test both environments:

Sources: pyproject.toml34-52 pixi.toml27-44

---

Issue 5: Installation Failures Due to Missing System Dependencies

Symptom: Installation fails with errors about missing compilers, system libraries, or build tools.

Root Cause: Some PyPI packages require system-level dependencies for compilation. The uv-only approach lacks these, while pixi includes them via conda-forge.

System Dependency Comparison:

Dependency Type	uv Environment	pixi Environment
C compiler	❌ Must be system-installed	✓ Provided by conda
Node.js	❌ Must be system-installed	✓ From pixi.toml24
GitHub CLI	❌ Must be system-installed	✓ From pixi.toml24
OpenSSL/SSL libs	❌ System-dependent	✓ Versioned in conda
ICU (Unicode)	❌ System-dependent	✓ From conda-forge

Resolution:

The pixi environment includes system dependencies like nodejs and gh CLI as shown in pixi.toml18-24:

These appear in the lock file with specific versions for each platform, e.g., pixi.lock14 for Linux:

- conda: https://conda.anaconda.org/conda-forge/linux-64/gh-2.83.1-h76a2195_0.conda

Manual Fix:

1. For missing compilers/build tools:

   • Linux: apt-get install build-essential or similar
   • macOS: Install Xcode command line tools
   • Windows: Install Visual Studio Build Tools

2. For missing Node.js/system tools:

   • Switch to pixi: pixi install
   • Or install system-wide: Use system package manager

3. For SSL/crypto errors:

   • Check if using pixi: The conda openssl package handles this
   • For uv: Install system SSL libraries

Sources: pixi.toml18-24 pixi.lock14-40

---

Issue 6: Dependency Resolution Timeout or Extremely Slow

Symptom: uv lock or pixi lock commands take minutes or hang indefinitely.

Root Cause: Complex dependency trees with many optional features can cause resolution algorithms to explore exponential solution spaces. The uv.lock contains ~400 packages with extensive platform-specific wheels.

Performance Characteristics:

Operation	Expected Time	Slow Threshold	File Reference
uv lock	< 30 seconds	> 2 minutes	uv.lock1 (~400 pkgs)
pixi lock	< 1 minute	> 5 minutes	pixi.lock1 (multi-platform)
uv sync	< 10 seconds	> 1 minute	N/A
pixi install	< 30 seconds	> 2 minutes	N/A

Resolution:

1. Use cached resolution:

2. Incremental updates:

3. Simplify constraints:

   • Remove unnecessary upper bounds in pyproject.toml34-52
   • Use >= instead of ~= for more resolution flexibility

4. Clear caches:

Sources: uv.lock1-150 pixi.lock1-40

---

Issue 7: Pre-commit Hook Dependency Conflicts

Symptom: Pre-commit hooks fail with import errors or version conflicts, even though main installation works.

Root Cause: Pre-commit creates isolated virtual environments for each hook, which may resolve dependencies differently than the main environment.

Hook Dependency Flow:

Diagram: Pre-commit Isolated Environment Issues

Resolution:

1. Update pre-commit environments:

2. Force re-creation:

3. Match Python version: Verify pre-commit uses the same Python as your main environment by checking .pre-commit-config.yaml language versions.

4. For persistent issues: Run tools directly instead of through pre-commit:

Sources: pyproject.toml49-50

---

Diagnostic Commands

Use these commands to diagnose dependency issues:

Command	Purpose	Output Interpretation
uv pip list	Show installed packages in uv environment	Compare versions with uv.lock
pixi list	Show installed packages in pixi environment	Compare versions with pixi.lock
uv tree <package>	Show dependency tree for package	Identify constraint conflicts
uv pip check	Verify no broken dependencies	Resolves to fix suggestions
pixi info	Show pixi environment information	Verify platform and Python version
diff <(uv pip list) <(pixi list)	Compare environments	Identify version divergence
ap sync	Check configuration sync	Verify metadata consistency

Sources: pyproject.toml34-52 pixi.toml27-44

---

Prevention Best Practices

To avoid dependency issues:

1. Keep sources synchronized:

   • When adding a dependency, update both pyproject.toml34-52 and pixi.toml27-44
   • Use same version specifiers in both files

2. Regenerate locks together:

3. Test both environments in CI: The CI workflow automatically detects and tests both as shown in .github/workflows/ci.yml

4. Use version ranges, not pins:

   • Prefer >=X.Y.Z over ==X.Y.Z
   • Avoid unnecessary upper bounds unless known incompatibility

5. Document special cases:

   • Add comments for mystmd conda installation reason in pixi.toml21-23
   • Explain override rationale in pyproject.toml64

6. Regular updates:

7. Commit lock files: Both uv.lock and pixi.lock are tracked in git per .gitignore95-105 to ensure reproducibility

Sources: pyproject.toml34-65 pixi.toml21-44 .gitignore95-105