Configuration File (.pyrit_conf)

PyRIT supports an optional YAML configuration file that declares initialization settings — database type, initializers, environment files, and more. When present, these settings are loaded automatically so you don’t have to pass them every time you start PyRIT. It (.pyrit_conf) is basically just a YAML file specifying how to call initialize_pyrit. You can try it yourself in the PyRIT Configuration Notebook

File Location¶

The default configuration file path is:

~/.pyrit/.pyrit_conf

PyRIT looks for this file automatically on startup (via the CLI, shell, or ConfigurationLoader). If the file does not exist, PyRIT falls back to built-in defaults.

To get started, copy the example file from the repository root into your home directory:

mkdir -p ~/.pyrit
cp .pyrit_conf_example ~/.pyrit/.pyrit_conf

Then edit ~/.pyrit/.pyrit_conf to match your environment.

Configuration Fields¶

The .pyrit_conf file is YAML-formatted with the following fields:

memory_db_type¶

The database backend for storing prompts and results.

Values are case-insensitive and accept underscores or hyphens (e.g., in_memory, in-memory, InMemory all work).

initializers¶

A list of built-in initializers to run during PyRIT initialization. Initializers configure default values for converters, scorers, and targets. Names are automatically normalized to snake_case.

Each entry can be:

• A simple string — just the initializer name

• A dictionary — with name and optional args (each arg is a list of strings passed to initialize_async)

Example:

initializers:
  - simple
  - name: target
    args:
      tags:
        - default
        - scorer

Use pyrit list initializers in the CLI to see all registered initializers. See the initializer documentation notebook for reference.

initialization_scripts¶

Paths to custom Python scripts containing PyRITInitializer subclasses. Paths can be absolute or relative to the current working directory.

initialization_scripts:
  - /path/to/my_custom_initializer.py
  - ./local_initializer.py

env_files¶

Environment file paths to load during initialization. Later files override values from earlier files.

env_files:
  - /path/to/.env
  - /path/to/.env.local

silent¶

If true, suppresses print statements during initialization. Useful for non-interactive environments or when embedding PyRIT in other tools. Defaults to false.

Configuration Precedence¶

PyRIT uses a 3-layer configuration precedence model. Later layers override earlier ones:

This means you can set sensible defaults in ~/.pyrit/.pyrit_conf and override specific values on a per-run basis without modifying the file.

Execution Order Within Resolved Configuration¶

The 3-layer model above determines which config values are selected. Once resolved, the values are applied in a fixed runtime order:

1. Environment files are loaded

2. Default values are reset

3. Memory database is configured (from memory_db_type)

4. Initializers are executed (sorted by execution_order)

Because initializers run last, they can modify anything set up in earlier steps — including environment variables and the memory instance. In practice, built-in initializers like simple and airt only call set_default_value and set_global_variable and do not touch memory or environment variables. However, a custom initializer could override those if needed. When this happens, the initializer’s changes take effect because it runs after the other settings have been applied.

Usage¶

From the CLI¶

The CLI and shell automatically load ~/.pyrit/.pyrit_conf. You can also point to a different config file:

pyrit_scan run --config-file ./my_project_config.yaml --database InMemory

Individual CLI arguments (like --database) override values from the config file.

From Python¶

Use initialize_from_config_async to initialize PyRIT directly from a config file:

from pyrit.setup import initialize_from_config_async

# Uses ~/.pyrit/.pyrit_conf by default
await initialize_from_config_async()

# Or specify a custom path
await initialize_from_config_async("/path/to/my_config.yaml")

For more control, use ConfigurationLoader.load_with_overrides which implements the full 3-layer precedence model:

from pathlib import Path
from pyrit.setup import ConfigurationLoader

# Layer 1 (~/.pyrit/.pyrit_conf) is always loaded automatically if it exists.
# Layer 2 and 3 overrides are optional keyword arguments:
config = ConfigurationLoader.load_with_overrides(
    config_file=Path("./my_project.yaml"),  # Layer 2: explicit config file (omit to skip)
    memory_db_type="in_memory",             # Layer 3: override database type
    initializers=["simple"],                # Layer 3: override initializers
)

await config.initialize_pyrit_async()

Full Example¶

Below is an annotated example showing all available fields. Copy this to ~/.pyrit/.pyrit_conf and customize as needed, or copy over from .pyrit_conf_example in the base PyRIT folder (i.e. PYRIT_PATH).

# Memory Database Type
# Options: in_memory, sqlite, azure_sql
memory_db_type: sqlite

# Built-in initializers to run
# Each can be a string or a dict with name + args
initializers:
  - simple

# Custom initialization scripts (optional)
# Omit or set to null for no scripts; [] to explicitly load nothing
# initialization_scripts:
#   - /path/to/my_custom_initializer.py

# Environment files (optional)
# Omit or set to null to use defaults (~/.pyrit/.env, ~/.pyrit/.env.local)
# Set to [] to load no env files
# env_files:
#   - /path/to/.env
#   - /path/to/.env.local

# Suppress initialization messages
silent: false

Next Steps¶

• Populating Secrets — Setting up environment variables and .env files

• Configuration Guide — Interactive examples of initialize_pyrit_async options

• PyRIT Initializers — Creating and using built-in and custom initializers

• Default Values — How initializer defaults work under the hood