# Resolving Common Python Setup Errors: A Comprehensive Guide
URL: https://madhudadi.in/blog/posts/resolving-common-python-setup-errors-a-comprehensive-guide
Published: 2026-06-10
Tags: python, setup
Read time: 48 min
Difficulty: beginner
> Fix common Python setup errors: python not recognized, pip not found, ModuleNotFoundError, venv activation blocked, wrong VS Code interpreter, and Jupyter kernel problems.# 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:

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

macOS:

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

Inside Python:

```bash
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:

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

If `py` works, use:

```powershell
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:

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

## 2. `py list` Fails With A Legacy Launcher Warning

Symptom:

```text
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:

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

Safe project commands:

```powershell
# 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.

```bash
python3 --version
which python3
```

If using Homebrew:

```bash
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:

```powershell
py -m pip --version
py -m pip install requests
```

macOS:

```bash
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:

```bash
python -m ensurepip --upgrade
python -m pip install --upgrade pip
```

On Ubuntu/Debian:

```bash
sudo apt install python3-pip python3-venv
```

## 6. `ModuleNotFoundError`

Example:

```text
ModuleNotFoundError: No module named 'pandas'
```

Cause:

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

Fix:

```bash
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:

```text
running scripts is disabled on this system
```

Fix for current Windows user:

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

Close and reopen PowerShell.

Then:

```powershell
.\.venv\Scripts\Activate.ps1
```

## 8. `Permission denied` During pip Install

Cause:

- installing globally
- system Python is protected

Fix:

Use a virtual environment.

Windows:

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

macOS:

```bash
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:

```bash
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:

```bash
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:

```text
.venv\Scripts\python.exe
```

macOS path:

```text
.venv/bin/python
```

## 12. Jupyter Kernel Cannot Find Packages

Cause:

Notebook kernel is not your project environment.

Fix:

Activate `.venv` and install:

```bash
python -m pip install jupyterlab ipykernel
```

Inside notebook:

```python
import sys
print(sys.executable)
```

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

## 13. `jupyter` Is Not Recognized

Fix:

```bash
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:

```text
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.

```bash
python -m pip install --upgrade pip
```

Proxy example:

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

Certificate example:

```bash
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:

```text
FileNotFoundError: data.csv
```

Cause:

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

Fix:

```python
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:

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

macOS:

```bash
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:

```powershell
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:

```bash
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.