Instructor

1.14.5 verified Tue May 12 auth: no python install: stale quickstart: verified

Structured data extraction from LLMs via Pydantic models. Patches or wraps provider clients (OpenAI, Anthropic, Gemini, Cohere, Mistral, Groq, Ollama, and 15+ others) to add response_model, automatic validation, and retry logic. Uses tool-calling or JSON mode depending on provider. Core interface: client.chat.completions.create(response_model=MyModel, ...) returns a validated Pydantic instance. Maintained by Jason Liu / jxnl.

pip install instructor

Common errors

error ModuleNotFoundError: No module named 'instructor' ↓

cause The 'instructor' library is not installed in your Python environment or is not accessible within your current virtual environment.

fix

Install the library using pip: pip install instructor.

error ModuleNotFoundError: No module named 'instructor.patch' ↓

cause The `instructor.patch()` function has been deprecated and replaced by `instructor.from_openai()` or `instructor.from_provider()` for creating an Instructor-enhanced client.

fix

Update your code to use instructor.from_openai(OpenAI()) for OpenAI clients or instructor.from_provider('your_provider/model_name') for other providers:

import instructor
from openai import OpenAI

# Old (will cause error)
# client = instructor.patch(OpenAI())

# New way for OpenAI
client = instructor.from_openai(OpenAI())

# Or for other providers, e.g., Anthropic
# import anthropic
# client = instructor.from_provider(anthropic.Anthropic())

error ValidationError: 1 validation error for MyModel ... ↓

cause The Large Language Model's (LLM) raw response did not conform to the schema defined by your Pydantic `response_model`, and Instructor's retry mechanism (if enabled) was exhausted.

fix

Review your Pydantic model definition for correctness and ensure it accurately reflects the expected output structure. Provide clearer or more specific instructions in your LLM prompt to guide the model towards generating output that matches the schema. You can also inspect e.failed_attempts if catching InstructorRetryException (or e directly if ValidationError) for the raw LLM output that caused the failure to debug. Consider simplifying the model or adding more robust Pydantic validators.

error AttributeError: 'Instructor' object has no attribute 'moderations' ↓

cause You are attempting to call a method (e.g., `moderations`) directly on an `Instructor`-wrapped client that was not part of the original client's patched API or is not directly exposed through the `Instructor` object's top-level attributes.

fix

Access the original client via client.client (e.g., client.client.moderations.create(...)) or ensure the method you're trying to call is part of the chat.completions API that instructor directly enhances. Instructor primarily extends client.chat.completions.create to include response_model.

error TypeError: _GenerativeModel.generate_content() got an unexpected keyword argument 'messages' ↓

cause This error often occurs when using `instructor` with a specific LLM provider (like Google's Gemini/Vertex AI) where the underlying client's method (e.g., `generate_content`) expects different argument names or structures than the standard OpenAI-like `messages` parameter that Instructor's patching might try to pass by default.

fix

Check the specific integration documentation for the LLM provider you are using with instructor to understand the expected input format. You might need to manually map your messages to the provider's specific content structure (e.g., contents for Gemini/Vertex AI) or ensure you're using a compatible mode for that provider (e.g., instructor.Mode.VERTEXAI_TOOLS or instructor.Mode.VERTEXAI_JSON). Ensure your client is initialized with the correct from_provider function for the specific LLM.

Warnings

breaking instructor.patch() removed in 1.0.0. All pre-1.0 code using instructor.patch(openai.OpenAI()) breaks with AttributeError. ↓

fix Replace instructor.patch(openai.OpenAI()) with instructor.from_openai(openai.OpenAI()). For Anthropic: instructor.from_anthropic(anthropic.Anthropic()).

breaking Pydantic v1 not supported. instructor requires Pydantic v2. ↓

fix Migrate models to Pydantic v2. The @validator decorator is replaced by @field_validator; Config class is replaced by model_config = ConfigDict(...).

breaking Provider-specific extras required for non-OpenAI backends. Using instructor.from_anthropic() without pip install 'instructor[anthropic]' raises ImportError. ↓

fix Install the appropriate extra for your provider: instructor[anthropic], instructor[google-genai], instructor[groq], instructor[cohere], instructor[mistral], instructor[litellm], etc.

breaking from_provider() requires 'provider/model' string format. Bare model names raise ValueError. ↓

fix Use prefixed strings: 'openai/gpt-4o', 'anthropic/claude-3-5-sonnet-latest', 'google/gemini-2.0-flash', 'ollama/llama3.2', 'groq/llama-3.1-8b-instant'.

gotcha Each provider uses a different default Mode (tool-calling vs JSON). Anthropic uses ANTHROPIC_TOOLS by default; OpenAI uses TOOLS. Mixing providers without checking mode compatibility causes silent output degradation or errors. ↓

fix Check the mode comparison table at python.useinstructor.com/modes-comparison/. Pass mode=instructor.Mode.JSON explicitly if the provider doesn't support tool-calling.

gotcha max_retries controls validation retry attempts, not HTTP retries. Default is 1 retry on Pydantic validation failure. Complex schemas with small models frequently exhaust retries silently and raise InstructorRetryException. ↓

fix Set max_retries=3 or higher for unreliable models. Catch instructor.exceptions.InstructorRetryException explicitly. Simplify schemas to reduce retry rate.

gotcha Streaming with create_partial() returns Partial[T] objects where fields are None until generated. Accessing fields before the stream completes returns None — not an error. ↓

fix Only access fields after the final yielded object. Use create_iterable() for extracting multiple complete objects instead of partial streaming.

gotcha openai is a required dependency even when using non-OpenAI providers (Anthropic, Gemini, etc.). This is by design — instructor proxies through OpenAI's interface structure. ↓

fix Expected behavior. Do not attempt to uninstall openai when using other providers.

breaking Instructor uses type annotation union syntax (e.g., `Type1 | Type2`) which is natively supported only from Python 3.10. Using Instructor with Python versions below 3.10 will result in a `TypeError: Unable to evaluate type annotation 'Type1 | Type2'`. ↓

fix Upgrade your Python environment to version 3.10 or newer.

breaking OpenAI API key must be provided. When using OpenAI models with `instructor.from_provider('openai/model_name')` or `instructor.from_openai()`, ensure the API key is passed directly to the client constructor or set via the OPENAI_API_KEY environment variable. ↓

fix Set the OPENAI_API_KEY environment variable or pass `api_key` directly to the `openai.OpenAI` client when initializing it for instructor (e.g., `instructor.from_openai(openai.OpenAI(api_key='YOUR_KEY'))`).

Install

pip install 'instructor[anthropic]'

pip install 'instructor[google-genai]'

pip install 'instructor[groq]'

pip install 'instructor[litellm]'

Install compatibility stale last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) anthropic - - - -

