Python Setup with uv

uv is a fast and modern Python package, environment, and project manager that can:

• Install and manage Python versions (like pyenv)
• Handle dependencies and virtual environments (like Poetry)
• Run CLI tools without global installs (like pipx)

---

Python Installation and Version Management

List available Python versions:

uv python list

Install the latest Python 3 version:

uv python install 3

Pin a Python version for the current directory/project:

uv python pin 3

This creates a .python-version file specifying the chosen version.

Verify active Python:

which python
python --version

---

Running Tools with uv

Run any Python CLI tool without global installation:

uv tool run <tool> [args]

Or use the shorthand alias:

uvx <tool> [args]

Example:

uv tool run pycowsay 'hello world!'
uvx pycowsay 'hello world!'

Optionally, install a tool globally (cached for faster runs):

uv tool install <tool>

List globally installed tools:

uv tool list

---

Project & Dependency Management

Creating a new project

uv init my-project cd my-project

This initializes:

• pyproject.toml to manage dependencies
• .venv/ directory for the virtual environment inside the project folder

Activate the virtual environment

source .venv/bin/activate  # macOS/Linux
# Or on Windows PowerShell:
.venv\Scripts\Activate.ps1

Or run commands within the environment without activating:

uv run python --version uv run pytest

Adding dependencies

Install runtime dependencies:

uv add <package-name>

Install development dependencies:

uv add --dev <package-name>

Remove dependencies:

uv remove <package-name>

Install dependencies from existing pyproject.toml

uv sync

Viewing dependencies

Display the dependency tree for installed packages:

uv tree

Include optional and dev dependencies:

uv tree --all-groups

List all installed packages in the active environment (like pip list):

uv pip list

---

Upgrading Packages and Tools

Upgrade project dependencies

Upgrade all packages according to constraints and update the lockfile:

uv sync --upgrade

Upgrade a specific package:

uv sync --upgrade-package <package-name>

Upgrade globally installed CLI tools

Upgrade a specific tool:

uv tool upgrade <tool-name>

Upgrade all installed tools:

uv tool upgrade --all

---

References

• uv official documentation
• GitHub repository