Why Setting Up Python on Windows Trips People Up
“I followed the tutorial exactly, so why won’t it work?” — Sound familiar? A huge number of people hit a wall when trying to set up a Python environment on Windows, and the cause almost always comes down to two key issues.
Why Does Typing “python” Do Nothing?
If you type python in Command Prompt or PowerShell and get a “not recognized” error, the culprit is almost certainly a missing PATH entry. PATH is the list of folders Windows searches when you run a command. If you unchecked “Add Python to PATH” during installation, Windows has no idea where Python lives — so the command simply doesn’t work.
Heads up: If typing python opens the Microsoft Store instead, the issue is Windows’ “App Execution Aliases” setting. Go to Settings → Apps → App Execution Aliases and toggle off python.exe to fix it.
Get the Big Picture Before You Dive In
Before jumping into individual steps, it helps to understand the overall flow so you don’t lose your bearings.
Following these steps in order will save you from the most common headaches — version conflicts and package interference — that tend to show up later. The next sections walk through each step one by one.
Choosing Your Install Method: Official Installer vs. pyenv-win
The PATH issues and version conflicts mentioned earlier are usually triggered by picking the wrong installation method. This section lays out both options by use case, so you can figure out which one is right for you.
The Official Installer Is All You Need for a Single Version
If you’re learning Python for the first time or only need one version, the official installer from python.org is the simplest and most reliable choice.
When the official installer makes sense
- You’re just getting started with Python
- You’re working on a single project with a fixed version
- You don’t want to spend time managing tooling
The only thing to watch out for is making sure you check “Add Python to PATH” during installation. Miss that box and you’ll immediately run into the PATH problem described in the previous section.
For Multiple Versions, pyenv-win Is the Way to Go
When you’re juggling multiple projects simultaneously, you’ll inevitably end up needing Python 3.10 for Project A and 3.12 for Project B. Trying to manage multiple official installs manually leads to messy PATH priority conflicts where the wrong version gets called unexpectedly.
When pyenv-win makes sense
- You need different Python versions for different projects
- You need to match the version used by your team
- You plan to upgrade Python versions over time
That said, to be honest, pyenv-win requires a few extra setup steps on Windows — things like configuring PowerShell’s execution policy and setting up paths. The initial setup has a bit more of a learning curve for complete beginners, so keep that in mind.
Which Should You Choose? A Quick Decision Guide
| Situation | Recommendation |
|---|---|
| First time using Python | Official installer |
| Learning only, single version | Official installer |
| Running multiple projects in parallel | pyenv-win |
| Team development with a specific version requirement | pyenv-win |
If you’re still unsure, use this rule of thumb: “Just want to write code right now? Go with the official installer. Want a proper dev environment from the start? Go with pyenv-win.” The next sections cover the step-by-step instructions for each.
Setting Up Python with the Official Installer
As covered in the previous section, the official installer is the fastest route for anyone new to Python. Before learning any extra tools, let’s get a working environment up and running first.
Downloading the Installer from the Python Website
Open your browser, go to python.org, and click the “Download Python 3.x.x” button from the “Downloads” section on the homepage. The page automatically detects that you’re on Windows and offers the 64-bit installer (.exe file).
Which version to pick
Just grab the latest release listed under “Stable Releases” — that’s all you need. Avoid anything labeled “pre-release,” as those are still in development and not recommended for beginners.
The One Option You Must Check: Add to PATH
Run the downloaded file and the installer’s welcome screen will appear. The single most important thing here is to check “Add python.exe to PATH”. Skip this and Python won’t be recognized from the command line, and you’ll have to reinstall.
- Check “Add python.exe to PATH”
- Click “Install Now” (no customization needed)
- If “Disable path length limit” appears, click that too
You’ll be given two options — “Install Now” and “Customize installation.” Beginners should always go with “Install Now.” Customizing risks overwriting the PATH settings.
Verifying the Installation from Command Prompt
Once the installation is complete, search for “cmd” in the Start menu to open Command Prompt and type the following:
python --versionIf the version number you installed appears (e.g., Python 3.12.x), you’re good to go. If you see an error like 'python' is not recognized as an internal or external command..., the PATH change may not have taken effect yet. Close the Command Prompt window and reopen it — that usually fixes it.
Quick verification commands
python --version— displays the installed Python versionpip --version— confirms pip, Python’s package manager, is working
If both commands return output without errors, your environment is ready.
Managing Multiple Python Versions with pyenv-win
Even after installing Python with the official installer, the day will come when a different project needs a different version. That’s exactly where pyenv-win comes in handy.
What is pyenv-win?
pyenv-win is a Windows port of “pyenv,” a version manager originally built for macOS and Linux. It lets you switch between multiple Python versions with a single command.
How to Install pyenv-win
Launch PowerShell as Administrator and run the following commands in order.
-
1Install via winget
winget install pyenv-win -
2Add the paths to your environment variables
Add both%USERPROFILE%\.pyenv\pyenv-win\binand%USERPROFILE%\.pyenv\pyenv-win\shimsto your system’s PATH environment variable. -
3Verify the installation
Open a new terminal and runpyenv --version. If a version number appears, you’re all set.
Commands for Installing and Switching Python Versions
Here are the commands you’ll use most often. If it’s your first time, start with pyenv install --list to see all available versions.
| Action | Command |
|---|---|
| List available versions | pyenv install --list |
| Install a specific version | pyenv install 3.11.9 |
| List installed versions | pyenv versions |
| Check the active version | pyenv version |
Global vs. Local Settings: When to Use Each
pyenv-win has two configuration levels — “global” and “local” — and knowing when to use each one is key.
Setting the global version
pyenv global 3.11.9
Sets the default Python version for your entire system. Use this for any Python work outside of a specific project.
Setting the local version
Navigate to your project folder with cd your-project-folder, then run pyenv local 3.10.14.
This creates a .python-version file in that directory, and pyenv will automatically use the specified version whenever you’re inside it.
In practice, the standard approach is “global for the latest stable release, local locked per project.” For team development, committing the .python-version file to your Git repository ensures everyone on the team is using the same version.
How to Set Up VS Code as Your Main Editor
Once you have pyenv-win set up to manage multiple Python versions, it’s time to get an editor ready for writing code. Visual Studio Code (VS Code) is currently the most widely used editor for Python development. Despite being completely free, it handles code completion, debugging, and virtual environment switching all in one window — a huge advantage.
Installing VS Code and the Python Extension
Download the Windows installer for VS Code from the official Microsoft website. During installation, make sure to check “Add to PATH” — this lets you open any folder in VS Code from the terminal by typing code .
Launch VS Code and click the Extensions icon (four squares) in the left sidebar
Type “Python” in the search bar and install the official “Python” extension by Microsoft
Confirm that “Pylance” is also installed (it’s usually auto-installed alongside the Python extension)
Important: Always choose the official Microsoft extension. Unofficial extensions with the same name can appear in search results, so verify that the Publisher field shows “Microsoft” before installing.
Selecting an Interpreter and Creating a Virtual Environment (venv)
Installing the extension alone isn’t enough — VS Code still doesn’t know which Python to use. Selecting an interpreter means telling VS Code “this project should use this specific Python.” This is especially important when managing multiple versions with pyenv-win.
To keep each project’s dependencies isolated, you’ll also want to create a virtual environment (venv). A virtual environment is a self-contained Python runtime dedicated to a single project, and it’s the standard way to prevent package version conflicts.
Open your project folder in VS Code and launch the terminal (Ctrl + `)
Create a virtual environment with the following command
python -m venv .venvOpen the Command Palette (Ctrl + Shift + P), type “Python: Select Interpreter,” and choose the Python inside .venv
Restart the terminal — if you see (.venv) at the beginning of the prompt, the virtual environment is active
Common question: The folder name .venv is just a convention — you can use any name you like. Just make sure to add it to .gitignore so it doesn’t get tracked by Git.
Running Your First .py File
Once your environment is set up, the fastest way to confirm everything works is to actually run some code.
Create a new file in VS Code and save it as hello.py
Type the following line
print("Hello, Python!")In the terminal, type python hello.py and press Enter
If Hello, Python! appears in the terminal, VS Code is running scripts correctly. You can also use the “▷” button in the top-right corner, but getting comfortable with the terminal approach will pay off when you need to pass arguments or work with the debugger.
- Is the virtual environment active when you select the interpreter?
- Did you save the file (
Ctrl + S) before running it? - Is the terminal’s current directory the same folder as your file?
These three points are where most beginners get tripped up. If you hit an error, check them in this order first.
Common Errors and How to Fix Them
Right after setting up your environment is the most likely time to run into confusing errors. Here’s a quick rundown of the three most common issues beginners face, from root cause to resolution.
‘python’ is not recognized as an internal or external command
When you type python in Command Prompt or PowerShell and get this message, there’s almost always one cause: you didn’t check “Add Python to PATH” during installation, so Windows has no idea where Python lives.
First, check this
Search for “environment variables” in the Start menu and open “Edit the system environment variables.” Look inside “Path” and verify that Python’s installation path (e.g., C:\Users\YourUsername\AppData\Local\Programs\Python\Python3xx\) is listed there.
If the path isn’t there, the most reliable fix is to uninstall Python and reinstall it — this time making sure to check “Add Python.exe to PATH.” You can also add the path manually, but for beginners, a clean reinstall is less error-prone.
pip install fails or throws an SSL error
When trying to install a package with pip install, you might see an error like SSL: CERTIFICATE_VERIFY_FAILED. This tends to happen in corporate or school network environments with a proxy, or when the system’s certificate store isn’t being referenced correctly.
Quick workaround (temporary fix)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org package-name
This skips SSL verification temporarily. For security reasons, this isn’t recommended as a permanent setting.
For a proper fix, update Python to the latest version from the official site, or update the certificate library with pip install --upgrade certifi. If the issue is caused by a corporate proxy, you may need to check with your IT department.
How to reset when you have multiple Python versions installed
Ending up with two or more Python installations is a common scenario — it can happen after running the installer multiple times, or by installing from both the Microsoft Store and the official Python website. When versions get mixed up, the python command and the pip command can end up pointing to different Python installations, which causes all kinds of confusion.
Run where python in PowerShell and count how many paths are returned
Go to Settings → Apps → Installed apps and uninstall every Python-related entry
Remove all Python-related entries from the “Path” environment variable to get a clean slate
Download and install a single version from the official site. Avoid mixing the official installer with the Microsoft Store version
After resetting, run both python --version and pip --version and confirm they show the same version number. If the paths match, the conflict is resolved.
Recap: Key Points for a Solid Python Setup on Windows
We’ve covered everything from installation and virtual environments to common error fixes. It might seem like a lot of steps, but building a solid foundation upfront makes everything that follows much smoother.
For beginners: the official installer + VS Code is the fastest path
There are several ways to set up Python — Anaconda, pyenv, the Microsoft Store, and more — but the best starting point for beginners is the official installer from python.org combined with VS Code. It keeps things minimal while giving you access to a wealth of English documentation and community resources, making it easier to find answers when you get stuck.
Recommended setup by use case
- Learning Python basics: Official installer + VS Code
- Data analysis / machine learning: Anaconda (includes Jupyter Notebook out of the box)
- Advanced users who need multiple versions: pyenv-win + venv
When in doubt, start simple and add tools only when you actually need them. Trying to install everything at once is a reliable recipe for conflicts and headaches.
Next learning steps after your environment is ready
With your environment in place, the top priority is writing and running actual code. Use the steps below as a roadmap.
Python has one of the richest learning ecosystems of any programming language. The official documentation at docs.python.org is a great first stop. You’ve already cleared the hardest hurdle — getting your environment set up — so now is the best time to build momentum and keep going.
Comments