●Change8

Migrating to DSPy 3.0.0

Version 3.0.0 introduces 4 breaking changes. This guide details how to update your code.

Released: 8/12/2025

4
Breaking Changes
7
Migration Steps
23
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

dspy.ChatAdapterdspy.JSONAdapterdspy.XMLAdapterdspy.BAMLAdapterdspy.Imagedspy.Audiodspy.Historydspy.ToolCallsdspy.Adapterdspy.Typedspy.BaseTypedspy.ProgramModule.batchdspy.CodeActdspy.Refinedspy.ReActdspy.PythonInterpreterdspy.MIPROv2dspy.GRPOdspy.SIMBAdspy.GEPAdspy.syncifydspy.Code

Breaking Changes

●Issue #1

Community retriever integrations have been removed (see #8073). Migrate to custom code or use Tool/MCP integrations.

●Issue #2

Support for Python 3.9 has been dropped; only Python 3.10–3.13 are supported.

●Issue #3

The alias `dspy.Program` has been removed. Replace any usage with the actual program class or refactor code accordingly.

●Issue #4

Legacy modules `functional/` and `dsp/` clients, as well as old cache implementations, have been removed.

Migration Steps

  1. 1
    Remove any usage of community retriever integrations and replace them with custom retriever code or Tool/MCP integrations.
  2. 2
    Replace `dspy.Program` references with the concrete program class or refactor to the new API.
  3. 3
    Update imports from the removed `functional/` and `dsp/` client modules to the new locations or equivalents.
  4. 4
    Rename `BaseType` to `Type` in all type annotations and imports.
  5. 5
    Review adapter usage for async paths and streaming; adjust code if you relied on the previous streaming implementation.
  6. 6
    If you used legacy cache APIs, switch to the new configurable cache system.
  7. 7
    Verify optimizer configurations; `MIPROv2` now selects hyperparameters automatically.

Release Summary

DSPy 3.0 introduces powerful new optimizers, extensible adapters and types, async execution, and native MLflow 3.0 observability, while removing community retrievers, dropping Python 3.9 support, and cleaning up legacy APIs.

Need More Details?

View the full release notes and all changes for DSPy 3.0.0.

View Full Changelog