Python setup and the most common errors: a step-by-step troubleshooting guide

Short answer

Setting up Python means downloading the official installer for your operating system, making sure Python is added to your PATH, and confirming the version from the command line. Most errors come from PATH configuration, confusing python with python3, or skipping a project virtual environment.

This guide covers a first-time install and a shared team environment: installation per operating system, then the most common error messages and their fixes.

What is Python, and who is it a good starting point for?

Python is a general-purpose language built around readability. Web applications, data analysis, automation and machine learning all run on it, because the learning curve stays low while the ecosystem stays large.

• Automation: scripting repetitive file, report and data tasks
• Data and reporting: turning CSV, spreadsheet and database data into summaries
• Web and APIs: services and corporate integration layers
• Machine learning: running existing models on your own data

Before installing, decide which Python version to standardise on: for a new project, the current stable release of the Python 3 family. The python.org download page lists which versions are supported.

Installing Python on Windows, step by step

On Windows, the official installer from python.org is the most reliable route.

1. Download the stable Windows installer from the download page.
2. Run it and tick Add Python to PATH at the bottom of the setup screen.
3. Start the default installation and let it finish.
4. Close the window, then open a new command prompt; open terminals keep the old PATH.

Skip that checkbox and Python installs but the command line cannot find it, which causes nearly every python is not recognized error on Windows. The optional components are not needed, and because the recommended install method changes across releases, follow the official Windows setup page.

Installing Python on macOS

macOS has two common routes: the official installer and Homebrew. Download and run the macOS installer from python.org and the python3 command becomes available. Since python does not always point at Python 3 on macOS, writing python3 is safer.

Homebrew needs one command:

brew install python

The interpreter that ships with macOS is reserved for the system’s own tooling; use the version you installed yourself plus virtual environments instead of installing packages into it.

Installing Python on Linux

Most Linux distributions ship with Python 3 already. Verify the version, then fill in the gaps with the distribution’s package manager.

Debian and Ubuntu:

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

Fedora and Red Hat:

sudo dnf install python3 python3-pip

The virtual environment module is a separate package on some distributions; without python3-venv, the venv command fails. Check which interpreter is called with which python3.

Verifying the installation: python –version

Ask the command line for the version; it is the only reliable confirmation.

python --version
python3 --version
py --version

Which one works depends on your system, and you do not need all three. A Python 3 version number means the install is complete.

To see which directory the interpreter runs from:

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

This prints the full path of the Python that will receive your packages: if the path you expected and the one on screen differ, your packages are going elsewhere.

PATH problems and python is not recognized / command not found

PATH is the environment variable that tells your system which directories to search for commands. If Python is installed but not found, the PATH definition is almost always the problem.

• Windows: python is not recognized as an internal or external command means the PATH option was not checked during setup; reinstalling with it checked is the fastest fix.
• macOS and Linux: command not found usually just means you need python3 rather than python.
• Homebrew: make sure your shell configuration adds the Homebrew directory to PATH.

Calling the interpreter by its full path is a temporary workaround; correcting PATH is the lasting fix, or every new terminal session repeats the error.

Version management and the py vs python3 difference

Several Python versions on one machine is normal; most projects require it.

• On Windows, the py launcher lists installed versions and lets you choose.
• On macOS and Linux, python3 calls Python 3, while python may point elsewhere.
• With a virtual environment active, python is bound to that environment’s interpreter.

To list installed versions on Windows:

py --list

Pinning a version per project keeps that decision off individual machines, and a virtual environment confines the complexity to the project boundary.

pip and the “pip not found” error

pip installs Python packages. When pip is not found, call it through the interpreter instead:

python3 -m pip --version
python3 -m pip install --upgrade pip

This leaves no doubt about which Python receives the package. On Windows the same command is py -m pip.

Newer distributions block direct installs into the system Python:

error: externally-managed-environment

That is a deliberate guard: the distribution is preventing pip from overwriting files its own package manager controls. Do not force it with sudo; create a virtual environment. For system-wide tools, pipx runs each one in its own isolated environment.

Why a virtual environment (venv) is essential

A virtual environment is an isolated directory that separates a project’s packages from other projects and the system Python:

