Instructor

Instructor is a Python library, maintained by 567 Labs, that solves a specific and painful problem: getting LLMs to return structured, validated data. It is not an inference engine in the traditional sense -- it does not serve models, manage GPU memory, or provide an API endpoint. Instead, Instructor sits as a thin client layer on top of any supported model provider (OpenAI, Anthropic, Google, Ollama, vLLM, and 15 others) and forces the output to match a schema you define with Pydantic models. The library handles the prompting, JSON parsing, validation, and automatic retries that otherwise clutter every extraction pipeline.

The project was first released in 2023 and has grown rapidly: over 13,000 GitHub stars, 250+ contributors, and nearly 15 million PyPI downloads per month. Those numbers reflect real adoption. Teams building data pipelines, tool-calling systems, or any application that needs reliable structured output from an LLM have made Instructor a default choice.

Position this library relative to what practitioners actually reach for. If you need to serve models at high throughput, you use vLLM, SGLang, or TensorRT-LLM. If you need a local chat interface, you use Ollama or LM Studio. Instructor is not a competitor to those tools. It is a layer you add on top of any of them (or any hosted API) to guarantee that the model's output fits a contract. Think of it as a schema-enforcement wrapper that works with whatever backend you already have.

You do not "run" Instructor as a server. You install it with pip install instructor and import it into your Python application. The core workflow has three steps:

1. Define a Pydantic model that describes the output you want. For example: class Person(BaseModel): name: str; age: int.
2. Patch an existing client -- the OpenAI SDK, Anthropic SDK, or any provider that exposes a compatible interface -- using instructor.from_openai() or the generic instructor.from_provider().
3. Call client.chat.completions.create(response_model=Person, ...) as you normally would, but pass the model class. The library handles the rest: it constructs the correct system prompt or tool-call format, parses the response, validates it against your Pydantic model, and retries automatically if validation fails.

Under the hood, Instructor translates your Pydantic schema into JSON schema, injects it into the LLM request using the provider's structured output or tool-call endpoint, and runs Pydantic validation on the result. If the model returns malformed JSON or values outside your constraints, the library re-prompts the model with validation errors attached. This loop continues until the output matches or a configurable max retry limit is reached.

There is no model loading, no GPU allocation, no server to stand up. Instructor is a pure Python library that works with any provider's Python SDK. If you are using an OpenAI-compatible API served by vLLM or Ollama, you simply point the patched client at the local endpoint.

Instructor does not introduce its own inference overhead beyond the validation and retry loop. The performance characteristics you observe are entirely determined by the underlying model and provider you call. If you connect it to a local vLLM server running on an NVIDIA A100, you get vLLM's throughput and latency. If you connect it to Ollama on an Apple Silicon Mac, you get Ollama's performance.

The library itself adds a small amount of CPU time for Pydantic model validation (typically microseconds per field) and any network round trips to the provider. The retry mechanism can add latency if the model repeatedly fails to conform to the schema. In practice, with modern instruction-tuned models, retry rates are low (under 5% for well-defined schemas).

Hardwise issues can arise from the import footprint. The current release (as of early 2026) eagerly imports provider-specific patching code, response processing modules, and dozens of packages. A bare import instructor can consume 290 MB of RAM and take several seconds. A pending pull request (lazy-loading exports) aims to bring that down to roughly 15 MB and sub-second import time. If you are deploying in a serverless or memory-constrained environment, be aware of this import cost. The fix is expected to land in an upcoming release.

Structured output with Pydantic models. You define the shape of the data using Pydantic's field types, validators, and nested models. The library converts that into an LLM-friendly prompt or tool-call schema. This eliminates hand-written JSON schemas and fragile parsing code.

Automatic validation and retries. When the model's response fails to match your schema (wrong type, missing field, value out of range), Instructor automatically re-prompts the model with the validation errors. You do not write a single retry loop or try-except block.

Multi-provider support. The same code works with OpenAI, Anthropic, Google Gemini, Mistral, Cohere, Ollama, DeepSeek, and any OpenAI-compatible endpoint. You switch providers by changing the client instantiation; your Pydantic models remain unchanged.

