Dependencies

When running in virtual environment mode (execution_type="venv" or --venv flag), Flow creates isolated virtual environments for each workflow run, ensuring repeatability and avoiding dependency conflicts with your system Python environment.

When you run flow run config.py --venv, 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)
ImportantExecution Mode Matters

Flow’s dependency management behavior depends on your execution mode:

  • In-process mode (default): You manually install dependencies. Flow does not install packages automatically.
  • Virtual environment mode: Flow automatically creates isolated environments and installs dependencies.

This page primarily describes virtual environment mode. See Execution Modes for details on choosing between modes.

Automatic Dependency Discovery

In virtual environment mode, 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 Flow type names in your config:
    • Models: model="openai/gpt-4" → installs openai
    • Tasks: FlowTask(name="inspect_evals/mmlu") → installs inspect-evals
    • Note: Package inference only works with Flow types (FlowTask, FlowModel, etc.), not direct Inspect AI objects

This means most workflows require no dependency configuration at all!

NoteIn-Process Mode Dependencies

In in-process mode (the default), these files are ignored for automatic installation. You’re responsible for installing dependencies yourself using your preferred package manager (uv, pip, conda, etc.). However, you can still use the same pyproject.toml or requirements.txt files to manage your dependencies manually.

NoteConfig Inheritance

Flow automatically includes any _flow.py files in the config directory or parent directories (see Inheritance). When these files specify dependencies in venv mode, those dependencies are automatically installed. This works in both execution modes—the inheritance mechanism applies everywhere, but dependency installation only happens in venv mode.

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(
    execution_type="venv",
    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 when using venv mode:

config.py
from inspect_flow import FlowSpec, FlowTask

FlowSpec(
    execution_type="venv",
    python_version="3.11",
    log_dir="logs",
    tasks=[
        FlowTask(
            name="inspect_evals/gpqa_diamond",
            model="openai/gpt-5",
        ),
    ],
)
1
Required for python_version to take effect.
Note

The python_version field only applies to virtual environment mode. In in-process mode, evaluations run using your current Python interpreter.

Checking Config

To verify which dependencies and Python version will be used:

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

For repeatable workflows, use virtual environment mode with the following practices:

  • Enable venv mode: Set execution_type="venv" in your FlowSpec or use the --venv flag. This ensures isolated environments and automatic dependency installation.
  • Pin package versions: Use exact versions for PyPI packages ("inspect-evals==0.3.15") and commit hashes for Git repositories ("git+https://github.com/user/repo@commit_hash").
  • Specify Python version: Explicitly set python_version (e.g., "3.11") to ensure consistent Python environments.
  • Use lockfiles: When using pyproject.toml, include a uv.lock file for fully reproducible dependency resolution (automatically detected if present).

This combination ensures your evaluations can be reliably repeated and shared with others.