Skip to content

uvx Setup Guide#

This guide explains how to set up and use uvx for managing Python virtual environments in this project.

What is uvx?#

uvx is a tool from the uv project by Astral, designed to run Python tools in isolated environments. It's significantly faster than traditional virtual environment tools and provides better dependency management.

Prerequisites#

  • Python 3.8 or higher
  • pip (comes with Python)

Installation#

Installing uv (includes uvx)#

macOS and Linux#

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

Windows#

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

Alternative: Using pip#

pip install uv

After installation, verify that uvx is available:

uvx --version

Using uvx with This Project#

Initializing a New Project with uv#

If you're starting a brand new Python project from scratch, uv can set up the project structure for you:

# Create a new project directory with pyproject.toml
uv init my-project

# Create a new project in the current directory
uv init

# Initialize without creating a workspace
uv init --no-workspace

# Initialize with a specific Python version
uv init --python 3.12

This creates:

  • pyproject.toml - Modern Python project configuration
  • README.md - Basic project documentation
  • .python-version - Specifies Python version
  • Basic project structure

Note: This project uses pyproject.toml for modern dependency management. All dependencies are now managed through uv commands rather than legacy requirements.txt files.

Running Tools with uvx#

Instead of creating a traditional virtual environment, you can run Python tools directly with uvx:

# Run pytest
uvx pytest

# Run black formatter
uvx black src/ test/

# Run flake8 linter
uvx flake8 src/ test/

Creating a Virtual Environment with uv#

If you need a traditional virtual environment, use uv venv:

# Create a virtual environment
uv venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

Installing Dependencies#

Important: uv add requires a pyproject.toml file.

This project uses pyproject.toml for dependency management:

# Install all dependencies (production and dev)
uv sync

# Install only production dependencies
uv sync --no-dev

# Install with specific group
uv sync --group dev

# Add a new production package
uv add requests

# Add a new development dependency
uv add --dev pytest

# Install project in editable mode
uv pip install -e .

Common Development Workflows#

Running Tests#

# With uvx (no virtual environment needed)
uvx pytest -v

# With activated virtual environment
pytest -v

# Run specific test file
uvx pytest test/test_tmp.py -s -v

# Run specific test function
uvx pytest test/test_tmp.py -k test_print_hi -s -v

Code Formatting and Linting#

# Format code with Black
uvx black src/ test/

# Check formatting without changes
uvx black --check src/ test/

# Lint with flake8
uvx flake8 src/ test/

# Run all quality checks
uvx black src/ test/ && uvx flake8 src/ test/ && uvx pytest -v

Using Make Commands with uv#

If you prefer the Makefile commands, ensure your virtual environment is activated first:

# Create and activate environment
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies from pyproject.toml
uv sync

# Now you can use Make commands
make lint
make format
make test

Advantages of uvx#

  1. Speed: Much faster than pip and traditional virtual environment tools
  2. Isolation: Each tool runs in its own isolated environment
  3. No Activation Required: Use uvx to run tools without activating a virtual environment
  4. Consistency: Ensures everyone uses the same tool versions
  5. Simplicity: Fewer steps to get started with development

Cleanup#

Removing a Virtual Environment#

If you created a virtual environment with uv venv and want to remove it:

# First, deactivate if currently activated
deactivate

# Then remove the .venv directory
# On macOS/Linux:
rm -rf .venv

# On Windows (PowerShell):
Remove-Item -Recurse -Force .venv

# On Windows (Command Prompt):
rmdir /s /q .venv

Clearing uv Cache#

To free up disk space or resolve dependency issues:

# Clear all cached packages and environments
uv cache clean

# View cache location and size
uv cache dir

Troubleshooting#

uvx command not found#

Make sure uv is properly installed and in your PATH. Try reinstalling:

pip install --upgrade uv

Tool not found with uvx#

If uvx can't find a tool, try specifying the package explicitly:

uvx --from pytest pytest -v

Dependency conflicts#

If you encounter dependency conflicts, try removing the cache:

uv cache clean

Additional Resources#

Support#

For issues specific to this project's setup, please file an issue in the repository. For uvx/uv issues, refer to the uv GitHub Issues.