Document python vs python3 on Windows - #6
Merged
jessicahiggs merged 1 commit intoAug 18, 2026
Conversation
Every command in the README is spelled python3, which is the name macOS and Linux ship. The python.org Windows installer provides python and py instead, so a Windows reader hits the very first command failing while the page above it promises Windows support. The failure is worse than a plain "not found": python3 usually still resolves, to the Microsoft Store app-execution alias, which prints "Python was not found; run without arguments to install from the Microsoft Store" and exits. That reads as a broken Python installation rather than a command-name mismatch, which is the wrong thing to go and debug. One note under the requirements table, next to the existing Windows support claim. Closes jessicahiggs#4
Owner
|
Merged — thank you. Testing this on an actual Windows machine rather than describing it from the issue was the right call, and it turned up something the issue got wrong: I assumed a clean Naming that exact message is what makes the note findable by someone already staring at it. Good judgement on leaving the ~9 |
jessicahiggs
added a commit
that referenced
this pull request
Aug 18, 2026
* Update README.md * added --json flag for structured JSON output * Drop duplicate Windows note; the version from #6 is already on main Keeps this PR to the --json work (#3). The Windows documentation (#4) landed via #6, which named the Microsoft Store stub message explicitly. --------- Co-authored-by: jessicahiggs <jessicakhiggs@gmail.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
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.
Closes #4. Documentation only — one note in
README.md, placed directly under the requirements table and next to the existing "Works on macOS, Linux and Windows" claim, since that sentence is what makes the mismatch surprising.What actually happens
I checked this on Windows 11 rather than describing it from memory, and the real failure is worse than the "command not found" the issue anticipates:
python3does resolve — to the Microsoft Store app-execution alias stub. Running it prints:and exits. So a reader with a perfectly good Python 3.12 on PATH is told Python was not found, and sent off to reinstall Python — which will not help, because the problem is the command name, not the interpreter. That is a worse trap than a bare "not found", so the note names the message explicitly to make it recognisable.
pyis also present (C:\Windows\py.exe), so the note offers both.I confirmed the scripts themselves are fine under the right name —
python scripts/build_graph.py examples/sample-vault --out ...runs clean on Windows:So this really is only a naming issue, and a one-line docs fix is the whole of it.
What I did not do
I left the ~9
python3occurrences in the code blocks alone. Rewriting them topythonwould break macOS and Linux readers, wherepythonmay be absent or Python 2, and adding a second Windows variant to every block would triple the command list to say one thing. One substitution rule stated once seemed the better trade — happy to do it differently if you prefer.