uv, the Python virtual environment and package management tool

,

1. Python package

  • Module: A single python file (.py) containing code (functions, classes, variables)
  • Package: A collection of modules organized in directories, recognized by the presence of an init.py file (usally it is empty) within each directory. Packages can contain sub-packages.
  • Dependency: An extenal python package (or a specific version of it) that the project requires to function correctly.
  • Virtual Environment: An isolated python environment that allows to install packages for a specific project without interfering with other projects or the global pthon installation. This is the most crucial concept for robust python development.
  • Dependency Specification:
    • requirements.txt: A plain text file listing direct dependencies, typically generated using pip freeze. While simple, it often lists all transitive dependencies, making it hard to manage top-level requirements.
    • pyproject.toml: The modern, standardized way to declare project metadata and dependencies. It’s a TOML(Tom’s Obvious, Minimal Language) file that serves as a central configuration for various python tools. It allows to direct dependencies for project.
    • Lock file(uv.lock,poetry.lock, etc.): A file generated by a package manager (like uv or poetry) that lists all direct and transitive dependencies with their exact, pinned versions and hashes. This ensures absolute reproducibility of the environment.

2. uv

uv is new, extemely fast Rust-based package and project manager that aims to replace pip, pip-tools, venv, and potentially poetry for many workflows.

  1. install uv

    1
    pip install uv

  2. create a new project and initialize

    1
    2
    3
    mkdir project_folder
    cd project_folder
    uv init # Initializes a new project, creates pyproject.toml

  3. Explicitly create venv
    this is not necassary as adding the first depency will auto execute it.

    1
    2
    3
    uv venv
    uv venv --python 3.10
    uv python pin 3.10

  4. Add denpendencies:
    This adds the package to pyproject.toml and installs it into your virtual environment, also generating uv.lock

    1
    2
    3
    uv add fastapi uvicorn pydantic-settings
    # For dev dependencies (e.g., pytest, black):
    uv add pytest black --dev

  5. Install Dependencies (from pyproject.toml and possible lock file):
    if we clone a project or share it, others can quickly get set up.

    1
    uv sync

install on specific package

1
uv add dependency_name
1
uv pip install dependency_name  # Install all dependencies from pyproject.toml and uv.lock

  1. Run Scripts/Commands within the environment:
    uv provides a run command to execute scripts using the project’s virtual environment

    1
    2
    uv run uvicorn app.main:app --reload
    uv run pytest

  2. List Installed Packages:

    1
    uv pip list

  3. Upgrade Dependencies:

    1
    2
    uv update # Upgrades all dependencies to their latest compatiable versions and updates uv.lock
    uv update fastapi # Upgrade a specific package

  4. Remove Dependencies:

    1
    uv remove fastapi

  5. (Optional) Generate requirements.txt (if needed for compatibility):
    While uv.lock is preferred for uv users, if you neeed a requirements.txt for deployment systems that expect it:

    1
    uv pip freeze > requirements.txt