Resolving Common Python Setup Errors: A Comprehensive Guide

Common Python Setup Errors and Fixes: PATH, pip, venv, VS Code, Jupyter, and Permissions

Quick Answer

Most Python setup errors come from one of five causes:

1. The terminal cannot find Python.
2. pip is installing into the wrong Python.
3. The virtual environment is not active.
4. The IDE selected the wrong interpreter.
5. Jupyter selected the wrong kernel.

Last verified: June 9, 2026.

Official Links

• Python downloads: https://www.python.org/downloads/
• Python venv docs: https://docs.python.org/3/library/venv.html
• pip docs: https://pip.pypa.io/en/stable/
• uv docs: https://docs.astral.sh/uv/
• VS Code Python docs: https://code.visualstudio.com/docs/languages/python
• Jupyter install: https://jupyter.org/install

The First Debugging Rule

Before fixing anything, identify the Python being used.

Windows:

python --version
py --version
py -m pip --version
py -0p
pymanager help
pymanager list
where.exe python
where.exe py
where.exe pymanager

macOS:

python3 --version
python3 -m pip --version
which python3
echo $PATH

Inside Python:

python -c "import sys; print(sys.executable)"

1. python is not recognized On Windows

Cause:

• Python is not installed
• terminal was not restarted
• PATH is missing
• Windows Store alias is intercepting python

Fix:

py --version
py -0p
pymanager list
where.exe py
where.exe pymanager

If py works, use:

py script.py
py -m pip install package-name

If py -0p works but py list fails, Windows is using the legacy Python Launcher. That is usable. Use py -0p to list runtimes and py -3.14 when you want Python 3.14.

If python opens Microsoft Store:

1. Open Windows Settings.
2. Search App execution aliases.
3. Turn off aliases for python.exe and python3.exe.
4. Restart PowerShell.

If nothing works, reinstall from:

https://www.python.org/downloads/

2. py list Fails With A Legacy Launcher Warning

Symptom:

WARNING: The 'list' command is unavailable because this is the legacy py.exe command.

Cause:

• Python Install Manager may be installed.
• But Windows finds the older Python Launcher first when you type py.

Safe diagnosis:

py --version
py -0p
pymanager help
pymanager list
where.exe py
where.exe pymanager

Safe project commands:

# Use the Python that `python` currently points to
python -m venv .venv

# Use Python 3.14 through legacy Python Launcher
py -3.14 -m venv .venv

# Use Python 3.14 through Python Install Manager
pymanager exec -V:3.14 -m venv .venv

Do not remove Python runtimes blindly. If you intentionally want Python Install Manager to own the py command, remove Python Launcher from Windows Installed Apps. Otherwise, keep both and use pymanager list plus py -0p.

3. python3: command not found On macOS

Cause:

• Python 3 is not installed
• Terminal PATH has not refreshed

Fix:

Install from python.org or Homebrew.

python3 --version
which python3

If using Homebrew:

brew install python

Restart Terminal.

4. pip is not recognized

Cause:

• pip is not on PATH
• you are using the wrong command for your OS

Fix:

Windows:

py -m pip --version
py -m pip install requests

macOS:

python3 -m pip --version
python3 -m pip install requests

Do not depend on plain pip until you understand which Python it belongs to.

5. No module named pip

Fix:

python -m ensurepip --upgrade
python -m pip install --upgrade pip

On Ubuntu/Debian:

sudo apt install python3-pip python3-venv

6. ModuleNotFoundError

Example:

ModuleNotFoundError: No module named 'pandas'

Cause:

• pandas is not installed
• package installed into a different Python
• IDE or notebook uses another interpreter

Fix:

python -c "import sys; print(sys.executable)"
python -m pip install pandas
python -c "import pandas as pd; print(pd.__version__)"

In VS Code, run Python: Select Interpreter.

In PyCharm, check Project -> Python Interpreter.

In Jupyter, check the kernel.

7. PowerShell Blocks venv Activation

Error:

running scripts is disabled on this system