Streaming. For providers that support it (OpenAI, Anthropic, Google), Instructor can stream partial structured outputs. You receive validated Pydantic objects incrementally as the model generates tokens.

Type safety and IDE support. Because you work with Pydantic models, your editor provides autocomplete, type hints, and inline validation. This dramatically reduces debugging time compared to raw JSON or dict handling.

Language bindings. While the engine is Python-first, the project also maintains official libraries for TypeScript, Go, Ruby, Elixir, and Rust. The Python library is the most mature and widely used.

Data extraction pipelines. Feed natural language documents, emails, or support tickets into an LLM and get structured records that land directly into a database or data lake. Instructor ensures every extraction fits the target schema, reducing the need for manual cleaning.

Tool and function calls. When building agents that call external APIs or internal services, Instructor forces the model to generate arguments that match the function schema. This eliminates malformed API calls and the error-handling code around them.

IRL applications in CI/CD and automation. Teams use Instructor to automatically classify and extract information from pull requests, issue comments, or changelogs. The guarantee of valid output allows downstream systems to be fully automated.

Multi-provider fallback. Teams that want to avoid lock-in can code against Instructor's unified interface and swap between GPT-4, Claude, or a local open model without changing extraction logic.

When not to use Instructor. If your workload requires maximum possible throughput and you are already using a serving engine's built-in structured output features (e.g., vLLM's guided decoding or SGLang's constrained grammar), adding Instructor as an extra layer may add unnecessary latency and complexity. Similarly, if you need a full agent runtime with observability, replay, and evals, consider PydanticAI (also from the Pydantic team) which extends Instructor-style extraction with agent capabilities.

Installation. Run:

1pip install instructor

That is the entire install. No GPU, no CUDA, no model files.

Minimum working example. After installation:

1import instructor
2from pydantic import BaseModel
3from openai import OpenAI
4
5client = instructor.from_openai(OpenAI())
6
7class User(BaseModel):
8    name: str
9    age: int
10
11user = client.chat.completions.create(
12    response_model=User,
13    messages=[{"role": "user", "content": "John is 25 years old."}]
14)
15print(user)  # User(name='John', age=25)

That is it. The library patches the OpenAI SDK and returns a validated Pydantic object.

What you need around it. An API key or local endpoint for your chosen provider. For local models, run Ollama, vLLM, or llama.cpp and point the patched client at the local base URL.

Where to find more. The official documentation is at [python.useinstructor.com](https://python.useinstructor.com). The GitHub repository at [github.com/567-labs/instructor](https://github.com/567-labs/instructor) contains examples, a changelog, and contributor guidelines. The Discord community is active for quick questions.

Instructor vs. vLLM / SGLang / Ollama. These are serving engines. They handle model hosting, batching, and GPU utilization. Instructor is a client library that wraps the output of any serving engine. There is no direct competition. You use vLLM to serve a model, and Instructor to guarantee the model's output is valid JSON. If your serving engine already supports constrained decoding (as vLLM and SGLang do), you can achieve schema enforcement at the generation level, which is faster than post-hoc validation and retries. Instructor's fallback approach is more portable across providers but adds latency if retries are needed. Choose Instructor if you need a provider-agnostic schema layer. Choose guided decoding if you run a single engine and need maximum throughput.

Instructor vs. LangChain's output parsers. Both solve structured extraction, but Instructor is significantly simpler. You define a Pydantic model and call a method; LangChain requires chaining composable parsers and handling retries manually. Instructor's validation and retries are built-in and automatic. For teams that already use Pydantic (which is most Python ML teams), Instructor feels like a natural extension rather than a framework.

Instructor vs. PydanticAI. PydanticAI is the official agent runtime from the Pydantic team. It adds agent loops, tool execution, observability dashboards, and dataset replay on top of the same Pydantic schema foundation. Instructor is deliberately minimal -- it does extraction, not agents. If your workload is pure schema-first extraction with no need for multi-step reasoning or observability, use Instructor. If you need a full agent runtime, evaluate PydanticAI. They complement each other; you can migrate extraction code from Instructor to PydanticAI later without rewriting your Pydantic models.