beginner25 minby DevFox

Installing Python Without Breaking Your Machine

Why your computer may already have a Python you should not use, how versions coexist, and getting to a working setup you can trust on macOS, Windows or Linux.

Python

You follow a tutorial, type python, and get an error saying the command does not exist. Or worse, it works — and prints Python 2.7.18, a version that reached the end of its life in 2020, and every example you try behaves oddly for reasons nobody explains.

Installation is the step most likely to make a beginner quit, and almost none of that is your fault. It is confusing because your computer probably already has a Python, that Python is not for you, and the internet is full of advice that quietly assumes a different operating system from yours. By the end of this lesson you will have a Python you chose, know why you must not touch the other one, and be able to tell which is which.

The Python already on your machine

If you use macOS or Linux, there is a Python on your computer right now. You did not install it. It is there because the operating system itself uses it — parts of the system are written in Python and need an interpreter to run them.

This is called the system Python, and the important thing about it is that it does not belong to you.

Think of the boiler in a rented flat. It is in your kitchen, you can reach it, and it would be an odd decision to start rearranging its parts because you wanted hot water somewhere else. It is there to run the building.

Two things follow. The system Python is often an older version than you want, because the operating system upgrades it on its own schedule. And if you install packages into it, or upgrade it, or remove something it depended on, you can break system tools that had nothing to do with your project. That failure is memorably unpleasant to diagnose, because the thing that breaks is not the thing you touched.

So the rule is: leave the system Python alone, and install your own.

The system Python

Belongs to the operating system.

Usually at /usr/bin/python3. Upgraded on the operating system's schedule, not yours.

Installing packages into it can break system tools that had nothing to do with your project.

The one you install

Yours. Break it freely.

Under /opt/homebrew, /usr/local, or a .pyenv folder.

Whatever you do to it, the operating system keeps working. That is the entire reason to have a second one.

Two Pythons on one machine, and only one of them is yours to change

Why there are so many versions

Python releases a new version once a year — 3.11, 3.12, 3.13 — and supports each for about five years. Two consequences reach you immediately.

The first is that a version number is not decoration. Code written for a newer Python can use syntax an older one does not recognise, and will fail with a confusing message rather than a helpful one. When something works on a colleague's machine and not on yours, the version is the first thing to compare.

The second is the python versus python3 business. When Python 3 arrived, Python 2 was everywhere, so python kept meaning "Python 2" to avoid breaking the world, and python3 was added for the new one. Python 2 is now long dead, but the naming survived on many systems.

bash

python --version     # may not exist, or may be an ancient 2.7
python3 --version    # this is the one you want

Type both. Whatever python3 reports is what you are actually working with, and if that number does not start with 3.1, this lesson has a job to do.

Installing one you chose

There is more than one reasonable way to do this. Pick one, use it consistently, and do not mix them — most installation misery comes from having installed Python three different ways and no longer knowing which one answers when you type a command.

On Windows, get the installer from python.org and run it. One thing on the first screen matters more than everything else:

text

[x] Add python.exe to PATH      <- tick this

PATH is the list of places your computer looks when you type a command. If Python is not on it, your terminal will insist Python is not installed while you are looking at the folder containing it. If you already installed without ticking it, run the installer again and choose Modify.

On macOS, the usual route is Homebrew, a package manager for software that does not come from the App Store:

bash

brew install python@3.12    # installs alongside the system one
python3 --version           # confirm which one answers now

On Linux, your distribution's package manager already has it:

bash

sudo apt install python3 python3-pip python3-venv   # Debian, Ubuntu
sudo dnf install python3 python3-pip                # Fedora

The python3-venv part matters on Debian and Ubuntu, which split it into a separate package. Without it, a tool you will need in a later lesson fails with an error that does not mention the missing package at all.

When several versions live together

Sooner than you expect, you will need two versions at once — one project written for 3.11, another needing 3.13. Installing Python again over the top does not solve this; it gives you a confusing mixture.

The tool for this job is a version manager, which keeps several Pythons side by side and lets you say which one applies where. The widely used ones are pyenv and, more recently, uv.

