Devtoolwatch BoardInstructor review
Instructor is a Python library for getting validated, structured outputs from LLMs using Pydantic models, with retries and streaming.
TL;DR
Instructor is a library that extracts structured, typed data from LLM responses using Pydantic models. It is for developers who need validated JSON from providers like OpenAI, Anthropic, Google, or local Ollama models. It focuses on schema-first extraction rather than agents, and offers automatic validation retries, partial streaming, and one API across providers.
- 14.1kGitHub stars
- +29new stars, week of Oct 25
- 2.2Mdownloads a week, +3% vs 4-week avg
- #19in Model SDKs and gateways this week
Instructor at a glance
- Category
- Model SDKs and gateways
- Maintained by
- 567-labs (organization, @567-labs on GitHub)
- License
- MIT
- Language
- Python, Shell
- Repository
- github.com/567-labs/instructor
- Website
- python.useinstructor.com
- PyPI package
- instructor 1.17.0
- Latest release
- v1.17.0 on GitHub, Sep 9, 2026
- First published
- Jun 14, 2023
What Instructor does
- Instructor turns natural language into typed Pydantic objects by passing a response_model to client.chat.completions.create.
- Instructor automatically retries failed validations, sending the validation error message back, controlled with max_retries.
- Instructor streams partial objects as they are generated using Partial response models with stream=True.
- Instructor extracts nested data structures, such as lists of nested Pydantic models.
- Instructor uses the same code across providers including OpenAI, Anthropic, Google, Ollama, Groq, Mistral, Cohere, and DeepSeek.
- Instructor supports native structured outputs on Bedrock through Mode.JSON_SCHEMA and Mode.TOOLS_STRICT as of v1.16.0.
- Instructor caches responses using per-client namespaces, with an explicit cache_namespace option for sharing results.
How it works
Instructor runs as a library inside your Python code. You create a client with instructor.from_provider and a provider/model string such as "openai/gpt-4o-mini", optionally passing an API key directly. You define a Pydantic model and pass it as response_model. Instructor calls the provider, validates the response against the model, and retries on validation failure. Implementations also exist for TypeScript, Ruby, Go, Elixir, and Rust.
How to install and start using Instructor
With pip
pip install instructorWith uv
uv add instructorWith Poetry
poetry add instructorRequirements
- Python 3.9 or later, below 4.0.
- An API key for your chosen hosted LLM provider, set in the environment or passed as api_key.
- Bedrock native structured outputs require boto3 1.42.42 or later.
First steps
- Install Instructor with pip, uv, or Poetry.
- Define a Pydantic BaseModel describing the fields you want, such as name and age.
- Create a client with instructor.from_provider, for example "openai/gpt-4o-mini".
- Call client.chat.completions.create with response_model and your messages to get a validated object.
Who Instructor is for
- Python developers extracting structured data from text with LLMs.
- Teams that want one extraction API across multiple LLM providers, including local Ollama models.
- Apps needing validated, typed LLM output without manual JSON parsing and retry code.
Limitations to know
- Instructor focuses on structured extraction; the README points to PydanticAI for agents, observability, and shareable traces.
- Since v1.17.0, response models with Instructor async-validator decorators are rejected; use Pydantic validators instead.
- Upgrading to v1.17.0 changes cache keys, so existing cache entries will miss.
- On Bedrock, remote HTTP(S) image and PDF URLs are blocked; only data URLs, base64, or s3:// sources are accepted.
Is Instructor growing? Usage data
In the week of Oct 25–31, 2026, Instructor ranked #309 on the Devtoolwatch Board and #19 in Model SDKs and gateways, with a momentum score of 30 out of 100. Its main package had 2.2M downloads that week, +3% against its own 4-week average.
Show the weekly numbers
| Week of | New stars |
|---|---|
| Aug 9, 2026 | 35 |
| Aug 16, 2026 | 40 |
| Aug 23, 2026 | 39 |
| Aug 30, 2026 | 37 |
| Sep 6, 2026 | 53 |
| Sep 13, 2026 | 45 |
| Sep 20, 2026 | 26 |
| Sep 27, 2026 | 26 |
| Oct 4, 2026 | 34 |
| Oct 11, 2026 | 33 |
| Oct 18, 2026 | 36 |
| Oct 25, 2026 | 29 |
On Hacker News
- Show HN: Instructor v1, for LLM structured output and streaming, 5 points and 0 comments (Apr 1, 2024)
The Board ranks tools by four signals each week: new stars, new stars for the repo's size, added downloads and download growth beyond the market. How the ranking works.
Instructor alternatives
Other LLM SDKs and gateways on the Board in the week of Oct 25–31, 2026, by momentum:
| Rank | Tool | Stars | Downloads/wk |
|---|---|---|---|
| #1 | thinking-orbsthinking-orbs is a React library of dotted, animated thought-orb loading indicators for AI and agent user interfaces. | 3.9k | 1.4M |
| #2 | HeadroomHeadroom compresses tool outputs, logs, files, and RAG chunks locally before they reach the LLM, as a library, proxy, or MCP server. | 78.5k | 125.8k |
| #3 | LiteLLMLiteLLM is an open source AI gateway and Python SDK that calls 100+ LLM providers through one OpenAI-format interface. | 62.5k | 23.1M |
| #4 | Honcho Memory library for building stateful agents | 7.9k | – |
| #5 | Anthropic SDKAnthropic SDK is the official Python library for calling the Claude API from Python applications. | 4k | 111M |
| #6 | Hugging Face HubHugging Face Hub is the official CLI and Python client for downloading, uploading and managing models, datasets and Spaces on the… | 4k | 68.3M |
Recent Instructor releases
Instructor FAQ
Is Instructor free and open source?
Yes. Instructor's source code is on GitHub (567-labs/instructor) under the MIT license, so you can use it for free.
How do I install Instructor?
Run pip install instructor. The instructor package needs Python 3.9 or newer, below 4.0. The install section above has the other options from the project's README.
Is Instructor still maintained?
Yes. The 567-labs/instructor repository was last updated on Oct 20, 2026, and the latest release, v1.17.0 on GitHub, came out on Sep 9, 2026.
How popular is Instructor?
Instructor has 14.1k GitHub stars as of Nov 1, 2026. It gained 29 new stars in the week of Oct 25–31, 2026, against a 12-week average of 36 a week. Its main package had 2.2M downloads that week, +3% against its own 4-week average. That made it #19 among LLM SDKs and gateways on the Devtoolwatch Board.
What are the best alternatives to Instructor?
Other LLM SDKs and gateways on the Devtoolwatch Board in the week of Oct 25–31, 2026, by momentum: thinking-orbs (#1), Headroom (#2), LiteLLM (#3), Honcho (#4), Anthropic SDK (#5). The alternatives table above has their numbers.
What is a Python Instructor alternative for agents?
Instructor's own docs recommend PydanticAI when you need agents. PydanticAI is the Pydantic team's agent runtime, adding typed tools, replayable datasets, evals, and dashboards while using the same Pydantic models.
Which LLM providers does Instructor support?
Instructor supports OpenAI, Anthropic, Google, Mistral, Cohere, Ollama, DeepSeek, Groq, Bedrock, and more, with 15+ providers listed. The same from_provider API is used for all of them.
Can Instructor work with local open source models?
Instructor works with local models through Ollama, for example instructor.from_provider("ollama/llama3.2").
What happens when the LLM output fails validation in Instructor?
Instructor automatically retries the request, including the validation error message, up to the max_retries you set.
Is Instructor only for Python?
Instructor started in Python, and implementations also exist for TypeScript, Ruby, Go, Elixir, and Rust.
Sources
Instructor README badge
Maintainers can show the tool's weekly Board rank in their README:
[](https://index.devtoolwatch.com/tools/instructor/)How this page is made: Devtoolwatch writes each review from the project's README, releases, package metadata and website, with an AI model, then checks every claim against the source it cites and drops what the sources don't support. The numbers come from Devtoolwatch's daily GitHub snapshots, GitHub's stargazer history, and the npm and PyPI download APIs. Spotted an error? Email [email protected].