Dependencies

Inspect Flow automatically creates isolated virtual environments for each workflow run, ensuring repeatability and avoiding dependency conflicts with your system Python environment. Because each run starts with a fresh environment, dependencies must be resolved—either automatically detected from your project files or explicitly specified in your configuration.

When you run flow run config.py, Flow:

  1. Creates a temporary virtual environment with uv
  2. Installs dependencies from dependency files and/or config file
  3. Executes your evaluations in this isolated environment
  4. Cleans up the temporary environment after completion (logs persist in log_dir)

Automatic Dependency Discovery

By default, Flow automatically discovers and installs dependencies without requiring explicit configuration:

  • Dependency files: Searches upward from your config file directory for pyproject.toml or requirements.txt. Relative paths will be resolved relative to the config file (when using the CLI) or base_dir arg (when using the API)
  • Package inference: Detects packages from object names in your config:
    • Models: model="openai/gpt-4" → installs openai
    • Tasks: name="inspect_evals/mmlu" → installs inspect-evals
  • Config inheritance: Automatically includes any _flow.py files in the config directory or parent directories (see Inheritance). These files can specify default dependencies that apply to all including configs.

This means most workflows require no dependency configuration at all!

Explicit Dependencies

While automatic dependency discovery works for most cases, you may need explicit dependencies when you require specific package versions for reproducibility e.g. openai==2.8.0, need to specify a non-standard dependency file location, or need to override the automatic detection behavior. Explicit dependencies give you full control over what gets installed in your workflow’s virtual environment.

The dependencies field in FlowSpec accepts a FlowDependencies object:

config.py
from inspect_flow import FlowDependencies, FlowSpec, FlowTask

FlowSpec(
    dependencies=FlowDependencies(
        dependency_file="../foo/pyproject.toml",
        additional_dependencies=["pandas==2.0.0"],
        auto_detect_dependencies=True,
    ),
    log_dir="logs",
    tasks=[
        FlowTask(
            name="inspect_evals/gpqa_diamond",
            model="openai/gpt-5",
        ),
    ],
)
1
How to find dependency files: Defaults to "auto" which auto-detects a requirements.txt or a pyproject.toml file. May also be set to a path to a dependency file or "no_file" to not use a dependency file. When using pyproject.toml, if a uv.lock file exists in the same directory, it will be used automatically for reproducible installs.
2
Extra packages beyond the dependency file. Accepts a string or list of strings. Supports: PyPI packages, Git repositories, local packages.
3
Auto-install packages based on task and model names in the config (default: True). For example, model="openai/gpt-4" installs openai, and name="inspect_evals/mmlu" installs inspect-evals.

Python Version

Specify the Python version for your spec’s virtual environment:

config.py
from inspect_flow import FlowSpec, FlowTask

FlowSpec(
    python_version="3.11",
    log_dir="logs",
    tasks=[
        FlowTask(
            name="inspect_evals/gpqa_diamond",
            model="openai/gpt-5",
        ),
    ],
)

Checking Config

To verify which dependencies and Python version will be used:

flow run config.py --dry-run
TipRepeatability Best Practices

For repeatable workflows:

  • Pin PyPI package versions: "inspect-evals==0.3.15"
  • Pin Git commits: "git+https://github.com/user/repo@commit_hash"
  • Specify python_version explicitly
  • Use uv.lock with pyproject.toml for locked dependencies (automatically detected if present)