Install Instructor in Python Guide

Installing Instructor in Python is simple. This guide shows you the exact steps. You will learn how to set it up quickly.

Instructor is a powerful Python library. It helps you extract structured data from large language models. It works with OpenAI, Anthropic, and other providers.

This article covers everything. From basic installation to testing your setup. Follow along with code examples.

Prerequisites

Before you install Instructor, you need Python. Make sure you have Python 3.9 or later. Check your version with this command.

python --version

You also need pip. This is Python's package installer. Verify it is available.

pip --version

Virtual environments are recommended. They keep your projects clean. Create one with python -m venv myenv.

Step 1: Install Instructor via pip

Open your terminal or command prompt. Run the following command.

pip install instructor

This downloads the latest version. You will see progress bars. Wait for completion.

The command installs all dependencies. These include Pydantic and httpx. Everything works out of the box.

Step 2: Verify the Installation

Check that Instructor installed correctly. Run a quick Python import test.

# Verify Instructor installation
import instructor
print("Instructor version:", instructor.__version__)

You should see output with a version number. Something like 1.3.0 or higher.

Instructor version: 1.3.0

If you see an ImportError, try reinstalling. Use pip install --upgrade instructor.

Step 3: Set Up Your API Key

Instructor needs an API key. Most users connect to OpenAI. Set your key as an environment variable.

export OPENAI_API_KEY="your-api-key-here"

On Windows, use set OPENAI_API_KEY=your-api-key-here. Replace with your real key.

Never hardcode your API key in scripts. Use environment variables for security.

Step 4: Write a Simple Example

Now create a Python file. We will extract structured data from text. This shows Instructor in action.

# example.py
import instructor
from openai import OpenAI
from pydantic import BaseModel

# Define a data model
class UserInfo(BaseModel):
    name: str
    age: int

# Patch the OpenAI client
client = instructor.from_openai(OpenAI())

# Extract structured data
user = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=UserInfo,
    messages=[
        {"role": "user", "content": "John is 30 years old."}
    ]
)

print(user.name)  # Output: John
print(user.age)   # Output: 30

Run the script with python example.py. You will see the extracted fields printed.

John
30

The response_model parameter is key. It tells Instructor what structure to expect.

Step 5: Install Optional Dependencies

Instructor supports other providers. Install extras for Anthropic or Google AI.

pip install "instructor[anthropic]"
pip install "instructor[google-generativeai]"

Use pip install "instructor[all]" to get everything. This includes all optional backends.

Troubleshooting Common Issues

Sometimes installation fails. Here are solutions for common problems.

Error: "pip not found" — Install pip first. Use python -m ensurepip --upgrade.

Error: "Permission denied" — Use pip install --user instructor. This installs for your user only.

Error: "Version conflicts" — Create a fresh virtual environment. Then install Instructor again.

Best Practices

Always use a virtual environment. This prevents package conflicts between projects.

Keep Instructor updated. Run pip install --upgrade instructor regularly.

Use pip freeze to save your dependencies. Share them with your team.

pip freeze > requirements.txt

This creates a file with all installed packages. Others can install them with pip install -r requirements.txt.

Conclusion

Installing Instructor in Python is straightforward. You learned how to install it with pip. You verified the setup with a test import.

You wrote your first extraction script. It used Pydantic models for structured output. This is the core power of Instructor.

Now you can build applications that extract data from text. Use it for chatbots, data parsing, and more.

Remember to use virtual environments and keep your API keys secure. Happy coding with Instructor!