Open AI Code Interpreter

Code Interpreter is a built in tool in the OpenAI API that lets a model write Python code and actually run it inside a sandboxed environment, then use the results to finish the task. This is different from plain code generation, where the model only writes code as text and cannot execute it. With Code Interpreter, the model can calculate, transform data, create charts, read files you provide, and generate new files as outputs. A small but important naming detail is that even though the docs call it Code Interpreter, the model “knows” and refers to it as the python tool. If you want to make tool usage more explicit in your prompting, telling the model to “use the python tool” is the clearest instruction.

The mental model: model, tool, container, outputs

When you enable Code Interpreter, you are giving the model access to a Python runtime that lives inside a container. The container is a fully sandboxed virtual machine that the model can run Python code in, and it can hold files you upload or files the model creates.

A typical interaction looks like this conceptually:

The user asks a question or provides files.
Your app calls the Responses API with the Code Interpreter tool enabled.
The model decides whether it needs Python. If yes, it writes code, executes it in the container, sees the results, and may iterate until it succeeds.
The model returns a normal assistant message that explains the result, and it can attach references to any files it generated in the container.

This design is especially useful for tasks where correctness depends on computation and where intermediate failures are normal, like data cleaning, parsing messy files, or statistical analysis. The model can run code, see an exception, fix the code, rerun, and only then respond.

Containers: how they are created, reused, and why they expire

Code Interpreter requires a container object. You can create or select a container in two main ways.

Auto container mode
You set the tool with container: { type: "auto" } (optionally with a memory limit and file ids). In this mode, the system will create a new container or reuse an active container that is already in context from a previous Code Interpreter call. This makes it easy to keep continuity across turns, because you do not need to manage container ids yourself.

Explicit container mode
You create a container yourself using the containers API, then pass its id into the tool configuration for your Responses API call. This gives you more control, for example if you want to deliberately reuse the same container across multiple requests from your server, or if you want a specific memory tier.

Memory tiers
You can choose from memory limits such as 1g as the default, and larger tiers like 4g, 16g, or 64g. That memory limit applies for the life of the container.

Expiration and ephemerality
Containers are meant to be treated as ephemeral. A container expires if it is not used for 20 minutes, and when it expires, the data is discarded and not recoverable. You cannot reactivate an expired container; you create a new one and upload files again. Container operations like retrieving the container or adding or deleting files refresh the container’s last active time.

This is the reason you should treat Code Interpreter as a compute workspace, not as long term storage. If you need something later, download it and store it in your own system.

Files: how to give the model data, and how to get generated artifacts back

There are two separate but related file concepts:

Files in model input
When you include a file as part of the model input, it is automatically uploaded to the container when Code Interpreter runs. You do not need to separately upload it into the container.

Files generated inside the container
The model can create files in the container while it is running Python, for example a CSV of cleaned data, or an image file of a chart. When it does this, the next assistant message can include annotations that cite those container files. These citations include the container id, the file id, and the filename, and you can parse them to present download options in your app.

Downloading generated files
To download a file created in the container, you call the container files content endpoint, conceptually:

GET /v1/containers/{container_id}/files/{file_id}/content

The response is the binary content of the file.

If you want to upload or manage files inside a container directly, there are container file endpoints for creating, listing, retrieving metadata, retrieving content, and deleting.

Prompting patterns that work well with Code Interpreter

Make the model’s decision easy
Instead of asking vaguely, directly grant permission and set expectations, for example: “Use the python tool to compute the answer and show the final numeric result.”

Tell it what to produce
If you want a file, say so explicitly: “Create a CSV with the cleaned data and a PNG chart, then cite the files.”

Ask it to verify with code
For math and data questions: “Compute with the python tool, then cross check with an independent method.”

Keep important state in files
Even if a container stays active, treat it as ephemeral. If a result matters, write it to a file and download it.

End to end example 1: the smallest useful Code Interpreter call

This example enables Code Interpreter in a Responses API request and asks for a math solution. It uses auto container mode.

Python

from openai import OpenAI

client = OpenAI()

instructions = """
You are a personal math tutor.
When asked a math question, use the python tool to compute the answer.
Return the final answer and a short explanation.
"""

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "code_interpreter",
            "container": {"type": "auto", "memory_limit": "4g"},
        }
    ],
    instructions=instructions,
    input="Solve 3x + 11 = 14. Show x.",
)

print(resp.output_text)

What you should expect to happen

The model sees the instruction to use the python tool, runs the algebra computation in Python, then returns x = 1 with a short explanation. The exact formatting depends on the model, but the key point is that the computation is executed, not guessed.

End to end example 2: explicit container creation and forcing tool usage