bash

# pyenv: install two versions, pick a default and a per-folder one
pyenv install 3.12.7
pyenv install 3.13.1
pyenv global 3.12.7        # the default everywhere
cd ~/projects/older-thing
pyenv local 3.11.9         # just this folder, recorded in a file

You do not need this today. You need to know the word, so that when a project says "requires Python 3.11" and you have 3.13, you reach for a version manager rather than uninstalling what works.

Bad — solving a version conflict by replacing what you have.

bash

brew uninstall python@3.13
brew install python@3.11     # now the other project is broken

Good — keeping both and choosing per project.

bash

pyenv install 3.11.9
cd ~/projects/older-thing
pyenv local 3.11.9           # only this folder changes

The first version turns one stuck project into two, alternating, forever — and each swap takes a download and a rebuild. The second takes the same time once and then never again, because the version is recorded next to the project that needs it rather than in your global setup.

Checking what you actually have

When something is wrong, guessing is expensive and asking is free. Three questions, and each one narrows the problem.

Which version answers?
python3 --version. If it does not start with 3.1, the rest of this lesson has a job to do.
Where does that command live?
which python3 on macOS and Linux, where python on Windows. /usr/bin/python3 means you are talking to the system Python; anything under /opt/homebrew, /usr/local or .pyenv means you are talking to your own.
Still unsure? Ask the interpreter itself
python3 -c "import sys; print(sys.executable)" prints the exact file being used, with no guessing about which command found what.

Run all three whenever a Python surprises you

The second question is the one people forget, and it is the one that explains the mysteries. When a package you definitely installed cannot be found, this is almost always the reason: you installed it into one Python and are running another.

Installing packages, carefully

Most of Python's usefulness comes from packages — code someone else wrote that you can install and use. The tool that installs them is pip.

bash

python3 -m pip install requests    # install a package
python3 -m pip list                # what is installed?

Write it as python3 -m pip rather than pip. The two look identical and are not: pip on its own is whichever pip your PATH finds first, which may belong to a different Python than the python3 you are running. python3 -m pip means "the pip belonging to this exact Python", which removes an entire category of confusion where a package installs successfully and then cannot be imported.

There is a second, larger idea here — that packages should be installed per project rather than for your whole machine, so two projects can want different versions of the same package without a fight. That is what virtual environments are for, and they get a proper lesson later in this course. For now, install sparingly and know the phrase.

A cheat sheet to keep

text

FINDING OUT WHAT YOU HAVE
  python3 --version                 which version answers
  which python3                     where it lives (macOS, Linux)
  where python                      where it lives (Windows)
  py --version                      the Windows launcher
  python3 -c "import sys; print(sys.executable)"
                                    the exact file, no guessing

INSTALLING
  Windows    python.org installer, TICK "Add to PATH"
  macOS      brew install python@3.12
  Debian     sudo apt install python3 python3-pip python3-venv
  Fedora     sudo dnf install python3 python3-pip

SEVERAL VERSIONS AT ONCE
  pyenv install 3.12.7              add a version
  pyenv global 3.12.7               the default everywhere
  pyenv local 3.11.9                just this folder

PACKAGES
  python3 -m pip install requests   install for THIS python
  python3 -m pip list               what is installed

RULES
  leave the system python alone     it runs your operating system
  never sudo pip install            that is the system python
  prefer python3 -m pip to pip      removes a whole class of bug
  pick one install method           mixing them is the usual mess

Where to go next

You now have a Python you chose rather than inherited, you can find out which one is answering when a command surprises you, and you know why the one that came with your machine is not the one to build on. That last point will save you a bad afternoon at some stage.

Next is Values, Names, and Types, where the course stops being about your machine and starts being about the language. It begins with the thing every program does before it does anything else: holding on to a piece of information and giving it a name you can use later.

Before you move on, run the three checking commands and read what they say — the version, the location, and sys.executable. Write the answers down somewhere. In a month, when something mysterious happens, comparing those three lines against what you see then will identify the problem faster than any amount of searching.