●Change8

Migrating to DSPy 3.3.0b1

Version 3.3.0b1 introduces 3 breaking changes. This guide details how to update your code.

Released: 5/28/2026

3
Breaking Changes
4
Migration Steps
13
Affected Symbols

⚠️ Check Your Code

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

dspy.ReActV2dspy.Historydspy.Tooldspy.ToolCallsdspy.LMRequestdspy.LMResponsedspy.BaseLMdspy.LMErrordspy.RLMSandboxSerializableDspyGEPAResultdspy.LMRequestdspy.LMResponse

Breaking Changes

●Issue #1

The base `dspy` install no longer includes `numpy`. Users requiring NumPy-backed features (embeddings, KNN/KNNFewShot, SIMBA, optimizers, retrieval) must now install with `pip install "dspy[numpy]"`.

●Issue #2

The structure of GEPA results returned by `optimized_program.detailed_results` has changed due to GEPA 0.1.1 updates. Specifically: `DspyGEPAResult.candidates` is now a list of compiled DSPy modules (was instruction dictionaries), `DspyGEPAResult.best_candidate` returns a compiled DSPy module, `val_subscores` is now `list[dict[Any, float]]`, `per_val_instance_best_candidates` is now `dict[Any, set[int]]`, `best_outputs_valset` is now `dict[Any, list[tuple[int, Prediction]]]`, and `highest_score_achieved_per_val_task` returns a dictionary keyed by validation instance id.

●Issue #3

If passing custom GEPA reflection templates directly, default placeholders have changed: `<curr_instructions>`/`<inputs_outputs_feedback>` are now `<curr_param>`/`<side_info>`. Passing `reflection_prompt_template` via `gepa_kwargs` now raises a `ValueError`; use `instruction_proposer` instead.

Migration Steps

  1. 1
    If your code depends on NumPy features (embeddings, KNN, SIMBA, etc.), install it explicitly using `pip install "dspy[numpy]"`.
  2. 2
    If you inspect detailed GEPA results, update code to handle the new shapes for `DspyGEPAResult.candidates`, `DspyGEPAResult.best_candidate`, `val_subscores`, `per_val_instance_best_candidates`, `best_outputs_valset`, and `highest_score_achieved_per_val_task`.
  3. 3
    If you pass custom GEPA reflection templates, use `instruction_proposer` instead of passing `reflection_prompt_template` via `gepa_kwargs`.
  4. 4
    If you catch specific provider exceptions for LM failures, update handlers to catch `dspy.LMError` or a DSPy subclass instead.

Release Summary

DSPy 3.3.0b1 introduces the experimental ReActV2 module and moves towards a typed, provider-neutral LM boundary contract. This release also makes NumPy optional in the base install and updates GEPA integration to 0.1.1.

Need More Details?

View the full release notes and all changes for DSPy 3.3.0b1.

View Full Changelog