[Python Series 2] Set Up a Python Environment with uv on macOS

In Part 1, we discussed why we chose Python. Now, let's take action and set up our Python environment using a tool called uv. When you decide to learn Python, the first milestone is ensuring "my computer can run Python code reliably."

Key terms

1. Homebrew: A package manager that installs macOS apps and CLIs with a single command.
2. Virtual environment: An isolated Python runtime per project so package versions never collide.

Core ideas

Study memo

• Time required: 30–40 minutes
• Prereqs: macOS with Homebrew installed and basic terminal experience
• Goal: Create a project with uv and run the first Python file

uv ties together Python installation, virtual environments, package management, and execution. That keeps commands short and makes it trivial to recreate the environment later.

Code examples

Install uv

If you use Homebrew, run:

brew install uv

Check the version afterward:

uv --version

There is also an official install script, but Homebrew is the most familiar path on macOS.

Quick glossary:

• uv: An all-in-one CLI that handles virtual environments, dependency installs, and execution.
• Virtual environment (project-local runtime): keeps package versions from conflicting across projects.

Create a project folder

We'll make a python-playground project.

uv init python-playground
cd python-playground

This command drops in a basic Python project skeleton.

Build the execution environment

Why each project needs its own environment

Every project may rely on different package versions. A virtual environment isolates installations so they never clash.

uv venv

This creates a .venv directory.

Do you have to activate it?

Not necessarily. When you run uv run ..., uv automatically uses the project environment, so you can start without activation.

Activate manually if you prefer:

source .venv/bin/activate

You'll see the .venv prefix in your prompt:

(.venv) MacBook-Pro python-playground $

Any package installs performed now stay scoped to this project.

Run the first Python file

Create main.py:

name = "MathBong"
print(f"Hello, {name}!")

Execute it through uv:

uv run main.py

Expected output:

Hello, MathBong!

Install a package

Add requests as an example:

uv add requests

This not only installs the dependency but also records it for the project.

Practical example: quick report summary

Install rich to render tables in the terminal.

uv add rich

from rich.console import Console
from rich.table import Table

console = Console()
table = Table(title="Daily Summary")
table.add_column("Task")
table.add_column("Status")

table.add_row("Data collection", "Done")
table.add_row("Report writing", "In progress")

console.print(table)

Managing install and execution through uv means a teammate can clone the repo and simply run uv run python main.py to reproduce the same output.

Why it matters

uv run handles launching Python, so you rarely type python3 directly at first. If needed, uv python install can even manage Python itself. Editors like VS Code or Cursor work the same way—point the interpreter at .venv to get accurate IntelliSense and runtime behavior.

Success for this step equals:

• Running uv --version
• Preparing a project with uv init and uv venv
• Executing uv run main.py

Follow that sequence and you can rebuild the environment from scratch with the exact same commands.

Practice

• Follow along: Create a new folder and reproduce the uv init, uv venv, uv run main.py flow.
• Extend: Add a package like rich, print a different table, and capture the install command plus the output.
• Debug: Run uv run main.pyy to trigger an error, read the message, then correct the filename and rerun.
• Definition of done: You see uv run output in a fresh project and have the command history saved.

Wrap-up

Before memorizing syntax, learn to control your runtime. Starting with uv keeps package installs, execution, and reproducibility simple.

Next time we will connect variables, data types, and the input–output flow through tight examples.