Master Instructor with our step-by-step tutorial, detailed feature walkthrough, and expert tips.
Install Instructor via pip: 'pip install instructor' and import the library into your Python project Patch your existing LLM client using 'instructor.from_provider(provider_name)' or specific provider functions like 'instructor.from_openai()' Define a Pydantic model describing your desired output schema with typed fields and optional validation rules Call your client with the response_model parameter: 'client.create(response_model=YourModel, messages=[...])' to get validated Python objects Handle the returned Pydantic object directly in your application code with full type safety and IDE support
💡 Quick Start: Follow these 1 steps in order to get up and running with Instructor quickly.
Explore the key features that make Instructor powerful for coding agents workflows.
Define output structure as Pydantic models with typed fields, descriptions, and validators. Instructor converts these to function-calling schemas and returns validated Python objects automatically.
When Pydantic validation fails, Instructor provides specific error messages to the LLM and retries. Models receive context about validation failures and can self-correct, achieving 99%+ success rates.
Unified from_provider() interface works with OpenAI, Anthropic, Google, Cohere, Mistral, DeepSeek, Ollama, and 10+ more providers. Switch providers without code changes for easy A/B testing and cost optimization.
Get incremental Pydantic model updates as the LLM generates tokens. Fields populate progressively, enabling real-time UIs that show structured data appearing as extraction progresses.
TOOLS mode uses native function calling for maximum reliability, JSON mode forces JSON output for weaker models, MD_JSON extracts from markdown blocks, and PARALLEL extracts multiple objects simultaneously.
Use Union types to let the LLM select the appropriate Pydantic model for classification tasks. Supports discriminated unions and automatic routing based on input content analysis.
Instructor is an open-source library for extracting structured, validated data from large language models. It lets you define the shape of the output you want using a Pydantic model (in Python, with equivalents in TypeScript, Go, and Ruby), then handles prompting, parsing, validation, and automatic retries so you receive a typed object instead of a raw string of JSON-ish text.
Instructor patches the official client SDKs of most major providers, including OpenAI, Anthropic Claude, Google Gemini and Vertex AI, Mistral, Cohere, Groq, Together, Fireworks, Anyscale, Databricks, Ollama, llama.cpp, and vLLM. The same Pydantic schema and call pattern works across providers, so swapping models is typically a one-line change.
A basic understanding of Pydantic is strongly recommended, because Instructor uses Pydantic models to define output schemas and to power validation. The good news is that the same skills transfer directly to FastAPI, LangChain, and many other Python tools, and Instructor's documentation includes worked examples for common patterns like nested models, enums, and custom validators.
When a model returns output that does not match your schema, Instructor catches the Pydantic ValidationError and automatically issues a follow-up request containing the original schema and the specific error messages, asking the model to correct itself. You control the maximum number of retries, and you can hook into the loop for logging or custom recovery logic.
Yes. Instructor integrates with Ollama, llama.cpp, vLLM, Together, Fireworks, Anyscale, Groq, and other open-source-friendly runtimes. Quality of structured output depends on the underlying model's instruction-following ability, but Instructor's retry-with-validation loop helps compensate for weaker models that occasionally produce malformed JSON.
Now that you know how to use Instructor, it's time to put this knowledge into practice.
Sign up and follow the tutorial steps
Check pros, cons, and user feedback
See how it stacks against alternatives
Follow our tutorial and master this powerful coding agents tool in minutes.
Tutorial updated March 2026