Skip to content
Get packs

Instructor

Python library that gets structured, validated data (via Pydantic models) back from LLMs.

GitHub Download v1.17.0
Stars
14.1k
Forks
1.3k
Licence
MIT
Language
Python
Last update
10 days ago
Type
Library

What it is

Instructor is a Python library for pulling structured data out of large language models. You define the shape of the data you want as a Pydantic model, and Instructor asks the model for that structure and returns a validated Python object instead of raw text. The README says it can retry extractions when validation fails and works across several LLM providers through one interface.

  • Extract a user's name and age from a sentence into a typed object
  • Pull product name, price, and stock status from a product description
  • Parse nested data such as a user with a list of addresses
  • Stream partially completed objects while the model is still generating

Great for

  • Python developers who need JSON-like data from an LLM for downstream code
  • Teams extracting fields such as names, prices, or dates from free-form text
  • Developers already using Pydantic models for validation
  • People who want one calling style across OpenAI, Anthropic, Google, or local Ollama models

Not ideal for

  • People who only need plain chat text and no structured output, since the library adds nothing there
  • Developers who want a full agent runtime with tools and tracing; the README points to PydanticAI for that
  • Non-Python teams, unless they use one of the separate ports the README lists, whose maturity it does not describe
Step-by-step guide: how to use InstructorInstall, first run, examples, tips and FAQs
Instructor alternativesInstructor vs Pydantic AIInstructor vs LangChainInstructor vs LlamaIndex

How to get it

  1. 1

    Install with a package manager

    You'll need: Python · An API key for your chosen LLM provider, or a local model such as Ollama

    Install with pip

    pip install instructor

    Install with uv

    uv add instructor
  2. 2

    Run it

    • Install the package with pip or uv
    • Define a Pydantic model with the fields you want
    • Create a client with instructor.from_provider("openai/gpt-4o-mini") after setting your API key
    • Call client.chat.completions.create with response_model set to your model and print the result
  3. 3

    Get the most out of it

    • Add field_validator checks to your Pydantic model and use max_retries to let Instructor re-ask on failure
    • Use Partial[YourModel] with stream=True to display results as they arrive
    • Model nested objects with List[...] fields for richer extraction
    • Switch providers by changing the from_provider string, as shown in the README examples

Downloads

Source code (.zip)main branch · straight from GitHubRelease v1.17.02 files incl. instructor-1.17.0.tar.gzOfficial website & docspython.useinstructor.com/

Strengths

  • Uses Pydantic models, so the output is validated and typed in ordinary Python code
  • The README describes automatic retries that feed validation errors back to the model
  • Same calling code is described as working across several providers

Trade-offs

  • Output quality still depends on the underlying LLM; the README does not give accuracy figures
  • Provider-specific setup such as API keys is required, and the README's examples assume you have accounts with those providers
  • The README's marketing-style claims (usage numbers, company users) are not independently verified here

How it compares

ProjectStarsTypeLevelUpdatedBest for
instructor (this)14.1kLibrarybeginner10 days agoPython developers who need JSON-like data from an LLM for downstream code
pydantic-ai21kLibraryintermediate4 days agoPython developers building LLM-powered features that need structured, typed output
langchain149kFrameworkintermediate4 days agoPython developers building LLM-powered applications
llama_index52.8kLibraryintermediate10 days agoPython developers building retrieval-augmented generation (RAG) apps over private documents
whisper.cpp54.9kLibraryintermediate7 days agoDevelopers who want to embed offline speech-to-text in a C, C++, or other native app
openai-agents-python30.5kLibraryintermediate5 days agoPython developers building multi-step AI workflows

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.