Fix conda env creation hang and clang build failure on macOS; improve install docs#2953
Open
rwest wants to merge 4 commits into
Open
Fix conda env creation hang and clang build failure on macOS; improve install docs#2953rwest wants to merge 4 commits into
rwest wants to merge 4 commits into
Conversation
environment.yml previously used `python >=3.9,<3.12` so that the conda-incubator/setup-miniconda action could safely inject a per-matrix equality pin without creating a contradiction. That broad range forces the solver to consider every compatible package set for all three Python micro-versions simultaneously, which makes fresh environment creation slow and, on some local setups with older libmamba, can cause the solver to hang indefinitely. Changes: - environment.yml: tighten the pin to `=3.11`. Users running `conda env create -f environment.yml` now get a fast solve because the solver only needs to consider packages for a single Python version. - CI.yml (build-and-test): add a "Pin Python version for CI matrix" step immediately after checkout that rewrites `=3.11` to the matrix python-version before setup-miniconda runs. The -i.bak/rm idiom works on both GNU sed (Linux) and BSD sed (macOS). - CI.yml (regression-test): upgrade the hardcoded python-version from 3.9 to 3.11. There is no technical requirement for regression tests to use an older Python; 3.9 was a historical artifact. With the pin already set to 3.11 in the file, setup-miniconda's injected `=3.11` is redundant but harmless. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…in note Two classes of problems encountered during a macOS source install were not covered by the existing documentation: 1. An outdated Xcode Command Line Tools installation (Apple clang 11, from 2019) causes `make` to fail with "clang: error: invalid version number in 'MACOSX_DEPLOYMENT_TARGET'" because that vintage of clang does not recognise macOS deployment targets >= 11.0. Added a warning at the top of the page explaining how to detect and fix this, with the recommended reinstall command. 2. Conda versions older than ~24.0 (particularly libmamba 2.1.x) can hang indefinitely when solving the RMG environment. Added guidance to check and update conda before starting, including the `conda install -n base conda=26.3` workaround for cases where `conda update` fails to advance the version. Also added a brief note alongside the `conda env create` step explaining why environment.yml now pins Python 3.11 (faster solves), and cross-referenced the macOS CLT warning from the compiler prerequisites section. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Previous version written by Claude. These changes written by me.
You just know someone is going to copy and paste that incorrectly into their terminal....
JacksonBurns
approved these changes
May 14, 2026
Contributor
JacksonBurns
left a comment
JacksonBurns
left a comment
There was a problem hiding this comment.
lovely - please merge at your leisure
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation or Problem
Two separate issues were encountered when doing a fresh source install on macOS (reported while setting up a new conda environment after
pysidt-rmgwas added as a dependency. See #2952):conda env create -f environment.ymlhangs or is very slow. The previous Python constraint>=3.9,<3.12causes the conda solver to consider the full package graph for three Python versions simultaneously. On systems with older conda/libmamba (pre-24.x) this can hang indefinitely; even on modern toolchains it imposes unnecessary solver load.makefails withclang: error: invalid version number in 'MACOSX_DEPLOYMENT_TARGET=11.0'. The conda-forgeosx-64Python package targetsmacosx-11.0, but Apple clang versions older than ~clang 13 (shipped with Xcode Command Line Tools before ~2021) do not recognise any macOS deployment target ≥ 11.0. Users whose Command Line Tools installation was never updated since macOS Big Sur was released hit this immediately.Neither issue was documented, and the install guide gave no guidance on prerequisite tool versions.
Description of Changes
environment.yml>=3.9,<3.12to=3.11. This collapses the solver search space to a single Python version, making fresh environment creation fast and reliable..github/workflows/CI.ymlbuild-and-testjob: add a "Pin Python version for CI matrix" step immediately after checkout that rewritesconda-forge::python =3.11toconda-forge::python =<matrix-version>beforesetup-minicondaruns. This is necessary becausesetup-minicondaadds an equality pin rather than replacing the existing one, so a pre-existing=3.11would conflict with the injected=3.9or=3.10. Thesed -i.bak / rmidiom works on both GNU sed (Linux) and BSD sed (macOS).regression-testjob: upgrade the hardcoded Python version from 3.9 to 3.11. There is no technical reason for regression tests (which compare chemistry output, not Python behaviour) to use an older Python; 3.9 was a historical artifact. With the file already pinned to 3.11, setup-miniconda's injected=3.11is redundant but harmless, so no sed step is needed here.documentation/source/users/rmg/installation/anacondaDeveloper.rstconda updatefails to advance itconda env createstep with the alternativeconda create --filesyntax (preferred on conda ≥ 26.3) and simplify the "conda command not found" recovery advice.Testing
osx-64) with Apple clang 21.0.0 and conda 26.3.2:conda env create -f environment.ymlresolves successfully with the=3.11pin.make buildcompletes without errors after reinstalling Xcode Command Line Tools.Reviewer Tips
setup-minicondastep inbuild-and-test. The two steps are adjacent in the YAML with no conditional logic between them.=3.11and the hardcodedpython-version: 3.11insetup-minicondainjects a redundant but non-conflicting second=3.11constraint.conda_build.ymlis not changed — it builds from.conda/meta.yamland never readsenvironment.yml.