7. Troubleshooting common issues

If something on the previous pages didn't work, the fix is almost certainly here. Eight common setup problems, each with diagnostic signatures and fixes for Windows, macOS, and Linux. Find the issue that matches your error message and follow the steps.

This section contains solutions for the most common setup problems. Issues are numbered so earlier sections can reference them directly. Don't read this section linearly. Use it as a reference when you encounter specific errors.

Issue 1: Python not found

Error message.

'python' is not recognized as an internal or external command

Or:

command not found: python

What this means. Python isn't installed, or it's installed but not in your system's PATH (the list of locations your command line searches for programs).

Windows

1. Go to https://python.org/downloads
2. Download Python 3.13 or 3.14 (the big yellow button)
3. Important. Check "Add Python to PATH" at the bottom of the installer
4. Click "Install Now"
5. After installation, close and reopen your command prompt

Verify: python --version should now show Python 3.10+

macOS

macOS may include an older Python, but you need a current Python 3 install. Two options:

Option A: Download from python.org (recommended)

1. Visit https://python.org/downloads
2. Download the macOS installer
3. Run the .pkg file and follow installation prompts

After installation, use python3 instead of python for all commands.

Option B: Install with Homebrew

If you have Homebrew installed:

brew install python3

Linux

Most Linux distributions include Python 3. If not:

sudo apt update
sudo apt install python3 python3-pip python3-venv

sudo dnf install python3 python3-pip

sudo pacman -S python python-pip

After installation, verify with python3 --version

Issue 2: pip not found

Error message.

'pip' is not recognized as an internal or external command

What this means. pip isn't installed or isn't in your PATH. This is unusual since pip comes with Python 3.4+, but it happens.

Try pip3 first

On some systems, pip for Python 3 is called pip3:

pip3 --version

If this works, use pip3 only when working outside a virtual environment. Once your virtual environment is active, prefer python -m pip so pip and Python stay matched.

Run pip through Python

You can run pip as a Python module:

python -m pip --version

This almost always works. If it does, you can install packages with python -m pip install package-name

Linux

On some Linux distributions, pip needs to be installed separately:

sudo apt install python3-pip

Issue 3: virtual environment won't create

Error message.

No module named venv

What this means. The venv module isn't installed. This typically happens on Linux where venv is a separate package.

Linux

sudo apt install python3-venv

sudo dnf reinstall python3

On Fedora, recent Python 3 installs include the standard-library venv module. The python3-virtualenv package installs a different third-party tool and does not fix python3 -m venv.

Then try creating your virtual environment again:

python3 -m venv my-first-api-env

Issue 4: virtual environment won't activate (Windows)

Error message.

cannot be loaded because running scripts is disabled on this system

What this means. Windows PowerShell's execution policy blocks script execution for security. You need to allow scripts you created locally to run for your user account.

Open PowerShell normally, then change the execution policy:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Type Y and press Enter to confirm.

Now try activating your virtual environment again in the same PowerShell window.

Alternative: use Command Prompt instead

If you don't want to change PowerShell settings, use Command Prompt (cmd) instead. Virtual environment activation works without any policy changes in cmd.

Issue 5: activation script not found

Symptom. Running the activation command produces "file not found" or similar errors.

Cause. Either the virtual environment wasn't created successfully, or you're not in the right directory.

First, verify the environment folder exists:

ls my-first-api-env/bin/activate

dir my-first-api-env\Scripts\activate.bat

If you get an error, the environment wasn't created. Delete it and start over:

rm -rf my-first-api-env
python3 -m venv my-first-api-env

rmdir /s /q my-first-api-env
python -m venv my-first-api-env

Shell-specific activation

Different shells use different activation scripts:

my-first-api-env\Scripts\activate.bat

source my-first-api-env/bin/activate.csh

Issue 6: permission denied when installing packages

Error message.

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: '/path/to/site-packages'
Consider using the `--user` option or check the permissions.

On Debian, Ubuntu, and other distributions that protect the system Python, you may instead see this:

error: externally-managed-environment

This environment is externally managed

What this means. You're trying to install to system Python, or you're not in an activated virtual environment.

The fix is the same: install packages inside your project environment. Check for the (my-first-api-env) prefix. If it's missing:

# Windows
cd %USERPROFILE%\api-projects
my-first-api-env\Scripts\activate

# macOS/Linux
cd ~/api-projects
source my-first-api-env/bin/activate

Then install:

python -m pip install requests

Issue 7: requests module not found

Error message.

ModuleNotFoundError: No module named 'requests'

Most common cause. Mismatch between where requests is installed and which Python is running.

Step 1: check which Python you're using

which python

where python

Step 2: check whether requests is installed

python -m pip show requests

If "Location" doesn't match your virtual environment path, requests is installed elsewhere.

Make sure your virtual environment is active (look for the prefix), then:

python -m pip install requests

Test again:

python

>>> import requests
>>> requests.__version__

If Python prints a version number, requests is installed in the environment you're using. If the import still fails, exit Python with exit(), reactivate my-first-api-env, and run python -m pip install requests again.

Issue 8: command line basics not working

Symptoms. Commands like cd, ls, or mkdir don't work, or you're confused about where you are in the file system.

Try this sequence to build comfort:

# See where you are
pwd  # or 'echo %CD%' on Windows Command Prompt

# Go to home directory
cd ~  # or 'cd %USERPROFILE%' on Windows

# List what's in this folder
ls  # or 'dir' on Windows

# Navigate into your api-projects folder
cd api-projects

# Confirm you're in the right place
pwd  # or 'echo %CD%' on Windows Command Prompt

If you get lost, cd ~ (or cd %USERPROFILE% on Windows) always takes you back to your home directory.

Getting more help

If you encounter an error not covered here, you're not alone. Millions of developers have hit the same issue. Here's how to find solutions:

1. Copy the error message. Select the error text from your terminal and copy it. Remove any personal information like your username or file paths.
2. Search Google. Paste the error message in quotes: "your error message here". Add "Python" or "pip" to narrow results.
3. Check Stack Overflow. Stack Overflow (stackoverflow.com) has answers to virtually every setup error. Look for answers with green checkmarks (accepted solutions) and high vote counts.
4. Python official documentation. The official Python docs (docs.python.org) have detailed installation guides for every platform.

Learning to search for error solutions is a core development skill. Professional developers search for errors constantly. It's not a sign of weakness; it's how development works. Error messages are clues, and the internet has the answers. Build this habit early.