Creating a project with uv

Real Python projects get messy fast. One project needs Python 3.14 and one set of packages, another needs a different version and different packages, and they mustn't get in each other's way.

Python comes with a tool called pip for installing packages, but it leaves the rest of the setup to you. uv is a newer, much faster tool that does the whole job: it picks the right Python version, creates a separate space for each project's packages, called a virtual environment, and installs packages into it.

Step 1: Install uv

macOS: in the VS Code terminal, run:

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

Windows: in the VS Code terminal (Git Bash), run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close VS Code completely, open it again and check it worked:

uv --version

Stuck?Show hints

uv: command not found: you didn't restart VS Code. Close it completely, not just the terminal, and open it again.

Step 2: Create the project

In the VS Code terminal, go to your course folder and create a project called learn-python inside a week-02 folder:

cd ~/projects/fde-course
mkdir -p week-02
cd week-02
uv init --no-package --python ">=3.14" learn-python
cd learn-python
code .

uv init creates a new project.
--no-package keeps it a simple project with a main.py file, which is all you need for now.
--python ">=3.14" says the project needs Python 3.14 or newer. If you don't have it, uv downloads it for you, without touching the Python you installed yourself.

code . opens the project in a new VS Code window. Use that window from now on.

Step 3: Run it

uv has written a small starter program in main.py. Run it:

uv run main.py

The first time, you'll see something like this. Your version number may be different:

Using CPython 3.14.4
Creating virtual environment at: .venv
Hello from learn-python!

uv run creates the virtual environment if it doesn't exist yet, then runs your code with the project's Python instead of the one on your computer. From now on, run your Python files with uv run instead of python3.

What uv created

File or folder	What it's for
`pyproject.toml`	The project's settings: its name, the Python version it needs and the packages it uses
`.python-version`	The exact Python version uv uses for this project
`main.py`	The starter program
`README.md`	An empty README for you to fill in
`.venv/`	The virtual environment, created the first time you run `uv run`. It's hidden, and never committed to Git.
`uv.lock`	The exact version of every package installed, so the project installs the same way on any computer

If you run uv init outside a Git repository, it also creates a .git folder and a .gitignore for you. Your project is inside fde-course, which is already a repository, so it doesn't.

The uv commands you'll use

Command	What it does
`uv init`	Creates a new project
`uv run file.py`	Runs a file with the project's Python and packages
`uv add package-name`	Installs a package and records it in `pyproject.toml`
`uv sync`	Creates the virtual environment if it's missing and installs everything listed in `pyproject.toml`. Use it after you clone someone else's project.

Stuck?Show hints

uv run main.py says the file doesn't exist: you're in the wrong folder. Run cd ~/projects/fde-course/week-02/learn-python and try again.
There's a src folder and no main.py: you left out --no-package. Delete the learn-python folder and run uv init again with it.