Skip to content

python_uv.md

Latest commit

 

History

History
165 lines (111 loc) · 5.46 KB

python_uv.md

File metadata and controls

165 lines (111 loc) · 5.46 KB
Raw

Setting up Python and UV

The sections below detail the steps to implement a clean Python install along with UV for environment management.

Fully UV-managed setup

UV can manage Python itself - you do not need to install Python manually or worry about Anaconda PATH conflicts. This is the simplest and most reproducible path for new projects.

Install UV

In a terminal (PowerShell or CMD on Windows):

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

or on Unix-like systems (Linux/macOS):

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

Verify the installation:

uv --version

Note

Explanation of the Windows command:

  • irm = Invoke-RestMethod - downloads the install script from the web
  • iex = Invoke-Expression - executes the downloaded script immediately
  • -ExecutionPolicy ByPass - temporarily bypasses script execution restrictions (required if your system blocks scripts)

Install and pin a Python version with UV

  1. Install a specific Python version via UV (no separate installer needed):

    uv python install 3.13

  2. Pin that version to your project by writing a .python-version file at the project root:

    uv python pin 3.13

    This file should be committed to the repository so all collaborators use exactly the same Python version.

Initialise and sync a project

uv init
uv sync

Because .python-version is present, uv init will link the virtual environment to the pinned Python version automatically.

uv init initialises a new UV-managed project in the current folder:

  • .venv/ - a local virtual environment (isolated Python environment for this project)
  • pyproject.toml - declares your project metadata and dependencies
  • uv.lock - locks dependency versions for reproducible installs
  • Detects your system Python interpreter and links the .venv to it

uv sync reads pyproject.toml (and uv.lock if present) and:

  • Installs all declared dependencies into the .venv
  • Ensures the Python environment matches the lockfile exactly so collaborators get the same package versions
  • Updates the lockfile if necessary

Tip

This approach eliminates the need to install Python from python.org, manually edit the system PATH, or manage conflicts with existing Anaconda installations. The Python version is declared in .python-version and locked in uv.lock, making the environment fully reproducible across machines.

Install and manage dependencies with UV

  1. Install a package and add it to pyproject.toml:

    uv add package-name==0.0.1

    This installs the necessary package versions inside the .venv, not globally, and also updates pyproject.toml and uv.lock, making them a project dependency, so that uv sync installs it automatically for others. Later, anyone running uv sync will get the same versions installed in their .venv.

  2. Add a development-only dependency (e.g. testing or formatting tools):

    uv add --dev pytest
uv add --dev black

    Dev dependencies are recorded under [dependency-groups] in pyproject.toml. They are installed locally with uv sync but are excluded when running uv sync --no-dev (e.g. in production or Docker builds), keeping runtime images lean.

  3. Remove a package:

    uv remove package-name

    This uninstalls the package and removes it from pyproject.toml and uv.lock.

  4. Update packages:

    uv lock --upgrade-package package-name   # update a specific package
uv lock --upgrade                         # update all packages

    After upgrading, run uv sync to apply the changes to the .venv.

  5. Run a script without manually activating the venv:

    uv run python script.py

    uv run automatically uses the project's .venv, making it useful for one-off executions, CI pipelines, and scheduled jobs where you do not want to manage activation.

  6. If you do need to activate the venv manually (e.g. for interactive work in a terminal):

    # Windows CMD
.venv\Scripts\activate.bat

# PowerShell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

  7. Run uv sync and push the updated pyproject.toml and uv.lock to the repository for other users.

Sync an existing project with UV

  1. Clone repository and pull latest version:

    git clone https://github.com/your-org/your-project.git
cd your-project
git pull

  2. Sync the project:

    uv sync

    This single command will:

    • Create a .venv using the pinned Python version from .python-version
    • Install all dependencies from your pyproject.toml and uv.lock
    • Ensure exact versions match so your environment is identical to the repository

  3. Open a script in VSCode, select the Python interpreter from your project's .venv (Ctrl+Shift+P → Python: Select Interpreter → .venv), and run it