Instructor patches LLM clients to return validated Pydantic models instead of raw JSON. If you see ModuleNotFoundError: No module named ‘instructor’, install with one pip command and pair with whichever LLM provider you use.
Step 1: Install instructor
# Base install:
pip install instructor
# With provider extras:
pip install 'instructor[openai]' # OpenAI client patched
pip install 'instructor[anthropic]' # Anthropic client patched
pip install 'instructor[google-generativeai]' # Gemini
pip install 'instructor[litellm]' # 100+ models via LiteLLM
Step 2: Define a Pydantic schema
from pydantic import BaseModel, Field
from typing import List
class User(BaseModel):
name: str = Field(description="Full name")
age: int = Field(description="Age in years")
skills: List[str] = Field(description="List of skills")
Step 3: Extract structured data
import instructor
from openai import OpenAI
client = instructor.from_openai(OpenAI())
user = client.chat.completions.create(
model="gpt-4o",
response_model=User,
messages=[{
"role": "user",
"content": "Extract: Alice is 30 and knows Python, SQL, Docker."
}]
)
print(user.name, user.age, user.skills)
# Alice 30 ['Python', 'SQL', 'Docker']
Step 4: Use with Anthropic Claude
import instructor
from anthropic import Anthropic
client = instructor.from_anthropic(Anthropic())
user = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
response_model=User,
messages=[{"role": "user", "content": "Alice is 30 and knows Python"}]
)
Why this error happens
| Cause | Fix |
|---|---|
| Never installed | pip install instructor |
| Installed openai but not instructor | Add pip install instructor (instructor wraps OpenAI client) |
| Python under 3.9 | Upgrade to Python 3.10+ |
| Pydantic v1 (instructor needs v2) | pip install -U pydantic |
Frequently Asked Questions
Why use instructor instead of OpenAI’s built-in JSON mode?
Instructor gives you Pydantic validation, automatic retries on schema mismatch, streaming partial objects, and a consistent API across OpenAI, Anthropic, Gemini, Cohere, and Ollama. JSON mode alone just guarantees valid JSON, not your specific schema.
Does instructor work with local LLMs?
Yes. Use the OpenAI-compatible endpoint of Ollama, vLLM, or LM Studio: from openai import OpenAI; OpenAI(base_url=”http://localhost:11434/v1″) then wrap with instructor. Larger local models (70B+) handle structured output best.
Can instructor stream partial Pydantic objects?
Yes. Use create_partial() instead of create() to yield progressively-filled Pydantic models as tokens arrive. Useful for UIs that show fields appearing one by one.
How does instructor handle validation failures?
When the LLM returns data that does not match your Pydantic schema, instructor retries automatically with the validation error included in the prompt so the LLM can correct itself. Default max_retries=3. Configurable.
Is instructor free and open-source?
Yes, MIT licensed. The library is free; you only pay for LLM API calls. Works in commercial products with no restrictions.