Python College

Table of Contents

Setup like a pro

Chapter 2

Setup Like a Pro (Python 3.14 Edition)

A professional Python setup isn’t about having the fanciest tools. It’s about removing surprise.

Surprise is what happens when:

  • one project silently upgrades your dependencies and breaks another
  • “Python works” on your machine but not your teammate’s
  • you install a package globally and six weeks later can’t remember where it came from
  • Windows can’t find python, macOS runs a different python3 than you expected, Linux permissions get weird

The goal of this chapter is to give you a setup that is:

  • stable (doesn’t break your OS)
  • repeatable (same commands across projects)
  • portable (macOS / Windows / Linux)
  • team-friendly (easy to explain, easy to debug)

We’ll target Python 3.14 specifically (current downloads are in the 3.14.x line). ([Python.org][1])

The two rules that prevent 90% of Python setup problems

Rule 1: Don’t touch “system Python” for projects

Your operating system may use Python internally—especially on Linux. Treat that installation as owned by the OS.

You can absolutely use it to run Python, but you shouldn’t install project dependencies into it.

Rule 2: One virtual environment per project

Every project gets its own isolated environment:

  • its own pip
  • its own dependency versions
  • its own “it works on my machine” boundary

This is the difference between “Python as a hobby” and “Python as a professional toolchain.”

What we’re going to build

A “pro” baseline that works everywhere:

  1. Install Python 3.14 (prefer official installers on Windows/macOS; use distro packages or a version manager on Linux)
  2. Use .venv per project (built-in venv)
  3. Use pip inside the venv for project dependencies
  4. Use pipx for global CLI tools (so you don’t pollute projects with tool installs) ([pipx.pypa.io][2])

Optionally (recommended once you juggle multiple projects):

  • use a version manager like pyenv or uv (both are common in real teams) ([GitHub][3])

First: confirm what “Python 3.14” means on your machine

Python 3.14 is a major release line, and you’ll typically install a patch version like 3.14.3 (patch releases contain bug/security fixes). The python.org downloads page shows the current latest in the 3.14 series. ([Python.org][1])

After installation, your first verification commands are always:

python3 --version
python3 -m pip --version

On Windows, also:

py --version
py -0p

(We’ll explain py in the Windows section.)

macOS (Python 3.14)

macOS is usually smooth—until you accidentally mix multiple Pythons. The fix is simple: pick a primary installation method, then verify your PATH.

Option A: Official python.org installer (simple, predictable)

  1. Download Python 3.14.x for macOS from python.org. ([Python.org][1])
  2. Install it (standard macOS installer flow).
  3. Verify:
python3 --version
which python3
python3 -m pip --version

You want python3 --version to show 3.14.x.

Why this is “pro”

  • You’re aligned with the reference distribution
  • Tooling and docs match what most people assume

Option B: Homebrew (great if you already live in brew)

Homebrew can install Python 3.14 specifically via [email protected]. ([Homebrew Formulae][4])

brew install [email protected]

Verify:

python3 --version
which python3

One important note about Homebrew

Brew can also install “python” (unversioned), which may advance to newer versions. If your book/project targets 3.14, installing [email protected] keeps you anchored.

macOS: create your first professional project environment

This is the workflow you’ll reuse constantly.

mkdir hello314
cd hello314

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip --version
python --version

At this point, python --version should report 3.14.x, and your pip is the one inside .venv.

Install a dependency:

python -m pip install requests
python -c "import requests; print(requests.__version__)"

Freeze for reproducibility:

python -m pip freeze > requirements.txt

When you’re done:

deactivate

Pro habit: always run pip through python

Inside a venv, prefer:

python -m pip install ...

It guarantees you’re installing into the interpreter you’re actually using.

macOS: install global CLI tools safely with pipx

You’ll want tools like linters, formatters, cookiecutters, REPL helpers, build tools. Installing them into every project is wasteful, and installing them globally with pip gets messy.

pipx installs each CLI tool into its own isolated environment and exposes the executable on your PATH. ([GitHub][5])

On macOS:

brew install pipx
pipx ensurepath

Or using Python’s pip (also valid):

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Now you can do:

pipx install ruff
pipx install pytest

(We’ll talk about these tools later; the point is: pipx keeps tools clean.)

Windows (Python 3.14)

Windows setup is extremely workable, but you have to understand one key concept:

On Windows, the Python Launcher (py) is your best friend.

It exists specifically to locate and run installed Python versions. ([Python Enhancement Proposals (PEPs)][6])

Install Python 3.14 from python.org

Go to python.org downloads and choose the Windows installer for Python 3.14.x. ([Python.org][1])

During installation, you’ll typically want:

  • ✅ Add Python to PATH (helpful)
  • ✅ Install the launcher (py) (very helpful)

After installing, open PowerShell and verify:

py --version
python --version
py -0p

What py -0p tells you

It lists installed Python versions and their paths, which is incredibly useful when debugging “wrong Python” problems.

The official Windows docs also note that once you install the Python install manager/launcher, python may point to your “current latest” installation and can change as versions are added/removed—another reason py is so useful. ([Python documentation][7])

Create a virtual environment on Windows (PowerShell)

mkdir hello314
cd hello314

py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1

python --version
python -m pip install --upgrade pip

If activation is blocked by PowerShell policy, set it for your user:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then activate again.

Install a dependency:

python -m pip install requests
python -c "import requests; print(requests.__version__)"
python -m pip freeze > requirements.txt

Deactivate:

deactivate

Pro tip: specify the version you mean

When you want Python 3.14 specifically:

py -3.14 --version
py -3.14 -m venv .venv

This keeps you honest, especially if you have multiple versions installed.

Windows: pipx for global tools

Install pipx:

