Modernizing Python Development: My Switch to UV
Summary of Common UV Commands # Install UV - multiple options available ###################################################### # Windows powershell -ExecutionPolicy ByPass -c "irm <https://astral.sh/uv/install.ps1> | iex" winget install --id=astral-sh.uv -e # Linux/macOS curl -LsSf "https://astral.sh/uv/install.sh" | less brew install uv # Python pipx install uv # alternative is pip uv --version # or 'uv self version' uv --help # --help can be used with all commands uv self update # Update UV itself # Install and Manage Python ###################################################### uv python install # Install latest Python version uv python install 3.10.5 # Install specific Python version uv python install --default # Add python.exe to $HOME\.local\bin\ uv python install --reinstall # Reinstall uv-managed Python versions uv python list # List available Python versions uv python list --managed-python # Only list managed Python versions uv python list --no-managed-python # Only list system Python versions uv python upgrade 3.14 # Install the latest patch version uv python uninstall 3.10.5 # Uninstall version uv python find 3.14 # Show path for a specific python.exe uv run where <exe_name> # Show path(s) of all <exe_name>.exe uv python pin 3.14 # Use a specific version in the _current directory_ # Creates a .python-version file # UV Uninstall uv cache clean # Optional, but recommended rm -r "$(uv python dir)" # Optional, but recommended rm -r "$(uv tool dir)" # Optional, but recommended rm $HOME\.local\bin\uv*.exe # Windows rm ~/.local/bin/uv ~/.local/bin/uvx # Linux/macOS # Run Python ###################################################### uv run python # REPL with default version uv run <script>.py # Default version uv run -p 3.14 <script>.py # Specific version, --python alias uv run python [py_option] # Standard Python cmd options uv run --with <pkg> <script>.py # Include dependency package # Multiple --with allowed # Can use UVX, but take care when trying to run pytest, mypy, etc uvx python@3.14 <script>.py # Specific version # Create Virtual Environment (venv) ###################################################### uv venv # Use the default Python version uv venv <venv_name> # Specify the venv name uv venv --python 3.14 # Specify the Python version for the venv uv venv --prompt <prmt> # Alternative prompt prefix for the venv uv venv --seed # Add the pip module to the venv # Activate venv's .venv\Scripts\activate # PowerShell source .venv/bin/activate # Linux/macOS deactivate # Add Dependencies - normally into current venv ###################################################### # Will add to pyproject.toml, uv.lock and sync the venv uv add <pkg1,...> # Add one or more dependencies to the project # Version Specifiers allowed, e.g. rich>13.9.1 uv add -r requirements.txt # Add all in the given `requirements.txt` uv remove <pkg1,...> # Remove dependencies from the project # pyproject.toml [dependency-groups] uv add --dev <pkg1,...> # Add to the development group uv add --group test <testpkg> # Add to user named `test` group uv add <azurepkg> --optional azure # Add Optional to 'azure' group # Remove is the same # Requires a pyproject.toml uv tree # View the project dependency tree uv tree --outdated --depth 1 # View latest available versions uv pip tree # View the environment dependency tree # Update packages # 1: Update uv.lock file to version in pyproject.toml uv lock --upgrade uv lock --upgrade-package <pkg> # 2: call 'uv sync' to update your venv from lock file uv sync # Sync environment from uv.lock # Add/Update InLine Script Metadata (PEP 723) uv add --script <script> <pkg1 ...> # Can pass a requirements file with '-r' # Can set Python version with '--python' # Export the project's lockfile to an alternate format uv export --no-annotate --no-dev --no-emit-workspace --no-header --no-hashes --output-file requirements.txt # pylock.toml (PEP 751) also supported # 'uv.lock' file created first time a UV proj cmd is run # i.e., uv run, uv add, uv sync, uv lock uv lock # Manually create lock file uv lock --check # Check if the lockfile is up-to-date # Manage Python packages with a pip-compatible interface ###################################################### # You should have done 'uv venv --seed' to use these uv pip list # List packages installed uv pip install <pkg1 pkg2..> # Install package into an environment uv pip install -p 3.14 <pkg> # Install into specific version # Install packages into the system Python environment (non-virtual) uv pip install --system <pkg> # Allow UV to modify an `EXTERNALLY-MANAGED` Python installation uv pip install --system --break-system-packages <pkg> # Create UV Project Areas ###################################################### uv init # Create in CWD, default proj type = --app uv init <proj_name> # Create a default named project uv init --bare # Only create a pyproject.toml uv init --app # Application project - this is the default uv init --package # Package project uv init --lib # Library project uv version # Project version as listed in pyproject.toml # Build Project ###################################################### uv build # Build Lib/Pkg using UV or specified Build-Backend # UV Tools ###################################################### # Run Tools uvx <tool> # UVX is an alias for 'uv tool run' uvx <tool@version> # Specify Tool Version: <tool@version> uvx <tool>@latest # Latest Tool Version uv cache clean # Deletes all entries in the cache # Install Tools uv tool install <tool> # [install | uninstall | upgrade] uv tool install <tool>@latest # Install latest version of <tool> uv tool update-shell # Ensure Tool Exe on path (if not already) # Tool Info uv tool dir # Installed source uv tool dir --bin # Installed executable uv tool list # List Installed Tools Simple Library Project Creation - PowerShell Commands # Powershell $proj_name = Read-Host 'What is your-project-name?' $proj_underscores = $proj -replace '-', '_' mkdir $proj_name cd $proj_name # Create a library uv init --lib # auto creates hello() in ./src/$proj_name/__init__.py # Use Dependency Groups (PEP 735) uv add --dev pytest # creates a .venv and uv.lock file mkdir tests # Use double-quotes to ref variables directly in string echo "from $proj_underscores import hello def test_hello(): assert hello() == ""Hello from $proj_name!"" " > tests/test_$proj_underscores.py uv run pytest see Simple Src Layout Example Introduction Python development is evolving rapidly, and UV is at the forefront of this transformation. In this post, I wanted to document my experience switching to UV, why and I how I’ve started the move to a modern workflow. ...