Setup Guide: Python, uv, and VS Code

Overview

This guide walks you through everything required to get set up, end to end:

  • Installing Python
  • Installing uv
  • Installing and configuring VS Code
  • Creating a project-based Python environment
  • Running code successfully

This is a one-time setup. Once completed, you will reuse this workflow all semester.

Note

Read this once, then follow it top-to-bottom.
Most setup problems happen when steps are skipped or done out of order.

Prerequisite

This guide assumes you know how to:
- open Terminal (Mac) or PowerShell (Windows)
- run a command
- copy/paste commands
- recognize when a command succeeds or fails

If not, complete the short Terminal Basics video and guide before continuing.

What you will have when you’re done

By the end of this guide, you should have a project folder that looks like this:

CLASS_FOLDER/
├── pyproject.toml
├── .venv/
└── hello.py

And you should be able to: - open this folder in VS Code - run Python code using the project environment - install packages in a repeatable way

Tip

If your folder does not look like this at the end, stop and fix it before moving on.

Phase 1 — Install Required Tools

1. Install Python (3.xx)

This text works with Python 3.12 or higher.
Examples below use Python 3.13.

Important

If you already have Python installed, you still need to verify the version and that it runs from the terminal.

macOS

  1. Download Python from https://www.python.org
  2. Run the installer (accept defaults)
  3. Verify in Terminal:
python3 --version
pip3 --version

Windows

  1. Download Python from https://www.python.org
  2. Check “Add Python to PATH” during install
  3. Verify in PowerShell:
python --version
pip --version
Warning

If python is “not recognized,” restart your terminal first.
If it still fails, Python was not added to PATH.

If pip is not recognized but python -m pip works, this is normal on Windows. See more below

On some Windows systems—especially with newer Python versions (3.13+)—you may see this behavior:

python --version
# works

pip --version
# pip is not recognized as a command

This does not mean Python or pip is broken. What’s happening is this:
- Python is correctly installed - pip exists inside Python - The pip launcher is not on your PATH - You can confirm pip is installed by running:

python -m pip --version

Later in the course when you are installing new packages you can use pio through python by following this template:

python -m pip install <package>
python -m pip --version

2. Install uv

uv manages your project, environment, and packages.

Note

Do not install uv using plain pip install uv.
Modern systems intentionally block this to protect your Python installation.

macOS

Option A — Homebrew (if you already use it)
brew install uv
uv --version
Option B — pipx (no Homebrew required)
python3 -m pip install --user pipx
python3 -m pipx ensurepath

Restart your terminal, then:

pipx install uv
uv --version

Windows

Option A — winget
winget install uv
uv --version

Some users may encounter an error here…something like : “multiple packages found matching input criteria…”. If this happens, try using the ID field in the table that winget produces. For example:

winget install astral-sh.uv
uv --version

Note: this may take a little work, and some frustration.

Option B — pipx
python -m pip install --user pipx
python -m pipx ensurepath
pipx install uv
uv --version
Tip

If uv is “not found,” close and reopen your terminal.
This fixes most PATH-related issues.

3. Install VS Code

  1. Download from https://code.visualstudio.com
  2. Install using defaults
    • On Windows, check Add to PATH
  3. Open VS Code

Install the Python extension

  • Extensions → search Python
  • Install Python (by Microsoft)
Important

VS Code will not work correctly for Python until the Python extension is installed.

Phase 2 — Create Your Project

4. Create a project folder

Choose a location (Documents recommended).

macOS

mkdir -p ~/Documents/CLASS_FOLDER
cd ~/Documents/CLASS_FOLDER

Windows

mkdir $HOME\Documents\CLASS_FOLDER
cd $HOME\Documents\CLASS_FOLDER
Note

Avoid spaces in folder names.
Use letters, numbers, and hyphens only.

5. Initialize the project

uv init
uv venv

You should now see: - pyproject.toml - .venv/

Warning

If you do not see .venv, you are not in the correct folder.

6. Add a test package

uv add rich
Tip

Using uv add both installs the package and records it in pyproject.toml.

7. Create a test file

Create hello.py:

from rich import print
print("[bold green]Hello from Python + uv + VS Code![/bold green]")

Phase 3 — Connect VS Code to the Project

8. Open the folder in VS Code

  • File → Open Folder…
  • Select CLASS_FOLDER
Important

Open the folder, not just the Python file.
VS Code needs the folder to find .venv.

9. Select the Python interpreter

  1. Command Palette
    • macOS: Cmd + Shift + P
    • Windows: Ctrl + Shift + P
  2. Choose Python: Select Interpreter
  3. Select the interpreter inside .venv
Warning

The wrong interpreter is the #1 cause of “ModuleNotFoundError.”

Phase 4 — Run Code (Choose One Style)

You only need one of the following approaches.
Pick one and use it consistently.

Option B — No activation (uv-managed)

uv run python hello.py
Tip

This avoids activation entirely and is often easier on Windows.

Troubleshooting

“ModuleNotFoundError”

Warning

This almost always means Python is running outside the project environment.

Checklist: - VS Code interpreter is set to .venv - You are in the project folder - You activated .venv or used uv run

“uv: command not found”

  • Restart your terminal
  • Re-run pipx ensurepath (pipx installs)

Final checkpoint

Important

Do not move on until all of the following work.

  • python --version
  • uv --version
  • hello.py runs successfully
  • VS Code shows the .venv interpreter