Sometimes you want stronger control. In explicit mode, you create the container first, then pass its id into the response call. You can also set tool_choice to required so the model must use tools for that request.

Python

from openai import OpenAI

client = OpenAI()

container = client.containers.create(
    name="analysis-container",
    memory_limit="4g",
)

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "code_interpreter",
            "container": container.id,
        }
    ],
    tool_choice="required",
    input="""
Use the python tool to do all computations.

Compute 4 * 3.82.
Then take the square root of that result.
Then take the square root again.
Return each intermediate value.
""",
)

print(resp.output_text)
print("container_id:", container.id)

Why this is useful

You now have a specific container_id you can reuse on later requests, as long as it remains active. You can also manage its lifecycle explicitly via the containers endpoints, and you can choose memory tiers at creation time.

End to end example 3: upload a CSV, analyze it, generate a chart, download the chart

This example shows the full “data analysis plus artifact output” workflow.

Conceptual flow

Create a local CSV file.
Upload it using the Files API with purpose user_data.
Call the Responses API with Code Interpreter enabled and include the file id in the input message.
Ask the model to read the CSV with the python tool, compute metrics, and save a chart as a PNG file.
Parse the response to find container_file_citation annotations, then download the file content using the container files content endpoint.

Python

import csv
from pathlib import Path
from openai import OpenAI

client = OpenAI()

# Create a tiny CSV locally for the demo
csv_path = Path("sales.csv")
rows = [
    ["date", "region", "revenue"],
    ["2026-01-01", "west", "1200"],
    ["2026-01-02", "west", "900"],
    ["2026-01-01", "east", "700"],
    ["2026-01-02", "east", "1100"],
]
with csv_path.open("w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerows(rows)

# Upload the file to OpenAI Files
uploaded = client.files.create(
    file=csv_path.open("rb"),
    purpose="user_data",
)

# Ask the model to analyze it with Code Interpreter
resp = client.responses.create(
    model="gpt-4.1",
    tools=[{"type": "code_interpreter", "container": {"type": "auto", "memory_limit": "4g"}}],
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": """
Use the python tool.

Read the uploaded CSV.
Compute total revenue by region.
Create a bar chart of revenue by region.
Save the chart as chart.png in the container.
Then explain the result in plain English.
"""},
                {"type": "input_file", "file_id": uploaded.id},
            ],
        }
    ],
)

# Print the assistant's explanation
print(resp.output_text)

# Extract container file citations
citations = []
for item in resp.output:
    if item.type == "message":
        for part in item.content:
            ann = getattr(part, "annotations", None)
            if not ann:
                continue
            for a in ann:
                if a["type"] == "container_file_citation":
                    citations.append(a)

print("Found citations:", citations)

# At this point you can download the file bytes:
# Send an authenticated GET request to:
# /v1/containers/{container_id}/files/{file_id}/content
# using citations[0]["container_id"] and citations[0]["file_id"].

Key details that make this work

The file is included in the model input as an input_file with a file id. 
Any files in the model input are automatically uploaded to the container for Code Interpreter runs.
When the model creates chart.png, the next message can include a container_file_citation annotation with the container id and file id.
You download the chart by calling the container file content route for that container id and file id.

End to end example 4: image or document processing as a Python powered vision helper

Code Interpreter is also useful as an “analysis workbench” for images and documents, because Python can load images, crop, rotate, compute histograms, and generate derived images. The docs explicitly call out that the model can use the tool to crop, zoom, rotate, and otherwise process images as part of problem solving.

A practical workflow

Upload an image as an input file.
Ask the model to use the python tool to do preprocessing, for example crop to a region of interest, rotate, enhance contrast, compute statistics, then save the processed image as a new file.
Parse the returned container file citation and download the processed output.

This pattern is extremely useful when you want reproducible image transformations, or when you want the model to compute objective measurements rather than rely on a purely verbal description.

Operational considerations for real products

Latency and iteration
Because the model may run code multiple times, tool enabled requests can take longer than pure text. The tradeoff is higher correctness for computation heavy work.

Rate limits
The guide lists an availability of 100 requests per minute per organization for this tool across APIs, so you should design with throttling and retries in mind.

Cost control
Memory tier selection matters. If most tasks are small, keep the default tier. Move to larger tiers only when needed.

Robustness pattern
When you want highly reliable pipelines, prompt the model to write intermediate outputs to files, then read them back and validate, rather than relying on a single pass.

If you want, tell me what kind of example you care about most, like analyzing a spreadsheet, generating a PDF report, or cleaning JSON logs, and I will write a tailored end to end sample that includes the exact prompts and the response parsing logic for citations.