Skip to content

install_local_dev.md

Latest commit

 

History

History
247 lines (168 loc) · 5.99 KB

install_local_dev.md

File metadata and controls

247 lines (168 loc) · 5.99 KB
Raw

Contributor Local Installation

Set up a PyRIT development environment on your local machine.

**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.

Option 1: uv (Recommended)

uv is a fast Python package installer and resolver. We recommend it for PyRIT development.

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

Prerequisites

  1. 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

    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/microsoft/PyRIT

  4. Node.js and npm. Required for building the TypeScript/React frontend. Download Node.js (which includes npm). Version 18 or higher is recommended.

Installation

  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 ty check pyrit/

Pre-commit Hooks

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

Option 2: Conda

If you prefer conda for environment management, you can use it to create a Python environment and install PyRIT for development.

Prerequisites

  1. Conda or Miniconda: Download from https://docs.anaconda.com/free/miniconda/

  2. Git: Clone the repository:

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

  3. Node.js and npm: Required for building the frontend. Download Node.js (version 18+).

Installation

  1. Create a conda environment with the correct Python version:
conda create -y -n pyrit-dev python=3.12
conda activate pyrit-dev
  1. Navigate to the cloned PyRIT directory and install in editable mode with dev dependencies:
pip install -e .[dev]
  1. Verify installation:
pip show pyrit

Jupyter Kernel Setup

Create a Jupyter kernel for the conda environment:

pip install ipykernel
python -m ipykernel install --user --name=pyrit-dev --display-name "PyRIT Dev"

Then start Jupyter:

jupyter lab

Next Step: Configure PyRIT

After installing, configure your AI endpoint credentials.

Jump to [Configure PyRIT](./configuration.md) to set up your credentials.

Troubleshooting

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