install docs bug: specify the acceptable interpreter versions

[jhanley634]

Summary: Choice of interpreter really matters on new installs.

The install guide does not caution against using interpreter 3.13, a trap that at least one new user fell into:

https://stackoverflow.com/questions/79348318/how-do-i-resolve-installation-errors-for-installing-climada-using-mamba

Minimally, mention interpreter versions the install docs have been tested against, and discourage using untested interpreters. Could be the addition of a single sentence.

More helpfully, instruct users to configure a new environment with a specific interpreter version, perhaps 3.11.8. Using an untested interpreter such as 3.13.1 produces a long error message which is not as diagnostic as new users would like to see. They need to be guided away from untested versions, and told (if they stray) to use a tested version.

Steps to reproduce:

1. Choose an untested interpreter, then follow the install guide's instructions, as detailed in the SO question.

Expected behavior

Starting with an untested interpreter should "fail early", giving a helpful diagnostic message that puts a newbie back on the right path.

After installing and activating the environment, python -c "climada" should silently succeed.

Climada Version: 5.0.0

System Information:

• Operating system and version: macOS 15.1
• Python version: 3.11.11 wins, 3.12.8 wins, 3.13.1 loses, all of which is the expected behavior

Additional context

I agree with you that conda (mamba) is a terrific tool for dealing with binary deps in a complex build. Over the course of many years I have helped lots of newbies with conda setup. A project should not change its build tooling lightly.

But the python packaging ecosystem has come a long way lately. Uv is a reaction to what came before. It's faster than pip, and much faster than conda, leading to a qualitative difference in how engineers interact with packaging. To rm -rf .venv/ and rebuild suddenly is no big deal, rather than something to dread. Quick experiments happen, and learning is accelerated. Crucially, it lets us specify interpreter version, and then easily change it to another version.

Not everyone who interacts with the Climada project is a project member, and they may have a smaller set of packaging needs than each of you do. Please consider incorporating some of that Stack Overflow post's answer into a script, example config file, documentation, or a workflow that you encourage newcomers to follow. Let them reap some of uv's benefits. And then by the time you release 6.0.0 or even 8.0.0, you may have have enough comfort level and experience with uv that you want to make changes more substantial than the doc improvements suggested in the current issue. Thx!

[emanuel-schmid]

Thanks for the notification.

The install guide lists the supported python versions under "Advanced instructions" only, which is arguably a flaw.

However, the "Simple instructions" only fail if the environment has a pinned python version, which kind of could be considered an advanced case. Without a pinned python version, the instructions lead to a downgrade to python 3.12 (or an upgrade if python is below 3.9)

I agree, uv is really nice - and really fast too! However the reason for using mamba/conda is that CLIMADA depends on GEOS and GDAL and I very much doubt that uv can help there - although I haven't tried really. The installation of these libraries without conda is a topic that we cannot cover with reasonable effort I'm afraid. Sorry.

[peanutfun]

@jhanley634 Thanks for reporting this. I agree that we should mention more prominently which Python versions are compatible.

Still, I am confused about the issue reported on SO, because by default there are no pinned packages in a new Conda environment. Our setup.py and the recipe for conda-forge specify the compatible Python versions. In the error message reported on SO, Conda notifies that it cannot install Climada because of an incompatible pinned Python version. The error message is a bit cryptic, but specific to Conda and there is nothing we can do to make it more clear. If, on the other hand, somebody updates their Conda configuration to always pin a specific Python version, they should have the technical knowledge to understand this issue.

As @emanuel-schmid pointed out, we will not be able to provide support for uv in the near future.

[jhanley634]

Ok, thank you. I recommend you tack on a "use 3.11" remark to the cited documentation page, and close this out. (Or simply close this out as "not reproducible" or "won't fix".)

For something beyond the scope of the current issue, you might possibly wish to supply a script of a few lines which checks and says "delete existing environment and re-run", or creates new environment, installs libs, and demonstrates a successful import. And have the docs mention the script. Initial setup seems to be a speed bump that newbies often stumble on, especially when using conda for the first time, and giving them a single-line "run this!" instruction gives them less rope to hang themselves with. It's always a big challenge to make sure something works 100% of the time for users of diverse backgrounds.