DSPy: Declarative Self-improving Language Programs

3.1.3 verified Mon May 11 auth: no python install: stale quickstart: stale

DSPy is a framework for algorithmically optimizing Language Model (LM) prompts and weights, especially within complex workflows. It enables developers to express multi-step reasoning as modular, self-improving programs, abstracting away the specifics of prompting and fine-tuning. The current version is 3.1.3, with a very active development schedule and frequent updates, often involving significant API changes between major versions.

pip install dspy-ai

Common errors

error ModuleNotFoundError: No module named 'dspy.teleprompt' ↓

cause The `teleprompt` module and its classes, such as `MIPROv2` or `BootstrapFewShot`, have been moved or integrated directly into the `dspy.optimizers` module in recent versions.

fix

Update your import statements to from dspy.optimizers import ... for teleprompters and optimizers. For example, from dspy.optimizers import BootstrapFewShot.

error AttributeError: module 'dspy' has no attribute 'settings' ↓

cause The `dspy.settings` object, previously used for configuration, has been deprecated or restructured; global configuration is now primarily handled by `dspy.configure()` and temporary overrides by `dspy.context()`.

fix

Replace calls to dspy.settings.configure(...) or dspy.settings.get(...) with dspy.configure(...) for global settings and use dspy.context(...) for temporary overrides.

error TypeError: Field 'instructions' in 'Signature' must be declared with InputField or OutputField. ↓

cause You are attempting to use a reserved keyword (like 'instructions', 'fields', 'insert', 'prepend', 'append', 'equals') as a field name within a `dspy.Signature` definition, which conflicts with internal DSPy properties.

fix

Rename the conflicting field in your dspy.Signature to avoid using DSPy's reserved keywords. For example, use user_instructions instead of instructions.

error AssertionError: No LM is loaded. ↓

cause A DSPy module or program was executed without a language model (LM) being properly configured and set as the default.

fix

Before running any DSPy modules, initialize a dspy.LM instance and configure it using dspy.configure(lm=my_lm_instance).

error AttributeError: module 'dspy' has no attribute 'AzureOpenAI' ↓

cause Specific LM client classes like `AzureOpenAI` might have been moved, renamed, or are expected to be imported from a different submodule or are no longer directly exposed under `dspy`.

fix

Refer to the latest DSPy documentation for the correct way to import and initialize specific language model clients, or use the generic dspy.OpenAI class with appropriate parameters for Azure.

Warnings

breaking Major API changes occurred between DSPy v2.x and v3.x. The `dspy.settings` module was removed and replaced by `dspy.configure()`. Additionally, LM configurations (e.g., `max_tokens`, `temperature`) are now typically passed directly to the LM constructor (e.g., `dspy.OpenAI`). ↓

fix Migrate `dspy.settings.<property> = value` calls to `dspy.configure(lm=...)`, `dspy.configure(rm=...)`, etc. Pass LM-specific parameters directly to the LM class constructor (e.g., `OpenAI(model='gpt-4', max_tokens=100)`).

gotcha Many users incorrectly install `dspy` instead of `dspy-ai`. The `dspy` package on PyPI is an unrelated, much older project. The modern DSPy framework is published under the `dspy-ai` package. ↓

fix Always use `pip install dspy-ai` to ensure you install the correct DSPy framework.

gotcha Forgetting to configure the Language Model (LM) or Retrieval Model (RM) using `dspy.configure()` before running any DSPy program is a common mistake, leading to `ValueError` or `AssertionError`. ↓

fix Always call `dspy.configure(lm=..., rm=...)` at the beginning of your script to set up your LLM and retrieval backend. Ensure API keys are correctly provided, typically via environment variables, to the LM constructors.

gotcha Compilers (Teleprompters) like `BootstrapFewShot` and `SFT` require a `trainset` (examples) to work effectively. Attempting to compile without sufficient examples will result in errors or poor performance. ↓

fix Provide a list of input-output example dictionaries (`trainset`) to the `compile` method of your teleprompter. For example: `teleprompter.compile(student=..., teacher=..., trainset=my_examples_list)`.

gotcha When installing `dspy-ai[openai]` for DSPy versions below 3.0.0 (e.g., 2.x), pip issues a warning stating that the 'openai' extra is not provided. This is because the `[openai]` extra was formally introduced with DSPy v3.0.0. Despite the warning, the `openai` package is usually installed correctly as a direct dependency of the core `dspy` package in these earlier versions. ↓