python3 -m venv .venv

Activate it on macOS and Linux:

source .venv/bin/activate

In Windows PowerShell:

.venv\Scripts\Activate.ps1

The environment name appears in your prompt, and packages install there:

python -m pip install requests

Three things make this essential: projects needing different versions of the same package no longer collide, operating system tooling stays intact, and whoever inherits the project installs the same dependencies at the same versions.

The 7 most common errors and how to fix them

ModuleNotFoundError: No module named …

The package was most likely installed into a different interpreter. Confirm the virtual environment is active, install with python -m pip install, and compare with the output of sys.executable.

PermissionError: [Errno 13] Permission denied

This usually means installing into a system directory. The fix is a virtual environment, not sudo. Running pip with sudo can corrupt files managed by the system package manager, creating problems that are far harder to untangle later.

SSL certificate errors

On a certificate verification failure, first check whether your installation has a certificate bundle; on macOS, the official installer’s Python may need certificates installed with a separate command. On a corporate network, a proxy re-signing traffic causes the same error, and the organisation’s root certificate has to be trusted by the system.

UnicodeDecodeError and garbled characters

If non-ASCII characters look wrong, the file is being read without a declared encoding. State it explicitly:

from pathlib import Path

text = Path("notes.txt").read_text(encoding="utf-8")
print(text)

An encoding declaration at the top of a source file also helps. If a Windows console garbles output, switching its code page to UTF-8 usually resolves it.

IndentationError and TabError

Python defines blocks by indentation. Mixing tabs and spaces raises TabError; a missing indent raises IndentationError. Configure your editor to convert tabs into four spaces and both disappear permanently.

The wrong Python version running

If code does not behave as expected, the interpreter may not be the version you think. Print the version and interpreter path to confirm. An active virtual environment removes this ambiguity.

pip package build failures

Some packages are compiled during installation. On Windows the install stops when no compiler is found: use a prebuilt binary or install the build tools. On Linux, missing header files cause the same failure, resolved by the distribution’s development packages. The error’s first lines usually name the missing component.

Setting up an editor: VS Code

Visual Studio Code is enough to start. After installing it, add the Python extension: its most important function is choosing the project’s interpreter, so run the interpreter selection command from the command palette and pick the virtual environment’s interpreter.

The editor’s terminal inherits that interpreter, so command line version confusion does not repeat there, and leaving indentation settings on prevents most indentation errors.

A first project suggestion

Verify your setup with a small script that does something real. Reading the CSV files in a folder and printing their row counts is a good start:

import csv
from pathlib import Path

for path in sorted(Path(".").glob("*.csv")):
    with path.open(encoding="utf-8", newline="") as handle:
        rows = list(csv.DictReader(handle))
    print(f"{path.name}: {len(rows)} rows")

This uses file paths, encoding and loops in one place. A natural next step is installing a web framework into the same environment and writing a small HTTP service. Starting from a real need, such as automating a weekly report assembled by hand, makes the learning stick faster.

In a corporate setting, Python rarely stands alone; it earns its value as an automation and integration layer connecting to existing systems, alongside data ownership and maintenance decisions. We cover that in our corporate software solutions guide; for a project built from scratch, see our custom software projects.

Checklist

Once installation is done, verify the following:

• The interpreter version can be read from the command line.
• pip reports its version when called through the interpreter.
• Each project has its own virtual environment.
• The prompt shows the environment name once it is active.
• The editor has the correct interpreter selected.
• Dependencies are recorded in a requirements list.
• File operations declare an encoding.
• Setup choices are written down, so a new team member can reproduce them.

If all of these hold, most environment errors are eliminated at the start. For official details, see Python’s setup and usage documentation and the downloads page.

Next step

Set up properly, Python installation takes minutes; the real time sink is ambiguity around PATH, versions and virtual environments. Settling those up front removes most repeating errors. If that code is deployed to a server, SSH and essential Linux commands covers the basics, and keeping the environment maintainable is part of the technical debt conversation.

If you want a Python-based automation, data processing or integration layer for your team, our group company Web Tasarım Ofisi supports web projects with technical foundations and sustainable maintenance. To talk through your scope, get in touch.