{"id":30,"library":"instructor","title":"Instructor","description":"Structured data extraction from LLMs via Pydantic models. Patches or wraps provider clients (OpenAI, Anthropic, Gemini, Cohere, Mistral, Groq, Ollama, and 15+ others) to add response_model, automatic validation, and retry logic. Uses tool-calling or JSON mode depending on provider. Core interface: client.chat.completions.create(response_model=MyModel, ...) returns a validated Pydantic instance. Maintained by Jason Liu / jxnl.","status":"active","version":"1.14.5","language":"python","source_language":"en","source_url":"https://python.useinstructor.com/","tags":["instructor","structured-outputs","pydantic","openai","anthropic","gemini","extraction","validation","llm","tool-calling"],"install":[{"cmd":"pip install instructor","lang":"bash","label":"Base (OpenAI only)"},{"cmd":"pip install 'instructor[anthropic]'","lang":"bash","label":"Anthropic"},{"cmd":"pip install 'instructor[google-genai]'","lang":"bash","label":"Google Gemini"},{"cmd":"pip install 'instructor[groq]'","lang":"bash","label":"Groq"},{"cmd":"pip install 'instructor[litellm]'","lang":"bash","label":"LiteLLM (any provider)"}],"dependencies":[{"reason":"Bundled as a required dependency even for non-OpenAI providers. Instructor uses the OpenAI client interface as its base proxy model.","package":"openai","optional":false},{"reason":"Required. Pydantic v2 only — v1 is not supported.","package":"pydantic","optional":false},{"reason":"Required. Powers automatic retry logic on validation failures.","package":"tenacity","optional":false}],"imports":[{"note":"instructor.patch() removed in 1.0.0. Replace with instructor.from_openai(). The patched client is now a proper wrapper, not a monkey-patch.","wrong":"import instructor; client = instructor.patch(openai.OpenAI())","symbol":"from_openai","correct":"import instructor; import openai; client = instructor.from_openai(openai.OpenAI())"},{"note":"from_provider() requires provider-prefixed model strings in 'provider/model' format. Bare model names like 'gpt-4o' raise errors — must be 'openai/gpt-4o', 'anthropic/claude-3-5-sonnet', 'ollama/llama3.2', etc.","wrong":"import instructor; client = instructor.from_provider('gpt-4o')","symbol":"from_provider","correct":"import instructor; client = instructor.from_provider('openai/gpt-4o')"}],"quickstart":{"code":"import instructor\nfrom pydantic import BaseModel\n\nclass User(BaseModel):\n    name: str\n    age: int\n\n# Unified provider interface (1.x recommended)\nclient = instructor.from_provider('openai/gpt-4o-mini')\n\nuser = client.chat.completions.create(\n    response_model=User,\n    messages=[{'role': 'user', 'content': 'John is 25 years old'}],\n)\nprint(user)  # User(name='John', age=25)","lang":"python","description":"from_provider() is the 1.x unified interface. For per-provider clients use instructor.from_openai(), instructor.from_anthropic(), etc."},"warnings":[{"fix":"Replace instructor.patch(openai.OpenAI()) with instructor.from_openai(openai.OpenAI()). For Anthropic: instructor.from_anthropic(anthropic.Anthropic()).","message":"instructor.patch() removed in 1.0.0. All pre-1.0 code using instructor.patch(openai.OpenAI()) breaks with AttributeError.","severity":"breaking","affected_versions":"< 1.0.0"},{"fix":"Migrate models to Pydantic v2. The @validator decorator is replaced by @field_validator; Config class is replaced by model_config = ConfigDict(...).","message":"Pydantic v1 not supported. instructor requires Pydantic v2.","severity":"breaking","affected_versions":"all"},{"fix":"Install the appropriate extra for your provider: instructor[anthropic], instructor[google-genai], instructor[groq], instructor[cohere], instructor[mistral], instructor[litellm], etc.","message":"Provider-specific extras required for non-OpenAI backends. Using instructor.from_anthropic() without pip install 'instructor[anthropic]' raises ImportError.","severity":"breaking","affected_versions":"all"},{"fix":"Use prefixed strings: 'openai/gpt-4o', 'anthropic/claude-3-5-sonnet-latest', 'google/gemini-2.0-flash', 'ollama/llama3.2', 'groq/llama-3.1-8b-instant'.","message":"from_provider() requires 'provider/model' string format. Bare model names raise ValueError.","severity":"breaking","affected_versions":">= 1.x"},{"fix":"Check the mode comparison table at python.useinstructor.com/modes-comparison/. Pass mode=instructor.Mode.JSON explicitly if the provider doesn't support tool-calling.","message":"Each provider uses a different default Mode (tool-calling vs JSON). Anthropic uses ANTHROPIC_TOOLS by default; OpenAI uses TOOLS. Mixing providers without checking mode compatibility causes silent output degradation or errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Set max_retries=3 or higher for unreliable models. Catch instructor.exceptions.InstructorRetryException explicitly. Simplify schemas to reduce retry rate.","message":"max_retries controls validation retry attempts, not HTTP retries. Default is 1 retry on Pydantic validation failure. Complex schemas with small models frequently exhaust retries silently and raise InstructorRetryException.","severity":"gotcha","affected_versions":"all"},{"fix":"Only access fields after the final yielded object. Use create_iterable() for extracting multiple complete objects instead of partial streaming.","message":"Streaming with create_partial() returns Partial[T] objects where fields are None until generated. Accessing fields before the stream completes returns None — not an error.","severity":"gotcha","affected_versions":"all"},{"fix":"Expected behavior. Do not attempt to uninstall openai when using other providers.","message":"openai is a required dependency even when using non-OpenAI providers (Anthropic, Gemini, etc.). This is by design — instructor proxies through OpenAI's interface structure.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade your Python environment to version 3.10 or newer.","message":"Instructor uses type annotation union syntax (e.g., `Type1 | Type2`) which is natively supported only from Python 3.10. Using Instructor with Python versions below 3.10 will result in a `TypeError: Unable to evaluate type annotation 'Type1 | Type2'`.","severity":"breaking","affected_versions":"< 3.10"},{"fix":"Set the OPENAI_API_KEY environment variable or pass `api_key` directly to the `openai.OpenAI` client when initializing it for instructor (e.g., `instructor.from_openai(openai.OpenAI(api_key='YOUR_KEY'))`).","message":"OpenAI API key must be provided. When using OpenAI models with `instructor.from_provider('openai/model_name')` or `instructor.from_openai()`, ensure the API key is passed directly to the client constructor or set via the OPENAI_API_KEY environment variable.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T05:02:16.106Z","next_check":"2026-05-28T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install instructor`.","cause":"The 'instructor' library is not installed in your Python environment or is not accessible within your current virtual environment.","error":"ModuleNotFoundError: No module named 'instructor'"},{"fix":"Update your code to use `instructor.from_openai(OpenAI())` for OpenAI clients or `instructor.from_provider('your_provider/model_name')` for other providers: \n```python\nimport instructor\nfrom openai import OpenAI\n\n# Old (will cause error)\n# client = instructor.patch(OpenAI())\n\n# New way for OpenAI\nclient = instructor.from_openai(OpenAI())\n\n# Or for other providers, e.g., Anthropic\n# import anthropic\n# client = instructor.from_provider(anthropic.Anthropic())\n```","cause":"The `instructor.patch()` function has been deprecated and replaced by `instructor.from_openai()` or `instructor.from_provider()` for creating an Instructor-enhanced client.","error":"ModuleNotFoundError: No module named 'instructor.patch'"},{"fix":"Review your Pydantic model definition for correctness and ensure it accurately reflects the expected output structure. Provide clearer or more specific instructions in your LLM prompt to guide the model towards generating output that matches the schema. You can also inspect `e.failed_attempts` if catching `InstructorRetryException` (or `e` directly if `ValidationError`) for the raw LLM output that caused the failure to debug. Consider simplifying the model or adding more robust Pydantic validators.","cause":"The Large Language Model's (LLM) raw response did not conform to the schema defined by your Pydantic `response_model`, and Instructor's retry mechanism (if enabled) was exhausted.","error":"ValidationError: 1 validation error for MyModel ..."},{"fix":"Access the original client via `client.client` (e.g., `client.client.moderations.create(...)`) or ensure the method you're trying to call is part of the `chat.completions` API that `instructor` directly enhances. Instructor primarily extends `client.chat.completions.create` to include `response_model`.","cause":"You are attempting to call a method (e.g., `moderations`) directly on an `Instructor`-wrapped client that was not part of the original client's patched API or is not directly exposed through the `Instructor` object's top-level attributes.","error":"AttributeError: 'Instructor' object has no attribute 'moderations'"},{"fix":"Check the specific integration documentation for the LLM provider you are using with `instructor` to understand the expected input format. You might need to manually map your `messages` to the provider's specific content structure (e.g., `contents` for Gemini/Vertex AI) or ensure you're using a compatible `mode` for that provider (e.g., `instructor.Mode.VERTEXAI_TOOLS` or `instructor.Mode.VERTEXAI_JSON`). Ensure your client is initialized with the correct `from_provider` function for the specific LLM.","cause":"This error often occurs when using `instructor` with a specific LLM provider (like Google's Gemini/Vertex AI) where the underlying client's method (e.g., `generate_content`) expects different argument names or structures than the standard OpenAI-like `messages` parameter that Instructor's patching might try to pass by default.","error":"TypeError: _GenerativeModel.generate_content() got an unexpected keyword argument 'messages'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":70,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"anthropic","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"google-genai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"groq","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"litellm","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}