Installing and Running Python

Updated

September 8, 2026

Installing and Running Python

The boring way to run Python in this book is uv: install it once from astral.sh, pin Python 3.14, and run every file with uv run python. You do not need a distro package named python, a GUI installer, or an IDE before the first script works.

Mental model

A runtime is the program that reads a .py file and executes it. uv is one tool that:

  • installs that runtime (uv python install 3.14)
  • writes down the version the folder expects (.python-version, pyproject.toml)
  • runs a file with that interpreter (uv run python shift.py)

A terminal is the window where you type commands. PATH is the list of directories the shell searches for a program named uv. On macOS and Linux the installer puts uv in ~/.local/bin. If the shell says uv: command not found right after install, close the terminal and open a new one so PATH reloads.

Python source is text. An editor is anything that saves a .py file. Use the editor you already use.

Worked examples

Case 1: Install uv, then Python 3.14

These are terminal commands, not Python programs.

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Confirm uv is on PATH, then install the interpreter this book uses:

uv --version
uv python install 3.14
uv python list

You should see a 3.14 row. In a project folder, pin it so uv run keeps choosing 3.14:

uv python pin 3.14

That writes a tiny file named .python-version whose whole contents are:

3.14

Case 2: Prove the runtime

Save as runtime.py.

# runtime.py
import sys


def main():
    major, minor = sys.version_info[:2]
    print(f"python {major}.{minor}")


if __name__ == "__main__":
    main()

Run:

uv run python runtime.py

Output:

python 3.14

uv run selects a 3.14 interpreter (and will download one if needed), then runs the file. You did not activate a virtual environment by hand.

Case 3: A first desk script

Save as shift.py. Open it in your editor — Zed, VS Code, Neovim, Notepad, TextEdit, whatever you already have. If it can save this file, it is enough.

# shift.py
def main():
    name = "nights"
    tables = 8
    print(f"shift {name}: {tables} tables")


if __name__ == "__main__":
    main()

Run:

uv run python shift.py

Output:

shift nights: 8 tables

Change tables to 9. Save. Run the same command. The number in the output changes. Edit, save, run: that loop is the whole workflow.

Case 4: Write the project down

A project is a folder with a pyproject.toml. You can write the file yourself, or let uv create the same shape:

uv init --bare --name desk --python 3.14

Save this next to shift.py as pyproject.toml:

# pyproject.toml
[project]
name = "desk"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = []

Then:

uv python pin 3.14
uv run python shift.py

Same output as Case 3. requires-python is how you tell a teammate which Python this folder expects. dependencies stays empty until a later chapter needs a package.

A typical first folder looks like this:

desk/
  .python-version
  pyproject.toml
  shift.py

That is enough. Do not add src/, a package name, or a global “system Python” yet.

Case 5: Another file, same command

Save as ticket.py.

# ticket.py
def main():
    ticket_id = 41
    table = 6
    print(f"ticket {ticket_id} sits at table {table}")


if __name__ == "__main__":
    main()

Run:

uv run python ticket.py

Output:

ticket 41 sits at table 6

Every example in this book that you are told to run uses that same command shape: uv run python and the filename.

The trap

Installing “Python” from a website, then another copy from a package manager, then running python3 shift.py with whichever binary is first on PATH. Six months later one machine is 3.11, another is 3.14, and a forgotten pip install wrote packages into a user directory you cannot name.

A second trap: delaying the first script until you have chosen an IDE, a theme, and a plugin pack. The language is text. Highlighting can wait.

The boring rule

  • Install uv from https://astral.sh/uv with the script above.
  • Install the interpreter with uv python install 3.14.
  • Pin it in the project with uv python pin 3.14.
  • Keep a pyproject.toml with requires-python = ">=3.14".
  • Run every example with uv run python file.py.
  • Use the editor you already use. Save as .py.
  • If uv is not found, open a new terminal so PATH updates.

Try this

  1. In runtime.py, also print sys.executable. Run it and read the path — that is the interpreter uv chose.
  2. In shift.py, add a second print for the closer’s name (a string).
  3. Run uv run python --version in the same folder as pyproject.toml. Confirm it reports 3.14.