Project Setup

This page walks through setting up a Python project and virtual environment using uv. At any point, run uv help <subcommand> (e.g. uv help init) or consult the uv CLI documentation for more information.

Setting up a project

Navigate to the folder where you’d like to initialize the project and run the following command from within that folder.

uv init --python /bin/python3.12

This command will

  • initialize a git repository in the folder if one doesn’t already exist,

  • create a pyproject.toml file storing information about the project and its dependencies,

  • create a minimal main.py file, and

  • create a blank README.md.

The --python flag specifies a particular version of Python. Feel free to change this to another version or omit it entirely to use the default system Python.

Then, to create and activate the virtual environment, run

uv sync  # creates the venv -- only needs to be run the first time you set up the project
source .venv/bin/activate

Installing dependencies

To add dependencies (i.e. install packages), use uv add:

uv add oi-tools polars  # ... and any other packages you may want

This will install the packages into your virtual environment and record them in pyproject.toml. No more manually managing a requirements.txt file!

Adding other users to the project

For another person to use the virtual environment, have them go to the project folder and run source .venv/bin/activate. They will then have access to exactly the same Python environment (same version of Python, same packages, same package versions, etc.).

For projects you use frequently, consider making shell aliases to automate these steps:

# in ~/.bashrc
alias venv="source .venv/bin/activate"
alias proj="cd /path/to/project && venv"

Updating dependencies

uv sync --upgrade-package oi-tools  # upgrade a particular package
uv sync --upgrade  # upgrade all packages to their newest versions

Note that upgrading may break things. Make sure you have a clean git working tree so that you can revert uv.lock if needed.