Contributor Local Installation - PyRIT Documentation

Set up a PyRIT development environment on your local machine.

Setup with uv¶

uv is a fast Python package installer and resolver that we use for PyRIT development.

Why uv?

Much faster than pip (10-100x faster dependency resolution)
Simpler environment management 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

Prerequisites¶

Install uv: Download from https://github.com/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

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

Python 3.11-3.14: PyRIT supports these versions, and CI tests all of them. The repository does not pin an interpreter, so uv selects a compatible one for you (downloading it if needed).
Git. Git is required to clone the repo locally. It is available to download here.
```
git clone https://github.com/microsoft/PyRIT
```
Node.js and npm. Required for building the TypeScript/React frontend. Download Node.js (which includes npm). Version 22 or higher is required (the frontend’s react-router dependency requires Node >= 22.22.0).

Installation¶

Navigate to the directory where you cloned the PyRIT repo.
From the root of your clone, run:

uv sync

This command will:

Create a .venv directory with a virtual environment
Download a supported Python version if none is 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, ruff, etc.) via the dev dependency group
Create a uv.lock file for reproducible builds

To pin your checkout to a single version, run uv python pin 3.12. That writes a .python-version file, which is local to your working copy and not tracked by the repository.

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:

Press Ctrl+Shift+P
Type “Python: Select Interpreter”
Choose .venv\Scripts\python.exe

Running Jupyter Notebooks¶

uv sync already installs a python3 kernel inside .venv, and Jupyter binds it to whichever interpreter is running it, so notebooks work out of the box with no kernel registration step.

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 .venv interpreter for this checkout. 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.

If you do want a separately named kernel, scope it to the virtual environment:

uv run python -m ipykernel install --sys-prefix --name=pyrit-dev

Avoid --user with a fixed name if you work in more than one clone or git worktree. A --user kernel is installed machine-wide, so every checkout that registers the same name overwrites the others, and the survivor points at a single interpreter. Notebooks then execute against an unrelated checkout, or fail with FileNotFoundError: [WinError 2] once that checkout is deleted. See Jupyter setup if you hit this.

Running Python Scripts¶

Use uv run to execute Python with the virtual environment:

uv run python your_script.py

Remote dataset loaders use HF_DATASETS_CACHE when it is set. Otherwise they cache Hugging Face data under dbdata/huggingface. On Windows, a long worktree path can cause WinError 206 when Hugging Face creates a cache lock file. Set a shorter cache path before you start the server or script:

$env:HF_DATASETS_CACHE = Join-Path $env:TEMP "pyrit-hf"

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 (dev dependencies are always included automatically)
uv sync --extra playwright --extra gcg

Development Workflow¶

Keep the backend, CLI, and frontend in lockstep¶

The backend, CLI, and browser bundle must have exactly the same <Python package version>+g<full source commit> compatibility identity. Editable installation stamps the checkout; Vite stamps its bundle from the same source. After changing commits, refresh the stamp and restart the backend and Vite:

python -m build_scripts.stamp_compatibility --development

For locally packaged frontend assets, run python -m build_scripts.prepare_package --development. Dirty local changes warn but do not change the identity. These assets cannot be published. Wheel and sdist build hooks reject dirty sources and build matching assets automatically; installed clients read their packaged stamp, never local Git or the connected backend.

A compatibility failure requires matching artifacts, not bypassing the header. Reload the browser only after matching artifacts are deployed; mounted UI state is retained when a later mismatch blocks work. Do not automatically replay mutations. See the protocol and API example.

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 ruff format .
uv run ruff check --fix .

Running Type Checker¶

Run checks from the repository root using its own uv environment. Install all optional dependencies so guarded imports have the same dependency coverage as the production pre-commit hook:

uv sync --frozen --extra all
uv run --frozen --no-sync ty check pyrit
uv run --frozen --no-sync ty check pyrit tests\unit

The first check covers production code, matching the CI typing hook. The second also checks unit tests and is the scope of make ty. Pytest and ty both resolve test helpers from the tests directory; use tier-root imports such as from unit.mocks import MockPromptTarget.

CI runs make ty once in the Ubuntu pre-commit job with all extras and Python 3.11, the minimum supported version. It runs for every pull request, merge-queue entry, and push to main, including test-only changes. The existing production-only typing hook still runs on all three operating systems.

Checking all test tiers and build scripts is a separate, wider diagnostic scope:

uv run --frozen --no-sync ty check pyrit tests build_scripts

That wider scope is not the CI typing hook and may still report errors outside unit tests. The lock file pins the checker version. Record the environment’s Python version separately from ty’s target version, which defaults to the minimum supported Python version unless overridden with --python-version.

Pre-commit Hooks¶

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

Next Step: Configure PyRIT¶

After installing, configure your AI endpoint credentials.

Troubleshooting¶

Having issues? See the Local Dev Troubleshooting guide for common problems and solutions.