Migration Guide

Migrate from older versions of the OpenAI Python SDK

This guide helps you migrate between major versions of the OpenAI Python SDK.

Version 2.x to Latest

Breaking Changes in v2.0.0

Function Call Output Types

In v2.0.0, the output field for function tool calls now supports images and files in addition to strings:

Before (v1.x):

# output was always a string
output: str = tool_call.output

After (v2.x):

# output can be string or list of content items
output: str | list[ResponseInputText | ResponseInputImage | ResponseInputFile] = tool_call.output

# Check the type before using
if isinstance(output, str):
    print(output)
else:
    for item in output:
        if item.type == "input_text":
            print(item.text)
        elif item.type == "input_image":
            print(item.image_url)

This change affects ResponseFunctionToolCallOutputItem.output and ResponseCustomToolCallOutput.output.

Version 1.x to 2.x

Package Compatibility

Version 2.x maintains backward compatibility for most features. Update your package:

pip install --upgrade openai

New Features in v2.x

Responses API Enhancements

from openai import OpenAI

client = OpenAI()

# Enhanced function calls with multi-modal outputs
response = client.responses.create(
    model="gpt-5.2",
    input="Analyze this image and create a chart",
    tools=[...],
)

# Tool outputs can now include images and files
for output_item in response.output:
    if output_item.type == "function_tool_call_output":
        # Handle multi-modal outputs
        if isinstance(output_item.output, str):
            print(output_item.output)
        else:
            for content in output_item.output:
                # Process text, images, or files
                print(content.type)

Version 0.x to 1.x

Version 0.x is no longer supported. Please upgrade to v1.x or later.

Major Changes

Version 1.0 was a complete rewrite with many breaking changes:

Client Initialization

Before (v0.x):

import openai

openai.api_key = "sk-..."
response = openai.ChatCompletion.create(...)

After (v1.x):

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(...)

Resource Structure

Before (v0.x):

openai.ChatCompletion.create(...)
openai.Completion.create(...)
openai.Image.create(...)

After (v1.x):

client.chat.completions.create(...)
client.completions.create(...)
client.images.generate(...)

Error Handling

Before (v0.x):

import openai

try:
    response = openai.ChatCompletion.create(...)
except openai.error.RateLimitError as e:
    print(e)

After (v1.x):

import openai
from openai import OpenAI

client = OpenAI()

try:
    response = client.chat.completions.create(...)
except openai.RateLimitError as e:
    print(e)

Async Support

Before (v0.x):

import openai

openai.api_key = "sk-..."
response = await openai.ChatCompletion.acreate(...)

After (v1.x):

from openai import AsyncOpenAI

client = AsyncOpenAI(api_key="sk-...")
response = await client.chat.completions.create(...)

Streaming

Before (v0.x):

for chunk in openai.ChatCompletion.create(stream=True, ...):
    print(chunk)

After (v1.x):

stream = client.chat.completions.create(stream=True, ...)
for chunk in stream:
    print(chunk)

Migration Checklist

1. Update imports

   Change from module-level functions to client-based API:

   # Old
   import openai
   
   # New
   from openai import OpenAI
   client = OpenAI()
   
2. Update API calls

   Migrate resource paths:

   # Old: openai.Resource.method(...)
   # New: client.resource.method(...)
   
3. Update error handling

   Error classes moved:

   # Old: openai.error.RateLimitError
   # New: openai.RateLimitError
   
4. Update async usage

   Use AsyncOpenAI client:

   # Old: await openai.Resource.acreate(...)
   # New: 
   from openai import AsyncOpenAI
   client = AsyncOpenAI()
   await client.resource.create(...)
   
5. Test thoroughly

   Test all API interactions in your application to ensure compatibility.

Python Version Support

SDK Version	Minimum Python Version
2.x	Python 3.9+
1.x	Python 3.8+ (3.8 deprecated)
0.x	Python 3.7+

Python 3.8 support was dropped in SDK version 2.7.1. Please upgrade to Python 3.9 or later.

Deprecated Features

Assistants API

The Assistants API is deprecated in favor of the Responses API:

Deprecated:

assistant = client.beta.assistants.create(...)

Use instead:

response = client.responses.create(...)

See the Responses API documentation for migration details.

Getting Help

If you encounter issues during migration:

1. Check the CHANGELOG for detailed version changes
2. Review the API Reference for current method signatures
3. Visit the GitHub issues for community support
4. See the examples directory for working code samples

Version Detection

Check your installed version:

import openai

print(openai.__version__)

Or via command line:

pip show openai