dspy-ai

library3.3.1pypypi✓ verified 27d ago

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.

llm-agents ai-ml

pip install dspy-ai

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DSPY-AI

dspy-ai

llm-agentspythonv3.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.3.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

8/12 runs

9/12 runs

py 3.11

8/12 runs

9/12 runs

py 3.12

9/12 runs

py 3.13

9/12 runs

py 3.9

8/12 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

✓ from dspy.retrieve import ColBERTv2

✗ from dspy import ColBERTv2

Retrieval models are typically in `dspy.retrieve`.

BootstrapFewShot

✓ from dspy.teleprompt import BootstrapFewShot

✗ from dspy import BootstrapFewShot

Teleprompters (compilers) are typically in `dspy.teleprompt`.

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}")

Debug

Known issues

breakingMajor 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)`).

affects: >=3.0.0

gotchaMany 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.

affects: All

gotchaForgetting 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.

affects: All

gotchaCompilers (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)`.

affects: All

gotchaWhen 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.

affects: <3.0.0

gotchaThe `[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`).

affects: >=3.x.x

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'dspy.teleprompt'

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`.

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

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.

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

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`.

AssertionError: No LM is loaded.

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)`.

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

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.

Upgrade

Version history

3.3.1latest on PyPI · released Aug 21, 2026

Audit

Dependencies

openaioptionalRequired for using dspy.OpenAI and other OpenAI-compatible models. Often installed via `dspy-ai[openai]` extra.

python-dotenvoptionalCommonly used for managing API keys and environment variables in development.

tiktokenrequiredUsed for token counting, especially with OpenAI models.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/stanfordnlp/dsp ↗

packagehttps://pypi.org/project/dspy-ai/ ↗

homepagehttps://dspy.ai ↗