13.8k stars · MIT · v1.16.0 (2026-08-27) · Track this in Rising ↗
Pydantic-validated structured output from any LLM, with automatic retry on malformed responses — so the subtopic map cannot fail to parse.
Radar check
What we found when we opened it. Every bar is one fact, with its date.
Last code pushed 26 Oct 2026, one day before this check.
Latest release v1.17.0 on 9 Sep 2026.
Public since June 2023, a little over 3 years.
14,067 stars and 1,344 forks.
113 commits and 58 new issues in the last 90 days.
267 contributors. 29 pull requests merged in 90 days.
No security policy file says how to report a problem. No published security advisories.
How the bars are scored
- Alive. Days since the last code push: a week or less 100, a month 90, three months 70, six months 50, a year 30, eighteen months 15, older 0.
- Releases. Age of the latest GitHub release, on a similar scale; no bar when the project publishes no releases.
- Maturity. Age of the project: eight years 100, five 90, three 70, two 55, one 40, six months 25, younger 10.
- Adoption. Stars on a log scale: 100,000 stars is 100, 10,000 is 80, 1,000 is 60, 100 is 40.
- Activity. Commits in the last 90 days: 300 or more 100, 100 85, 30 65, 10 45, any 25.
- Community. People who have contributed: 100 or more 100, 30 80, 10 60, 5 40, 2 25, one 10.
- Security. A published security policy 80, none 40; published advisories are listed, not scored.
Checked by Repo Radar on 27 Oct 2026 from the repository on GitHub. Covered in Edition 5.
▶Repo detailsthe review · specs · pros & cons · install
What it does
You describe the answer you want as a Pydantic model, which is the standard Python way to declare the fields and types of a piece of data. The library turns that into the schema the provider needs, sends the request, and checks the reply against the model. If the reply does not validate, it asks again, including the validation error in the new request so the model can see what was wrong. Results can be streamed as they arrive, and lists of items can be returned one at a time. The same code works across providers, with examples for several paid services and for models running locally. What it does not do is guarantee the answer is right: it enforces the shape only, so a confidently wrong value in the correct field passes every check. Its own README draws the line at agents, pointing elsewhere for those.
Why it matters
Who it suits. Anyone whose program feeds a model's answer straight into a screen, a table or a database. Structured output is where the "sometimes the page just fails" class of fault comes from, and that fault is fatal in anything whose purpose is to make a mess readable. It also suits anyone changing prompts often, because the declared model becomes the contract and a reworded prompt cannot quietly change the shape. Skip it if the output is meant to be prose. And skip it if a strict shape is being forced on a weak model, because the retries will cost more than a better model would.
Verdict. Worth an hour, and one of the easiest wins on this page if a model's output is already being parsed by hand. The schema is a Pydantic class, which an existing FastAPI application already uses, so there is no new vocabulary. In good health: 13,992 stars, a release on 9 September 2026, code on 8 October 2026, and only 44 open issues. Three honest costs. Every retry is a paid request and added delay, so a strict shape against a weak model can quietly multiply the price, which is exactly why entry #9 belongs in front of it. It promises the shape and never the quality. And it is one more layer between the code and the provider, so an odd failure now has two places to look. pydantic/pydantic-ai is where the same team's thinking goes for agents rather than extraction.
Summary (Key Points)from the README
Key features
- Typed extraction: Define a Pydantic model and get structured data back, with validation and IDE support.
- Automatic retries: Failed validations are retried with the error message sent back to the model.
- Streaming: Partial objects are streamed as they are generated.
- Nested objects: Complex, nested data structures can be extracted.
- Provider-agnostic code: The same code works across LLM providers, which the README describes as "every major provider" without naming them.
- Simple scope: Focused on one task, structured extraction, rather than a broad agent framework.
- Multiple languages: Implementations are listed for Python, TypeScript, Ruby, Go, Elixir and Rust.
- Adoption figures: The README cites 3M+ monthly downloads, 10K+ GitHub stars, 1000+ community contributors and over 100,000 developers.
Ways to install
| Platform or method | What it needs | Effort |
|---|---|---|
| Python (the original) | Not stated in README | Not stated in README |
| TypeScript | Not stated in README | Not stated in README |
| Ruby | Not stated in README | Not stated in README |
| Go | Not stated in README | Not stated in README |
| Elixir | Not stated in README | Not stated in README |
| Rust | Not stated in README | Not stated in README |
Important
- Not for agent workloads: The README points to PydanticAI for agent runs, built-in observability, traces, evals and dashboards.
- Self-reported figures: The download, star, contributor and developer counts and the company list come from the project itself and are not independently verified in the README.
- Comparisons are the project's own: The claims that Instructor is "lighter, faster, and easier to debug" than LangChain or LlamaIndex are not backed by benchmarks in the README.
- Missing details: The README does not name the supported providers, give retry limits, or show install commands in the text provided.
- Retries add model calls: Automatic retries mean repeated LLM requests when validation fails, so usage and cost depend on how often that happens.
- License: MIT, with details in the LICENSE file.
Written by an AI model from the project’s README; not part of the review, and it can be wrong.
- The shape is an ordinary Pydantic class, which an existing Python web application almost certainly already uses.
- Automatic retry with the validation error fed back, which fixes most malformed replies before the calling code sees them.
- MIT licence, 44 open issues, a release on 9 September 2026 and code on 8 October 2026, and it works across providers.
- Retries cost money and add delay, so a strict shape against a weak model can multiply the price of a request.
- It guarantees the shape of an answer and never its truth: a confidently wrong value validates perfectly.
- One more layer between the code and the provider, which means one more place to look when something behaves oddly.
python3 -m venv venv source venv/bin/activate pip install instructor
