Setting up PyRIT Development Environment with uv (Windows)

Setting up PyRIT Development Environment with uv (Windows)#

This guide covers setting up a PyRIT development environment using uv, a fast Python package installer and resolver, on Windows.

Choose Your Setup Approach#

You can set up PyRIT for development in one of two ways:

  1. Local Installation with UV/Python (this page) - Install PyRIT in editable mode on your machine

  2. DevContainers in VS Code - Use a pre-configured Docker container with VS Code

Note

Development Version: Contributor installations use the latest development code from the main branch, not a stable release. The notebooks in your cloned repository will match your code version. This documentation website also shows the main branch version.

Overview#

To install PyRIT as a library, the simplest way to do it is just pip install pyrit. This is documented here.

However, there are many reasons to install as a contributor. Yes, of course, if you want to contribute. But also because of the nature of the tool, it is often the case that targets, attacks, converters, core, etc. code needs to be modified. This section walks through how to install PyRIT as a contributor.

Why uv?#

  • Much faster than pip (10-100x faster dependency resolution)

  • Simpler than conda/mamba for pure Python projects

  • Native Windows support - no WSL required, although if using a devcontainer, WSL is recommended

  • Automatic virtual environment management

  • Compatible with existing pyproject.toml

Prerequisite software#

  1. Install uv: Download from astral-sh/uv or use: for windows:

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

    for macOS and Linux

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

    or

    wget -qO- https://astral.sh/uv/install.sh | sh

  2. Python 3.12: uv will automatically download and use the correct Python version based on .python-version

  3. Git. Git is required to clone the repo locally. It is available to download here.

    git clone https://github.com/Azure/PyRIT

Installation with uv#

This is a guide for how to install PyRIT using uv

  1. Navigate to the directory where you cloned the PyRIT repo.

  2. The repository includes a .python-version file that pins Python 3.12. Run:

uv sync --extra dev

This command will:

  • Create a .venv directory with a virtual environment

  • Install Python 3.12 if not already available

  • Install PyRIT in editable mode; uv sync by default installs in editable mode so no extra flag is necessary

  • Install all dependencies including dev tools (pytest, black, ruff, etc.)

  • Create a uv.lock file for reproducible builds

If you are having problems getting pip to install, try this link for details here: this post for more details.

  1. Verify Installation

uv pip show pyrit

You should see output showing the most recent PyRIT version and your Python dependencies.

VS Code Integration#

VS Code should automatically detect the .venv virtual environment. If not:

  1. Press Ctrl+Shift+P

  2. Type “Python: Select Interpreter”

  3. Choose .venv\Scripts\python.exe

Running Jupyter Notebooks#

You can create a Jupyter kernel by first installing ipykernel:

uv add --dev ipykernel

then, create the kernel using:

uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=pyrit-dev

Start the server using

uv run jupyter lab

or using VS Code, open a Jupyter Notebook (.ipynb file) window, in the top search bar of VS Code, type >Notebook: Select Notebook Kernel > Python Environments... to choose the pyrit-dev kernel when executing code in the notebooks, like those in examples. You can also choose a kernel with the “Select Kernel” button on the top-right corner of a Notebook.

This will be the kernel that runs all code examples in Python Notebooks.

Running Python Scripts#

Use uv run to execute Python with the virtual environment:

uv run python your_script.py

Running Tests#

uv run pytest tests/

Running Specific Test Files#

uv run pytest tests/unit/test_something.py

Using PyRIT CLI Tools#

uv run pyrit_scan --help
uv run pyrit_shell

Running Jupyter Notebooks#

uv run jupyter lab

Installing Additional Extras#

PyRIT has several optional dependency groups. Install them as needed:

# For Hugging Face models
uv sync --extra huggingface

# For all extras
uv sync --extra all

# Multiple extras
uv sync --extra dev --extra playwright --extra gcg

Development Workflow#

Adding New Dependencies#

Edit pyproject.toml to add dependencies, then run:

uv sync

Updating Dependencies#

uv lock --upgrade
uv sync

Running Code Formatters#

uv run black .
uv run ruff check --fix .

Running Type Checker#

uv run mypy pyrit/

Pre-commit Hooks#

uv run pre-commit install
uv run pre-commit run --all-files

Populating Secrets#

See this for more details on populating secrets.

Troubleshooting#

uv command not found#

Make sure uv is in your PATH. Restart PowerShell after installation.

Import errors#

Ensure you’re using uv run python or have activated the virtual environment:

.\.venv\Scripts\Activate.ps1

Dependency conflicts#

Try regenerating the lock file:

Remove-Item uv.lock
uv sync --extra dev

Module not found errors#

PyRIT is installed in editable mode, so changes to the source code are immediately reflected. If you see import errors:

uv sync --reinstall-package pyrit

Advantages over Other Methods#

Feature

uv

conda/mamba

pip + venv

Docker/DevContainer

Setup time

~2 min

~10-15 min

~15-20 min

~20-30 min

Disk space

~1 GB

~3-5 GB

~1.5 GB

~5-10 GB

Windows native

✅

✅

✅

❌ (needs WSL2)

Speed

⚡⚡⚡

⚡

⚡⚡

⚡

Lock file

✅

✅

❌

✅

Isolation

✅

✅

✅

✅✅

Additional Resources#

Contents