py -m pip install --user pipx
py -m pipx ensurepath

ensurepath makes sure the pipx apps directory is on your PATH (you may need to restart the terminal). ([packaging.python.org][8])

Then:

pipx install ruff
pipx install pytest

Linux (Python 3.14)

Linux is the most variable because distributions ship different versions at different times.

Your choices are:

  • Use the distro Python if it’s already 3.14 (or if 3.14 isn’t required for your work yet)
  • Use a version manager to install Python 3.14 without touching system Python (recommended for consistency across machines)

Python 3.14 is a stable release line (3.14.0 released Oct 7, 2025), and patch releases follow. ([Python.org][9])

Baseline: install venv tools from your distro

Example (Debian/Ubuntu-ish):

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

Then:

python3 --version
python3 -m venv --help

If this reports Python 3.14.x, you’re good.

Create a project venv (Linux)

mkdir hello314
cd hello314

python3 -m venv .venv
source .venv/bin/activate

python --version
python -m pip install --upgrade pip

Pro path on Linux: install Python 3.14 with a version manager

When your distro doesn’t ship 3.14 yet (or you want identical versions across machines), a version manager keeps your system clean.

Option A: pyenv (classic, widely used)

pyenv installs Python versions into your user space and lets you choose a version globally or per directory. ([GitHub][3])

High-level steps:

  1. Install build dependencies (varies by distro; Ubuntu/Debian commonly needs build libs)
  2. Install pyenv
  3. Install Python 3.14.x:
pyenv install 3.14.3
pyenv local 3.14.3
python --version

Then you can create a venv using that Python.

Option B: uv (modern, very fast)

uv can install Python and manage environments, designed to be fast and cross-platform. ([Astral Docs][10])

One nice thing about uv is that it can handle “get me Python 3.14” without you wiring up compilers manually on many systems, and it has explicit commands for installing Python versions. ([Astral Docs][11])

(You can keep using venv + pip even if you use uv to install Python. Don’t feel forced into an all-or-nothing tool switch.)

The “real book” workflow: the setup you’ll reuse for every project

Here’s the setup I expect in a professional repository:

  1. Python version is known (3.14.x)
  2. Each project has .venv
  3. Dependencies are recorded
  4. Tools are consistent across contributors

Step 1 — Create project and venv

macOS/Linux

mkdir my_project
cd my_project
python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell

mkdir my_project
cd my_project
py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1

Step 2 — Upgrade pip inside the venv

python -m pip install --upgrade pip

Step 3 — Install project dependencies

python -m pip install requests

Step 4 — Record dependencies (two common styles)

Style A: requirements.txt (simple, common)

python -m pip freeze > requirements.txt

Style B: “top-level deps” + lock (more controlled)

Many teams keep a short list of direct deps and generate a fully pinned lock file. If you’re early in your journey, start with Style A and upgrade later.

Setup your editor like a pro (without overcomplicating it)

No matter which editor you use, professionals want three things:

  • the editor uses the project interpreter (.venv)
  • formatting is consistent
  • linting catches issues early

The one editor rule that matters

Make sure your editor is pointed at:

  • .venv/bin/python (macOS/Linux)
  • .venv\Scripts\python.exe (Windows)

If your editor uses a different Python, you’ll see weird behavior like:

  • imports failing in the editor but working in terminal
  • linting complaining about missing packages you installed
  • different Python versions between runs

Global tools: what belongs in pipx vs inside the project

A clean mental model:

Install via pipx (global CLI tools)

  • formatters / linters (ruff)
  • test runners (pytest) optional to keep global
  • scaffolding tools (cookiecutter)
  • CLI utilities (httpie, pip-tools, etc.)

pipx is designed exactly for this “install CLI tools, keep them isolated” use case. ([GitHub][5])

Install inside the project venv

  • runtime dependencies (requests, fastapi, numpy)
  • project-specific tooling that must match the project (certain plugins, pinned toolchains)

Many teams install pytest and ruff inside the project to guarantee versions. Others keep them global via pipx. Either can be “pro”—the key is consistency.

Troubleshooting: the professional “doctor commands”

When Python behaves strangely, don’t guess. Inspect.

macOS/Linux doctor commands

Outside venv:

which python3
python3 --version
python3 -m pip --version

Inside venv:

which python
python --version
python -m pip --version
python -c "import sys; print(sys.executable)"

Windows doctor commands (PowerShell)

py --version
py -0p
where python
python --version
python -c "import sys; print(sys.executable)"

If sys.executable isn’t pointing into .venv, you’re not running the environment you think you are.

Common “pro” mistakes (and fixes)

Mistake: installing packages globally

Symptom: your project works… until it doesn’t. Or a new project breaks an old one.

Fix: always create .venv and install dependencies there.

Mistake: mixing multiple Python installations on macOS

Symptom: python3 changes depending on terminal, or VS Code uses a different interpreter than your shell.

Fix: pick one install path (python.org or brew), verify which python3, and set your editor interpreter explicitly.

Mistake: Windows “python opens Microsoft Store”

Symptom: typing python triggers Store prompts.

Fix: use py (launcher) and ensure the official Python install + launcher is present. The launcher exists exactly to solve this problem. ([Python Enhancement Proposals (PEPs)][6])

Chapter recap

A professional Python 3.14 setup looks like this:

  • Install Python 3.14.x from a trusted source (python.org is the baseline; Homebrew on macOS is fine; Linux may need pyenv/uv).
  • Use .venv per project
  • Use python -m pip ... to avoid installing into the wrong interpreter
  • Use pipx for global CLI tools to keep things clean
  • On Windows, prefer py to reliably select Python versions
Previous
Iteration patterns
Next
Your first workflow

Enjoying this chapter?

Back to Guide