Muralidhar Kashipathi's blog

uv for data science practitioners

Python Project Management with uv:

Setting up a python environment was an adventure and used to take a good chunk of time. Package Conflict was a part of life for data science practitioners. UV is a ray of hope.

Here are two checklists that I am using to help me with this part of work.

Checklist 1: Setting Up a NEW Python Project with uv

Prerequisite: Ensure uv is installed globally on your system (pipx install uv)

Steps:

  1. Create Your Project Folder:

    mkdir your_new_project_name cd your_new_project_name

  2. Initialize Your Virtual Environment:

    uv venv

  3. Activate Your Virtual Environment:

    Windows Command Prompt

    .venv\Scripts\activate

    Linux / macOS / WSL

    source .venv/bin/activate

    (Verify (.venv) appears in your prompt)

  4. Define Your Dependencies (pyproject.toml):

    Create a pyproject.toml file in your project root and add your project metadata and declared dependencies under the [project] table.

    Example pyproject.toml snippet:

    pyproject.toml

    [project] name = "your-new-project" version = "0.1.0" requires-python = ">=3.8" dependencies = [ "requests2.31.0", "fastapi0.111.0", "uvicorn[standard]==0.30.1", ]

  5. Generate Your Lock File (requirements.txt):

    This command reads pyproject.toml and creates a precise requirements.txt with all exact versions and hashes:

    uv pip compile pyproject.toml --output-file requirements.txt

  6. Install Dependencies into Your Environment:

    This installs everything from your requirements.txt lock file into your active virtual environment:

    uv sync

  7. (Optional but Recommended) Configure Git:

    • Add .venv/ and __pycache__/ to your .gitignore file to prevent committing generated files
    • Ensure pyproject.toml and requirements.txt ARE committed

  8. Adding New Packages (The Easy Way):

    Add packages directly with uv:

    uv add pandas==2.0.3

    This command will:

    • Automatically add the package to your pyproject.toml
    • Update your lock file (requirements.txt)
    • Install the package in your active environment

    If the package doesn't install automatically, run:

    uv sync

  9. Removing Packages:

    To remove a package:

    uv remove pandas

    This will automatically update both files and uninstall from your environment.

Checklist 2: Porting an EXISTING Project to a New Environment with uv

This checklist assumes you've received a project (e.g., cloned from Git) that already has pyproject.toml and a requirements.txt lock file.

Prerequisite: Ensure uv is installed globally on your system (pipx install uv).

Steps:

  1. Get the Project Code:

    git clone

    Or download and extract the project files

  2. Navigate into the Project Directory:

    cd your_project_name

  3. (Verify Files Present):

    Confirm that pyproject.toml and requirements.txt (the lock file) are present in the project root.

  4. Create a New Virtual Environment:

    uv venv

  5. Activate Your Virtual Environment:

    Windows Command Prompt

    .venv\Scripts\activate

    Linux / macOS / WSL

    source .venv/bin/activate

    (Verify (.venv) appears in your prompt)

  6. Install Dependencies from the Lock File:

    uv sync

    This command will read the existing requirements.txt lock file and rapidly install all the exact, pinned dependencies into your new virtual environment.

#python_tools #til #uv