Fix for current Windows user:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Close and reopen PowerShell.

Then:

.\.venv\Scripts\Activate.ps1

8. Permission denied During pip Install

Cause:

• installing globally
• system Python is protected

Fix:

Use a virtual environment.

Windows:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install package-name

macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install package-name

9. externally-managed-environment

Cause:

Modern Linux distributions may protect system Python from pip installs.

Safe fix:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install package-name

Avoid --break-system-packages as a beginner. It can damage OS package boundaries.

10. VS Code Uses The Wrong Python

Symptom:

• script runs in terminal
• VS Code says package missing

Fix:

1. Open Command Palette.
2. Run Python: Select Interpreter.
3. Choose .venv.
4. Open a new VS Code terminal.

Check:

python -c "import sys; print(sys.executable)"

It should include .venv.

11. PyCharm Uses The Wrong Python

Fix:

1. Open Settings or Preferences.
2. Go to Project -> Python Interpreter.
3. Select the .venv interpreter.

Windows path:

.venv\Scripts\python.exe

macOS path:

.venv/bin/python

12. Jupyter Kernel Cannot Find Packages

Cause:

Notebook kernel is not your project environment.

Fix:

Activate .venv and install:

python -m pip install jupyterlab ipykernel

Inside notebook:

import sys
print(sys.executable)

If the path is wrong, change the kernel to .venv.

13. jupyter Is Not Recognized

Fix:

python -m pip install jupyterlab
python -m jupyterlab

If that works, the package is installed but the jupyter script is not on PATH. Running it through Python avoids the PATH issue.

14. Network, Proxy, SSL, Or Certificate Errors

Common messages:

ProxyError
SSLError
certificate verify failed
ReadTimeoutError

Fix order:

1. Try a normal browser page to confirm internet works.
2. Try a different network if you are on restricted office or college Wi-Fi.
3. Upgrade pip inside .venv.
4. Ask your network admin for proxy or certificate details if the network requires them.

python -m pip install --upgrade pip

Proxy example:

python -m pip install --proxy http://user:password@proxy.example.com:8080 requests

Certificate example:

python -m pip install --cert path/to/company-ca.pem requests

Avoid copying random --trusted-host commands unless you know why certificate verification is failing.

15. FileNotFoundError

Example:

FileNotFoundError: data.csv

Cause:

• file is not in the current working directory
• path is wrong
• IDE opened a different folder

Fix:

from pathlib import Path

print(Path.cwd())
print(Path("data").exists())

Open the full project folder in your IDE.

16. Clean Reset For A Broken Project Environment

If only the environment is broken, do not rewrite your code.

Delete and recreate .venv.

Windows:

Remove-Item -Recurse -Force .venv
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

macOS:

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Only do this inside the project folder after confirming your code is not inside .venv.

Final Troubleshooting Order

Use this order:

1. Check Python command.
2. Check Python path.
3. Activate .venv.
4. Check pip using python -m pip.
5. Install package.
6. Check IDE interpreter.
7. Check Jupyter kernel.
8. Check current working directory.

FAQ

Why do Python setup problems feel confusing?

Because Python, pip, IDEs, and notebooks can each point to different interpreters. Once you check sys.executable, the confusion usually becomes visible.

Should I reinstall Python for every error?

No. First check PATH, virtual environment activation, and interpreter selection.

Is it safe to delete .venv?

Yes, if your code is not inside .venv. Recreate it from requirements.txt.

Should I use sudo with pip?

Avoid sudo pip. Use a virtual environment.

Final Checklist

Windows:

py --version
py -0p
pymanager help
pymanager list
where.exe python
where.exe py
where.exe pymanager
py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip --version
python -c "import sys; print(sys.executable)"

macOS:

python3 --version
which python3
python3 -m venv .venv
source .venv/bin/activate
python -m pip --version
python -c "import sys; print(sys.executable)"

Find the wrong layer, then fix that layer.

Next in this series: Essential Python Local Setup Checklist for Developers →