# Setting up PyRIT Development Environment with uv (Windows)

This guide covers setting up a PyRIT development environment using [uv](https://github.com/astral-sh/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](./1b_install_devcontainers.md)** - 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](../setup/1a_install_uv.md).

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 [https://github.com/astral-sh/uv](https://github.com/astral-sh/uv) or use:
   for windows:
   ```powershell
   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](https://git-scm.com/downloads).
    ```bash
    git clone https://github.com/Azure/PyRIT
    ```

4. **Node.js and npm**. Required for building the TypeScript/React frontend. Download [Node.js](https://nodejs.org/) (which includes npm). Version 18 or higher is recommended.

## 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:

```bash
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](https://stackoverflow.com/questions/77134272/pip-install-dev-with-pyproject-toml-not-working) for more details.


3. Verify Installation

```bash
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:
```bash
uv add --dev ipykernel
```
then, create the kernel using:
```bash
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=pyrit-dev
```
Start the server using
```bash
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:

```bash
uv run python your_script.py
```

### Running Tests

```bash
uv run pytest tests/
```

### Running Specific Test Files

```bash
uv run pytest tests/unit/test_something.py
```

### Using PyRIT CLI Tools

```bash
uv run pyrit_scan --help
uv run pyrit_shell
```

### Running Jupyter Notebooks

```bash
uv run jupyter lab
```

### Installing Additional Extras

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

```bash
# 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:

```bash
uv sync
```

### Updating Dependencies

```bash
uv lock --upgrade
uv sync
```

### Running Code Formatters

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

### Running Type Checker

```bash
uv run mypy pyrit/
```

### Pre-commit Hooks

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

## Populating Secrets

See [this](../setup/populating_secrets.md) 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:

```powershell
.\.venv\Scripts\Activate.ps1
```

### Dependency conflicts

Try regenerating the lock file:

```powershell
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:

```bash
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

- [uv Documentation](https://github.com/astral-sh/uv)
- [PyRIT Contributing Guide](README.md)
- [Running Tests Guide](5_running_tests.md)