Skip to content

🟠 Set up Project Python Environment (managed by uv)

Each project uses its own Python environment stored in a project folder named .venv.

project-repo-name/
  .venv/             # <--- project Python environment
  pyproject.toml
  README.md

This isolates dependencies, prevents conflicts with system Python, and makes the project reproducible on any machine. If something breaks, the .venv/ folder can be deleted and recreated.

Before Starting

You should have already opened the project in VS Code using code ..

Open a VS Code terminal and list the contents of the current folder:

ls

You are in the correct folder when you see files such as:

pyproject.toml
README.md
If you do NOT see those files (click here)

Follow the earlier steps carefully. Continue once you see both pyproject.toml and README.md.

Step 1. Create the Project Environment

Run the following commands in the VS Code terminal to:

  1. Update uv.
  2. Pin the desired Python version for this project (scikit-learn, Apache packages may still need 3.14).
  3. Install/verify the Python version declared by the project.
  4. Update the dependencies listed in the uv.lock file.
  5. Create the .venv environment and install dependencies using uv sync.
uv self update
uv python pin 3.14

uv python install
uv lock --upgrade
uv sync

If prompted: "We noticed a new environment has been created. Do you want to select it for the workspace folder?", click Yes.

NOTE: If uv sync completes successfully but reports that it could not hardlink files and is falling back to copying them, you may continue. This is a performance warning, not an installation failure.

Step 1 Verify

  • A .venv/ folder appears in the project root
  • The command finishes without errors
If this step fails (click here)

uv command not found:

  • Close and reopen VS Code
  • Verify uv was installed during Workflow A. Set Up Machine.

Dependency install error:

  • Delete the .venv/ folder
  • Rerun: uv lock --upgrade
  • Rerun: uv sync

Step 2. Set Up Pre-Commit Hooks

Pre-commit hooks catch common issues before code is committed and pushed to GitHub.

Run the following commands in the VS Code terminal to:

  1. Install the pre-commit Git hooks for this repository
  2. Stage all files (so pre-commit can check them)
  3. Run the checks once explicitly
uv run pre-commit install
git add -A
uv run pre-commit run --all-files

After the hooks are installed, pre-commit checks run automatically on every git commit command.

Step 2 Verify

  • Commands complete without fatal errors
If pre-commit fails

Pre-commit may fail on restricted machines where Git hooks cannot be installed. If this occurs, it is safe to skip pre-commit and continue with the project.

Step 3. Align VS Code with the Project Environment

Step 3.1 Ensure VS Code uses the project .venv/

  1. Open the Command Palette (menu: View / Command Palette, or Ctrl+Shift+P)
  2. Type and choose: Python: Select Interpreter
  3. Choose the interpreter inside this project's .venv folder

Choose Python: Select Interpreter

Choose recommended local .venv

Step 3.2. Reload the VS Code Window

  1. Open the Command Palette (same as before).
  2. Type or choose: Developer: Reload Window

Step 3 Verify

  • VS Code reloads
  • No warnings about missing Python environments appear

◄ Back to 🟠 Workflow C