Pin Windows setup guide to Python 3.11 to match the workspace#45
Merged
Conversation
The guide already named 3.11 but buried it and said "latest Python 3.11," which invites grabbing whatever python.org's front page offers. On a brand-new Python (3.13/3.14), norgatedata and friends have no matching wheels, so pip either fails to compile or installs into a global per-version location instead of the venv, producing the "import works but cotdata-update not found" trap. - Lead Step 1 with an explicit "use 3.11, and why" callout, matching npf/.venv and wheel availability, warning against newer releases. - Make the version-check step catch a wrong major.minor and show how to target 3.11 (uv venv --python 3.11 / py -3.11 -m venv). - Add a troubleshooting entry for deps failing to build on a newer Python. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A uv-created venv ships without a standalone pip, so plain `pip install` after `uv venv` falls through to the global Python and installs there. The venv's own python then can't import the package (ModuleNotFoundError) even though the install reported success. The guide recommended uv but then showed plain `pip install`, walking straight into this. - Step 2 uv section: call out that a uv venv has no pip; use uv pip. - Step 3: add a pip vs uv pip chooser and show the uv form for each install variant. - Troubleshooting: make "plain pip into a uv venv" the first listed cause of ModuleNotFoundError, with the where pip / where python check. - Note the activated prompt may read (cotdata), not just (.venv). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
1 participant
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.
What
Pins the Windows setup guide to Python 3.11 — the version the rest of the workspace uses (
npf/.venv) and the one cotdata's dependencies have prebuilt wheels for.Why
The guide already said 3.11 but buried it and phrased it as "latest Python 3.11," which invites installing whatever python.org's front page serves. Hitting this in practice: installing Python 3.14 meant
norgatedatahad no matching wheel, pip fell back to a global per-version install location (AppData\Local\Python\pythoncore-3.14-64) instead of the venv, and the result was the confusing "import cotdataworks butcotdata-updateis not recognized" trap.Changes
python --versioncheck now catches a wrong major.minor and shows how to target 3.11 (uv venv --python 3.11,py -3.11 -m venv .venv).Docs-only.
🤖 Generated with Claude Code