Skip to content

Document python vs python3 on Windows - #6

Merged
jessicahiggs merged 1 commit into
jessicahiggs:mainfrom
dchaudhari7177:docs/python3-on-windows
Aug 18, 2026
Merged

Document python vs python3 on Windows#6
jessicahiggs merged 1 commit into
jessicahiggs:mainfrom
dchaudhari7177:docs/python3-on-windows

Conversation

@dchaudhari7177

Copy link
Copy Markdown
Contributor

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:

$ where python3
C:\Users\...\AppData\Local\Microsoft\WindowsApps\python3.exe

$ where python
C:\Users\...\AppData\Local\Programs\Python\Python312\python.exe

python3 does resolve — to the Microsoft Store app-execution alias stub. Running it prints:

Python was not found; run without arguments to install from the Microsoft Store,
or disable this shortcut from Settings > Apps > Advanced app settings > App execution aliases.

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.

py is 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:

wikilink edges resolved: 15
awaiting model extraction: 6
written: ...

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 python3 occurrences in the code blocks alone. Rewriting them to python would break macOS and Linux readers, where python may 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.

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
@jessicahiggs
jessicahiggs merged commit 395d6a1 into jessicahiggs:main Aug 18, 2026
@jessicahiggs

Copy link
Copy Markdown
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 command not found, and the real behaviour is worse. python3 resolving to a Store stub that says "Python was not found" would send someone off reinstalling a Python they already have.

Naming that exact message is what makes the note findable by someone already staring at it. Good judgement on leaving the ~9 python3 occurrences alone too — one substitution rule stated once is the right trade.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

2 participants