fix For DSPy versions below 3.0.0, this warning can typically be ignored as `openai` will still be installed. To explicitly install `openai` without the warning, use `pip install dspy-ai openai`. For DSPy versions 3.0.0 and above, `pip install dspy-ai[openai]` works as intended without warnings.

gotcha The `[openai]` extra is not provided by `dspy-ai` versions 3.x. OpenAI is typically installed as a transitive dependency of `dspy` (which `dspy-ai` depends on). Using `pip install dspy-ai[openai]` will result in a warning about the extra not being found, although OpenAI will still be installed. ↓

fix Install `dspy-ai` without the `[openai]` extra, e.g., `pip install dspy-ai`. OpenAI will be installed automatically as a dependency. If a specific version of OpenAI is needed, install it separately after `dspy-ai` (e.g., `pip install dspy-ai openai==X.Y.Z`).

Install

pip install dspy-ai[openai] # For OpenAI models

Install compatibility stale last tested: 2026-05-11

python os / libc variant status wheel install import disk

3.10 alpine (musl) dspy - - - -

3.10 alpine (musl) dspy-ai - - - -

3.10 alpine (musl) openai - - - -

3.10 slim (glibc) dspy - - - -

3.10 slim (glibc) dspy-ai - - - -

3.10 slim (glibc) openai - - - -

3.11 alpine (musl) dspy - - - -

3.11 alpine (musl) dspy-ai - - - -

3.11 alpine (musl) openai - - - -

3.11 slim (glibc) dspy - - - -

3.11 slim (glibc) dspy-ai - - - -

3.11 slim (glibc) openai - - - -

3.12 alpine (musl) dspy - - - -

3.12 alpine (musl) dspy-ai - - - -

3.12 alpine (musl) openai - - - -

3.12 slim (glibc) dspy - - - -

3.12 slim (glibc) dspy-ai - - - -

3.12 slim (glibc) openai - - - -

3.13 alpine (musl) dspy - - - -

3.13 alpine (musl) dspy-ai - - - -

3.13 alpine (musl) openai - - - -

3.13 slim (glibc) dspy - - - -

3.13 slim (glibc) dspy-ai - - - -

3.13 slim (glibc) openai - - - -

3.9 alpine (musl) dspy - - - -

3.9 alpine (musl) dspy-ai - - - -

3.9 alpine (musl) openai - - - -

3.9 slim (glibc) dspy - - - -

3.9 slim (glibc) dspy-ai - - - -

3.9 slim (glibc) openai - - - -

Imports

dspy
```
import dspy
```
Signature
```
from dspy import Signature
```
Predict
```
from dspy import Predict
```
ChainOfThought
```
from dspy import ChainOfThought
```
Retrieve
```
from dspy import Retrieve
```
OpenAI
```
from dspy.models import OpenAI
```
ColBERTv2
wrong
```
from dspy import ColBERTv2
```
correct
```
from dspy.retrieve import ColBERTv2
```
Retrieval models are typically in `dspy.retrieve`.
BootstrapFewShot
wrong
```
from dspy import BootstrapFewShot
```
correct
```
from dspy.teleprompt import BootstrapFewShot
```
Teleprompters (compilers) are typically in `dspy.teleprompt`.

Quickstart stale last tested: 2026-05-11

This quickstart demonstrates how to configure an LLM, define a simple `Signature` for a task, and use `dspy.Predict` to execute it. Make sure to set your `OPENAI_API_KEY` environment variable before running. The `dspy.configure` function sets the default language model for all subsequent DSPy operations.

import os
import dspy
from dspy.models import OpenAI

# Configure the LM (e.g., OpenAI GPT-3.5-turbo)
# Ensure OPENAI_API_KEY environment variable is set
dspy.configure(
    lm=OpenAI(model='gpt-3.5-turbo', api_key=os.environ.get("OPENAI_API_KEY", ""))
)

# Define a signature for a task (input fields, output fields)
class BasicQA(dspy.Signature):
    """Answer questions with short factoid answers."""
    question = dspy.InputField()
    answer = dspy.OutputField(desc="often just 1-5 words")

# Instantiate a predictor for the signature
# Predict uses the configured LM to execute the signature
predict_qa = dspy.Predict(BasicQA)

# Make a prediction
question = "What is the capital of France?"
response = predict_qa(question=question)

print(f"Question: {question}")
print(f"Answer: {response.answer}")