Guide · Open source

How to use Instructor: structured LLM outputs in Python

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Instructor is an MIT-licensed Python library for getting structured data out of large language models. You describe the shape of the data as a Pydantic model, and Instructor returns a validated Python object instead of raw text. This guide shows how to install it, make a first extraction, and use retries, streaming and nested objects.

Instructor567-labs/instructor · ★ 14.1k · MIT Install options & downloads

Quick start

1Install the package. Run pip install instructor, or uv add instructor if you use uv.
2Prepare an API key or local model. Get an API key for your LLM provider, or set up a local model such as Ollama.
3Define a Pydantic model. Write a BaseModel class with the fields you want extracted, using typed attributes.
4Create a client. Call instructor.from_provider with a provider and model name such as openai/gpt-4o-mini.
5Call the completion method. Pass your model as response_model along with your messages and read back a validated Python object.
6Add validators and retries. Use Pydantic field validators and set max_retries so failed validations are retried with the error message.

What you need before you start

Instructor runs in Python and needs an API key for your chosen LLM provider, or a local model such as Ollama. The library is built on Pydantic, so you will define your data shapes with Pydantic models.

Python
An API key for your chosen LLM provider, or a local model such as Ollama

Install Instructor with pip or uv

Install the package with pip. If you use uv, the README gives a uv command as an alternative.

pip install instructor

uv add instructor

Define the data you want as a Pydantic model

Write a class that inherits from BaseModel and list the fields you need with their types. Instructor uses this model to ask the LLM for that structure and to validate the answer.

from pydantic import BaseModel


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

Create a client and extract data

Create a client with instructor.from_provider, passing a provider and model name such as openai/gpt-4o-mini. Then call the chat completions method with response_model set to your model. The README shows the result as a User object rather than JSON text.

The README also shows the same calling style for Anthropic, Google, Ollama and Groq, changing only the provider string. It also shows passing an api_key directly instead of using environment variables.

Provider strings in the README include openai/gpt-4o, anthropic/claude-3-5-sonnet, google/gemini-pro, ollama/llama3.2 and groq/llama-3.1-8b-instant.
Pass api_key= to from_provider if you do not want to rely on environment variables.

import instructor
from pydantic import BaseModel


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


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)

Add validation rules and automatic retries

Add a validator to a field with Pydantic's field_validator. If the model's answer fails validation, the README says Instructor retries the request and includes the error message. The max_retries argument sets how many attempts are made.

from pydantic import BaseModel, field_validator


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

    @field_validator('age')
    def validate_age(cls, v):
        if v < 0:
            raise ValueError('Age must be positive')
        return v


user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "..."}],
    max_retries=3,
)

Stream partial results and extract nested objects

For streaming, the README wraps the model in Partial[User] and sets stream=True. Each loop iteration gives a partly filled object, with fields that are not yet known set to None.

For nested data, a field can hold a list of another Pydantic model, such as a list of addresses. The README says Instructor handles nested objects automatically.

Partial[User] with stream=True gives partial objects as they are generated.
List[Address] inside a model extracts nested structures.

from instructor import Partial

for partial_user in client.chat.completions.create(
    response_model=Partial[User],
    messages=[{"role": "user", "content": "..."}],
    stream=True,
):
    print(partial_user)

Know when Instructor is the wrong tool

Instructor is focused on structured extraction. The README says that if you need plain chat text with no structured output, the library adds nothing. It also says that for agent runs with tools, observability or shareable traces, you should look at PydanticAI, which is from the Pydantic team and uses the same Pydantic models.

The README lists ports in other languages, including TypeScript, Ruby, Go, Elixir and Rust. It does not describe how mature those ports are, so check them yourself before relying on one.

What people use it for

Pulling names, ages or other fields from free-form text into a Python object for downstream code.
Extracting product details such as name, price and stock status from a short description, as the README's example shows.
Turning unstructured text into nested records, such as a user with a list of addresses.
Streaming partial results to show fields as they fill in during generation.

Frequently asked questions

Is Instructor free to use?

Instructor is released under the MIT License, as the README states, and the license text is linked from the repository. Your LLM provider may still charge for API calls, which the source does not cover.

What do I need to run Instructor?

The README lists Python and an API key for your chosen LLM provider, or a local model such as Ollama. You also need Pydantic, since models are defined with it.

How do I install Instructor?

Run pip install instructor, or uv add instructor if you use uv. The README also mentions poetry add instructor.

What is the difference between Instructor and PydanticAI?

The README describes Instructor as a library for fast, schema-first extraction. It describes PydanticAI as the official agent runtime from the Pydantic team, adding typed tools, evals and dashboards.

Which LLM providers does Instructor support?

The README shows examples for OpenAI, Anthropic, Google, Ollama and Groq, all using the same calling style with a different provider string. It does not give a full provider list.

How does Instructor compare to LangChain or LlamaIndex?

The README says Instructor focuses on one thing, structured extraction, and is lighter and easier to debug than LangChain or LlamaIndex. Those projects cover wider ground, so the right choice depends on your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Instructor is a good fit for Python developers who want typed, validated data from an LLM and already use or are happy to use Pydantic models. If you need plain chat text, a full agent runtime with tools and tracing, or a mature non-Python port, look at PydanticAI or another tool from the comparison list instead.

Install options & downloads