{"id":17,"library":"dspy-ai","title":"DSPy: Declarative Self-improving Language Programs","description":"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.","status":"active","version":"3.1.3","language":"python","source_language":"en","source_url":"https://github.com/dspy-ai/dspy","tags":["LLM","NLP","AI","prompt engineering","framework","optimization","declarative"],"install":[{"cmd":"pip install dspy-ai","lang":"bash","label":"Install core library"},{"cmd":"pip install dspy-ai[openai] # For OpenAI models","lang":"bash","label":"Install with OpenAI support"}],"dependencies":[{"reason":"Required for using dspy.OpenAI and other OpenAI-compatible models. Often installed via `dspy-ai[openai]` extra.","package":"openai","optional":true},{"reason":"Commonly used for managing API keys and environment variables in development.","package":"python-dotenv","optional":true},{"reason":"Used for token counting, especially with OpenAI models.","package":"tiktoken","optional":false}],"imports":[{"symbol":"dspy","correct":"import dspy"},{"symbol":"Signature","correct":"from dspy import Signature"},{"symbol":"Predict","correct":"from dspy import Predict"},{"symbol":"ChainOfThought","correct":"from dspy import ChainOfThought"},{"symbol":"Retrieve","correct":"from dspy import Retrieve"},{"symbol":"OpenAI","correct":"from dspy.models import OpenAI"},{"note":"Retrieval models are typically in `dspy.retrieve`.","wrong":"from dspy import ColBERTv2","symbol":"ColBERTv2","correct":"from dspy.retrieve import ColBERTv2"},{"note":"Teleprompters (compilers) are typically in `dspy.teleprompt`.","wrong":"from dspy import BootstrapFewShot","symbol":"BootstrapFewShot","correct":"from dspy.teleprompt import BootstrapFewShot"}],"quickstart":{"code":"import os\nimport dspy\nfrom dspy.models import OpenAI\n\n# Configure the LM (e.g., OpenAI GPT-3.5-turbo)\n# Ensure OPENAI_API_KEY environment variable is set\ndspy.configure(\n    lm=OpenAI(model='gpt-3.5-turbo', api_key=os.environ.get(\"OPENAI_API_KEY\", \"\"))\n)\n\n# Define a signature for a task (input fields, output fields)\nclass BasicQA(dspy.Signature):\n    \"\"\"Answer questions with short factoid answers.\"\"\"\n    question = dspy.InputField()\n    answer = dspy.OutputField(desc=\"often just 1-5 words\")\n\n# Instantiate a predictor for the signature\n# Predict uses the configured LM to execute the signature\npredict_qa = dspy.Predict(BasicQA)\n\n# Make a prediction\nquestion = \"What is the capital of France?\"\nresponse = predict_qa(question=question)\n\nprint(f\"Question: {question}\")\nprint(f\"Answer: {response.answer}\")","lang":"python","description":"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."},"warnings":[{"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)`).","message":"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`).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always use `pip install dspy-ai` to ensure you install the correct DSPy framework.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=3.x.x"}],"env_vars":null,"last_verified":"2026-05-11T18:59:25.068Z","next_check":"2026-07-08T00:00:00.000Z","problems":[{"fix":"Update your import statements to `from dspy.optimizers import ...` for teleprompters and optimizers. For example, `from dspy.optimizers import BootstrapFewShot`.","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.","error":"ModuleNotFoundError: No module named 'dspy.teleprompt'"},{"fix":"Replace calls to `dspy.settings.configure(...)` or `dspy.settings.get(...)` with `dspy.configure(...)` for global settings and use `dspy.context(...)` for temporary overrides.","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()`.","error":"AttributeError: module 'dspy' has no attribute 'settings'"},{"fix":"Rename the conflicting field in your `dspy.Signature` to avoid using DSPy's reserved keywords. For example, use `user_instructions` instead of `instructions`.","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.","error":"TypeError: Field 'instructions' in 'Signature' must be declared with InputField or OutputField."},{"fix":"Before running any DSPy modules, initialize a `dspy.LM` instance and configure it using `dspy.configure(lm=my_lm_instance)`.","cause":"A DSPy module or program was executed without a language model (LM) being properly configured and set as the default.","error":"AssertionError: No LM is loaded."},{"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.","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`.","error":"AttributeError: module 'dspy' has no attribute 'AzureOpenAI'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-11","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-11","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":-1},{"runtime":"python:3.10-slim","exit_code":-1},{"runtime":"python:3.11-alpine","exit_code":-1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":-1},{"runtime":"python:3.9-slim","exit_code":-1}]}}