3.10 alpine (musl) google-genai - - - -

3.10 alpine (musl) groq - - - -

3.10 alpine (musl) litellm - - - -

3.10 alpine (musl) instructor - - - -

3.10 slim (glibc) anthropic - - - -

3.10 slim (glibc) google-genai - - - -

3.10 slim (glibc) groq - - - -

3.10 slim (glibc) litellm - - - -

3.10 slim (glibc) instructor - - - -

3.11 alpine (musl) anthropic - - - -

3.11 alpine (musl) google-genai - - - -

3.11 alpine (musl) groq - - - -

3.11 alpine (musl) litellm - - - -

3.11 alpine (musl) instructor - - - -

3.11 slim (glibc) anthropic - - - -

3.11 slim (glibc) google-genai - - - -

3.11 slim (glibc) groq - - - -

3.11 slim (glibc) litellm - - - -

3.11 slim (glibc) instructor - - - -

3.12 alpine (musl) anthropic - - - -

3.12 alpine (musl) google-genai - - - -

3.12 alpine (musl) groq - - - -

3.12 alpine (musl) litellm - - - -

3.12 alpine (musl) instructor - - - -

3.12 slim (glibc) anthropic - - - -

3.12 slim (glibc) google-genai - - - -

3.12 slim (glibc) groq - - - -

3.12 slim (glibc) litellm - - - -

3.12 slim (glibc) instructor - - - -

3.13 alpine (musl) anthropic - - - -

3.13 alpine (musl) google-genai - - - -

3.13 alpine (musl) groq - - - -

3.13 alpine (musl) litellm - - - -

3.13 alpine (musl) instructor - - - -

3.13 slim (glibc) anthropic - - - -

3.13 slim (glibc) google-genai - - - -

3.13 slim (glibc) groq - - - -

3.13 slim (glibc) litellm - - - -

3.13 slim (glibc) instructor - - - -

3.9 alpine (musl) anthropic - - - -

3.9 alpine (musl) google-genai - - - -

3.9 alpine (musl) groq - - - -

3.9 alpine (musl) litellm - - - -

3.9 alpine (musl) instructor - - - -

3.9 slim (glibc) anthropic - - - -

3.9 slim (glibc) google-genai - - - -

3.9 slim (glibc) groq - - - -

3.9 slim (glibc) litellm - - - -

3.9 slim (glibc) instructor - - - -

Imports

from_openai
wrong
```
import instructor; client = instructor.patch(openai.OpenAI())
```
correct
```
import instructor; import openai; client = instructor.from_openai(openai.OpenAI())
```
instructor.patch() removed in 1.0.0. Replace with instructor.from_openai(). The patched client is now a proper wrapper, not a monkey-patch.
from_provider
wrong
```
import instructor; client = instructor.from_provider('gpt-4o')
```
correct
```
import instructor; client = instructor.from_provider('openai/gpt-4o')
```
from_provider() requires provider-prefixed model strings in 'provider/model' format. Bare model names like 'gpt-4o' raise errors — must be 'openai/gpt-4o', 'anthropic/claude-3-5-sonnet', 'ollama/llama3.2', etc.

Quickstart verified last tested: 2026-05-12

from_provider() is the 1.x unified interface. For per-provider clients use instructor.from_openai(), instructor.from_anthropic(), etc.

import instructor
from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

# Unified provider interface (1.x recommended)
client = instructor.from_provider('openai/gpt-4o-mini')

user = client.chat.completions.create(
    response_model=User,
    messages=[{'role': 'user', 'content': 'John is 25 years old'}],
)
print(user)  # User(name='John', age=25)