# Instructor review

> Instructor is a Python library for getting validated, structured outputs from LLMs using Pydantic models, with retries and streaming.

Devtoolwatch Board, the week of Oct 25–31, 2026. Canonical page: https://index.devtoolwatch.com/tools/instructor/

## 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.

## Instructor at a glance

- **Category:** [Model SDKs and gateways](https://index.devtoolwatch.com/categories/model-sdks-and-gateways/)
- **Maintained by:** 567-labs (organization, [@567-labs](https://github.com/567-labs) on GitHub)
- **License:** MIT
- **Language:** Python, Shell
- **Repository:** [github.com/567-labs/instructor](https://github.com/567-labs/instructor)
- **Website:** [python.useinstructor.com](https://python.useinstructor.com/)
- **PyPI package:** [instructor](https://pypi.org/project/instructor/) 1.17.0
- **Latest release:** [v1.17.0](https://github.com/567-labs/instructor/releases/tag/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 Instructor

**With pip**

```
pip install instructor
```

**With uv**

```
uv add instructor
```

**With Poetry**

```
poetry add instructor
```

### Requirements

- 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

1. Install Instructor with pip, uv, or Poetry.
2. Define a Pydantic BaseModel describing the fields you want, such as name and age.
3. Create a client with instructor.from_provider, for example "openai/gpt-4o-mini".
4. 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

- 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.

## Usage data (the week of Oct 25–31, 2026)

- Board rank: #309 overall, #19 in Model SDKs and gateways, momentum score 30
- Downloads that week: 2.2M (+3% vs 4-week average)
- New GitHub stars per week (last 12 weeks): Aug 9: 35; Aug 16: 40; Aug 23: 39; Aug 30: 37; Sep 6: 53; Sep 13: 45; Sep 20: 26; Sep 27: 26; Oct 4: 34; Oct 11: 33; Oct 18: 36; Oct 25: 29

## Instructor alternatives

| Rank | Tool | Stars | Downloads/wk |
|---|---|---|---|
| #1 | [thinking-orbs](https://index.devtoolwatch.com/tools/jakubantalik-thinking-orbs/) | 3.9k | 1.4M |
| #2 | [Headroom](https://index.devtoolwatch.com/tools/headroomlabs-ai-headroom/) | 78.5k | 125.8k |
| #3 | [LiteLLM](https://index.devtoolwatch.com/tools/litellm/) | 62.5k | 23.1M |
| #4 | [Honcho](https://index.devtoolwatch.com/tools/plastic-labs-honcho/) | 7.9k | – |
| #5 | [Anthropic SDK](https://index.devtoolwatch.com/tools/anthropic-sdk/) | 4k | 111M |
| #6 | [Hugging Face Hub](https://index.devtoolwatch.com/tools/hf-hub/) | 4k | 68.3M |

## 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

1. [567-labs/instructor on GitHub](https://github.com/567-labs/instructor)
2. [Instructor README](https://github.com/567-labs/instructor/blob/main/README.md)
3. [instructor on PyPI](https://pypi.org/project/instructor/)
4. [Instructor website](https://python.useinstructor.com/)
5. [Release v1.17.0 (Sep 9, 2026)](https://github.com/567-labs/instructor/releases/tag/v1.17.0)
6. [Release v1.16.0 (Aug 27, 2026)](https://github.com/567-labs/instructor/releases/tag/v1.16.0)
7. [Release v1.15.4 (Jun 28, 2026)](https://github.com/567-labs/instructor/releases/tag/v1.15.4)
8. [Hacker News: Show HN: Instructor v1, for LLM structured output and streaming](https://news.ycombinator.com/item?id=39898093)
9. [Devtoolwatch Board, the week of Oct 25–31, 2026](https://index.devtoolwatch.com/)