Skip to content

Troubleshooting

Jump to bottom
Becky Sweger edited this page Jan 21, 2025 · 2 revisions

Troubleshooting hubDocs Setup

The hubDocs README.md recommends uv for creating Python virtual environments and managing project dependencies.

Although uv is a cross-platform tool that manages many tedious parts of setting up a dev environment (e.g., installing Python, if needed), there are few edge cases to be aware of.

Error: No solution found when resolving dependencies

This message occurs when uv is unable to reconcile the dependencies in the project's requirements.txt file with virtual environment's Python interpreter. For example:

uv pip install -r requirements/requirements.txt
  × No solution found when resolving dependencies:
  ╰─▶ Because the current Python version (3.9.15) does not satisfy Python>=3.10 and alabaster==1.0.0
      depends on Python>=3.10, we can conclude that alabaster==1.0.0 cannot be used.
      And because you require alabaster==1.0.0, we can conclude that your requirements are unsatisfiable.

The mostly likely cause of this error is having an active Python virtual environment when running the uv venv --seed command. For example, conda's base environment was active, so uv detected that and used its Python interpreter when creating the new hubDocs environment.

To resolve it, deactivate any active Python virtual environments and re-run uv venv --seed.

  • To deactivate a conda environment:

    conda deactivate

  • To deactivate an environment created with Python's build-in venv command:

    deactivate

Bonus

Add this to your .zshrc/.bashrc to prevent conda from strong-arming itself to be the default python manager:

conda deactivate

Further reading

For more information about how uv determines which Python interpreter to use when creating a virtual environment:

Clone this wiki locally