Let me tell you a true supernatural story.
One evening I typed in the Windows terminalpython I pressed Enter. Nothing happened. No error message, no prompts, the cursor flashed, a newline appeared, and the session ended. I thought the terminal was broken, so I opened another one, but the same thing happened. I thought the keyboard was broken, so I typed...dir That's normal. Onlypython This word sounds like it's talking to thin air.
I probably wasted an entire afternoon that day. The answer is: Windows 10 and 11 put [something] on the PATH.python.exe andpython3.exe Two "application execution aliases" point to the Microsoft Store. On machines without Python installed, running it will open the store; under certain settings, it will quietly terminate without errors or output. It's not Python; it's a sign that looks like Python, but there's nothing behind it.
From that day on, I had an ironclad rule: automated scripts must never depend on anything on the PATH.python .usepy -3 The launcher, or better yet, the complete path to the project's own interpreter.
Why be especially careful when running Python on Windows?
CPython is a reference implementation of Python, licensed under PSF, and its current stable version is 3.13. It's easy to install on Windows: download from the official website, click "next," click "next," and you're done. The problem isn't "it installs," but "it runs the same thing every time." A Windows computer that's been used for several years might simultaneously have the store version, the official version, a version that comes with a certain editor, and a version secretly installed by some tool. Your program might run perfectly fine with version A today, but tomorrow, for some reason, it uses version B, and then a certain package disappears.
It's like having five identical ballpoint pens scattered on your desk, two of which are out of ink. Each time you grab one, whether you can write anything depends entirely on luck. The solution isn't to throw them all away, but to assign a specific pen to each assignment and put it back afterward.
The interpreter travels with the project
My approach is to place a fixed version of CPython in each project directory, then use it to build a venv repository. All project commands are executed through the venv repository.python.exe Execute. The startup script checks if the venv base is the correct one; if not, it fails directly and does not revert to a version that happens to exist on the system.
"Straight failure" sounds unfriendly, but it's my favorite kind of unfriendly. It tells you "you've picked up the wrong pen" before you even start running, instead of letting you finish three pages only to find that the words are all broken and disjointed.
When creating a new working directory using git worktree, venv needs to be copied and modified as a whole.pyvenv.cfg The base path. It's an extra step, a bit tedious, but the test always runs on the correct interpreter.
The ._pth of the embeddable package
The official website offers an "embeddable" zip version, which is ready to use after extraction without requiring installation, making it ideal for packaging tools or inclusion in projects. It contains a...python313._pth This file will replace the usual path calculation: the working directory will not be added.sys.path ,PYTHONPATH Environmental variables were also ignored.
In layman's terms: A direct interpreter that decompresses exactly as is can't even import your own modules. You'll see...ModuleNotFoundError Then check if the file exists; if it does, check if the name is correct; if it does, check if it exists.__init__.py Yes, it is. Everything is correct, but I just can't find it. In that...._pth Add a line to the file. Or you can just use your source code path, but you need to know it exists first. This kind of "it's written in the file, but nobody will read it the first time" thing is especially common in Python on Windows.
Two lock files, with hashes required at install time
The samerequirements.txt The extracted versions for Windows and Linux may differ, especially for packages with native extensions. I've kept two lock files, each generated on its respective platform, with SHA-256 encoded in each line. Use them during installation.pip install --require-hashes --only-binary=:all: The former requires that the hash of each wheel matches, while the latter prohibits on-site compilation from source code.
The "prevent on-site compilation" rule is especially valuable on Windows. You've probably seen those installations that start displaying C compiler errors halfway through, with three pages of red text, the last line saying "Visual Studio Build Tools required." (Added)--only-binary After that, the situation becomes a clean "no matching wheel" situation, where you at least know where the problem lies, instead of being dragged into a world you don't want to be in at all.
It is possible to generate identical byte-by-byte outputs from the same source code on two platforms; I have verified this. The first time I saw that the hashes on both sides were exactly the same, I felt a strange sense of emotion, as if two people who had never met before had written the exact same words.
The console is not UTF-8
The default setting for the Traditional Chinese Windows console is cp950, and Python's standard output follows it. If a program prints an emoji or a rare character, it will crash on the code line, and the error message will look like there's a bug in the program itself. You'll debug the program logic, only to find after a long time that the logic is completely correct; it just wanted to print a character that it couldn't print.
When running tests and scripts, bringPYTHONUTF8=1 Enable UTF-8 mode, or explicitly specify the encoding in the program. PEP 686 has decided that UTF-8 mode will be the default starting from 3.15. Until then, this environmental variable will remain in every one of my scripts, like a sticky note that is always attached.
Mini-drama: How many Python programs did I actually install?
"I think I have three Python installations on my computer. Which one should I delete?"
"Don't delete it yet, you don't know which program is using which one."
"How do I know which one I'm using right now?"
"python -c "import sys; print(sys.executable)" It will tell you where you live.
"It printed out a path I had never seen before."
"Congratulations, you've found the fourth one."
Is this normal?
"That's perfectly normal. That's why projects require staff to bring their own copies and not rely on the system's."
Install fewer packages
Use the standard function library whenever possible.sqlite3 ,html.parser ,urllib ,hashlib ,unittest The scope is broader than most people think. Less of a suite means less work on versioning, hashing, and licensing across two platforms.
I know this sounds like an elder saying, "If you can walk, don't take a ride." But when it comes to running Python on Windows, the fewer variables you have, the better. Every package you don't install is like something that won't break down in the middle of the night.
A few tips about Python
Python's name has nothing to do with snakes; it comes from the British comedy troupe Monty Python. Guido van Rossum started writing it during the Christmas holidays of 1989 because he was bored with the office closed. The official documentation is full of examples like "spam" and "eggs," which are references to the comedy group. Knowing this makes the example code feel a bit more familiar.
Every major change to Python goes through a PEP (Python Enhancement Proposal), a public proposal document where everyone discusses and decides. PEP 686, mentioned earlier, is such a document, deciding when UTF-8 mode becomes the default. You can read those PEPs; they contain many discussions about "why it was designed this way," which can help you understand the language's thinking better than any textbook.
Version 3.13 has an experimental "free-threaded" version, the executable file is called...python3.13t It removes the global interpreter lock that has plagued everyone for twenty years. It's still experimental and incompatible with some packages, but it means Python is finally taking multi-threaded performance seriously. I haven't used it in any official projects yet, but I look forward to the day when I can.
Three common misunderstandings
The first misconception is that "Python on Windows is inferior." The core is the same; the differences lie in the peripherals: PATH, encoding, path separators, and the lack of a built-in compiler. There are solutions to these problems; you just need to know them.
The second misconception is that "venv is for isolating packages." Yes, but more importantly, it's for isolating interpreters. A venv remembers which Python version it was built from; if that Python version is missing or changed, the venv breaks down. That's why I insist that the interpreter stays with the project.
The third misconception is that "things installed by pip install are safe." Anyone can upload packages to PyPI; a single misspelled letter in the name could result in installing something someone else intentionally placed there. This includes mismatched lock files and...--require-hashes It's not prejudice, but a reasonable response to the fact that "anyone can upload".
A small exercise you can try over the weekend
Open a terminal on Windows and type...where python See how many it lists. (Call)py -0 See how many versions the launcher recognizes. Then select a folder and use...py -3.13 -m venv .venv Create a venv and open it..venv\pyvenv.cfg Look insidehome That line is where the foundation of this venv resides.
Then, deliberately doing something malicious: renaming the base Python folder and then executing....venv\Scripts\python.exe Watch it die. Change it back, run it again, and it's alive. These five minutes will make you remember forever the invisible line between venv and the interpreter.
Finally, open a new terminal.set PYTHONUTF8=1 Print an emoji. Open another window without any settings and print the same one. Look at the two windows side by side, and you'll understand why that environment variable remains in my script.
Postscript
That afternoon when "nothing happens when you type Python," I later came to regard it as an initiation ritual. Almost everyone who seriously uses Python on Windows has probably experienced it once, and then become ever more vigilant about their PATH. If you haven't experienced it yet, hopefully this article will allow you to skip that afternoon and use your time for something else, like making a cup of tea.
Official website: python.org