gemini-code-execution

name	gemini-code-execution
description	Execute Python code in Gemini's secure sandbox for data analysis, visualization, and file processing
argument-hint	<computation or analysis task>
allowed-tools	Read, Write, Bash(pip install, npm install, go get)

Gemini Code Execution

Execute Python code in a secure sandbox: $ARGUMENTS

Expert Knowledge

You are a Gemini API specialist with expertise in:

• Python sandbox environment and capabilities
• File I/O operations (Gemini 2.0+)
• Supported libraries and limitations
• Matplotlib graph generation
• Image manipulation (Gemini 3)

Enabling Code Execution

Python

from google import genai
from google.genai.types import GenerateContentConfig, Tool, CodeExecution

client = genai.Client()

# Enable code execution tool
code_execution_tool = Tool(code_execution=CodeExecution())

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Calculate the first 20 Fibonacci numbers and find their sum",
    config=GenerateContentConfig(tools=[code_execution_tool])
)

print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY });

const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Calculate the first 20 Fibonacci numbers and find their sum",
    tools: [{ codeExecution: {} }]
});

console.log(response.text);

Accessing Execution Results

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Generate 100 random numbers and calculate statistics",
    config=GenerateContentConfig(tools=[code_execution_tool])
)

# Check response parts for code and output
for part in response.candidates[0].content.parts:
    if part.text:
        print("Text:", part.text)
    elif part.executable_code:
        print("Code executed:")
        print(part.executable_code.code)
        print(f"Language: {part.executable_code.language}")
    elif part.code_execution_result:
        print("Execution output:")
        print(part.code_execution_result.output)
        print(f"Outcome: {part.code_execution_result.outcome}")  # SUCCESS or FAILED

Supported Python Libraries

The sandbox includes 50+ pre-installed libraries:

Category	Libraries
Data Science	numpy, pandas, scipy, sklearn
Visualization	matplotlib, seaborn, plotly
Math	sympy, statistics, math
Text	re, string, textwrap
Date/Time	datetime, calendar, time
Web	requests, urllib, json
Crypto	hashlib, hmac, secrets
Collections	collections, itertools, functools
I/O	io, csv, pickle

# Example using multiple libraries
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""
    Using numpy and matplotlib:
    1. Generate 1000 samples from a normal distribution
    2. Create a histogram
    3. Calculate mean and standard deviation
    """,
    config=GenerateContentConfig(tools=[code_execution_tool])
)

File I/O (Gemini 2.0+)

Code execution can read and write files in the sandbox:

Reading Input Files

from google.genai.types import Part

# Upload a file first
uploaded_file = client.files.upload(file="data.csv")

# Process with code execution
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        Part(file_data={"uri": uploaded_file.uri, "mime_type": "text/csv"}),
        Part(text="Read this CSV file and calculate summary statistics for each column")
    ],
    config=GenerateContentConfig(tools=[code_execution_tool])
)

print(response.text)

Generating Output Files

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Generate a CSV file with 100 rows of random user data (name, age, email)",
    config=GenerateContentConfig(tools=[code_execution_tool])
)

# Check for generated files
for part in response.candidates[0].content.parts:
    if part.code_execution_result:
        if part.code_execution_result.files:
            for file in part.code_execution_result.files:
                print(f"Generated file: {file.name}")
                print(f"MIME type: {file.mime_type}")
                # File data is base64 encoded
                print(f"Data: {file.data[:100]}...")

Matplotlib Graphs

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""
    Create a visualization showing:
    1. A sine and cosine wave plot
    2. A bar chart of monthly sales data
    3. A scatter plot with a trend line

    Generate all three as a single figure with subplots.
    """,
    config=GenerateContentConfig(tools=[code_execution_tool])
)

# Extract generated image
for part in response.candidates[0].content.parts:
    if part.inline_data:
        # Image is returned as base64
        import base64
        image_data = base64.b64decode(part.inline_data.data)
        with open("chart.png", "wb") as f:
            f.write(image_data)
        print("Chart saved to chart.png")

Image Manipulation (Gemini 3)

from google.genai.types import Part
import base64

# Load image
with open("input_image.jpg", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode()

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[
        Part(inline_data={"mime_type": "image/jpeg", "data": image_data}),
        Part(text="Apply a sepia filter to this image and resize to 800x600")
    ],
    config=GenerateContentConfig(tools=[code_execution_tool])
)

# Extract modified image
for part in response.candidates[0].content.parts:
    if part.inline_data:
        modified_image = base64.b64decode(part.inline_data.data)
        with open("output_image.jpg", "wb") as f:
            f.write(modified_image)

Data Analysis Example

# Complex data analysis task
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""
    Create a comprehensive analysis:
    1. Generate a dataset of 500 customers with: age, income, spending_score, membership_years
    2. Perform K-means clustering (3 clusters)
    3. Create visualizations:
       - Scatter plot of clusters
       - Distribution of each feature
       - Correlation heatmap
    4. Provide statistical summary
    """,
    config=GenerateContentConfig(tools=[code_execution_tool])
)

print(response.text)

Math and Scientific Computing

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""
    Solve these mathematical problems with code:
    1. Find all prime numbers under 1000
    2. Calculate the determinant of a 5x5 random matrix
    3. Solve the differential equation dy/dx = x + y with initial condition y(0) = 1
    4. Compute the first 50 digits of pi using the Chudnovsky algorithm
    """,
    config=GenerateContentConfig(tools=[code_execution_tool])
)

Combining with Function Calling

from google.genai.types import FunctionDeclaration, Tool

# Custom function for external data
get_stock_data = FunctionDeclaration(
    name="get_stock_data",
    description="Get historical stock price data",
    parameters={
        "type": "object",
        "properties": {
            "symbol": {"type": "string"},
            "days": {"type": "integer"}
        },
        "required": ["symbol"]
    }
)

# Combine code execution and functions
combined_tools = Tool(
    code_execution=CodeExecution(),
    function_declarations=[get_stock_data]
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Get AAPL stock data for the last 30 days and analyze the trend",
    config=GenerateContentConfig(tools=[combined_tools])
)

Error Handling

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Run this intentionally buggy code: print(1/0)",
    config=GenerateContentConfig(tools=[code_execution_tool])
)

for part in response.candidates[0].content.parts:
    if part.code_execution_result:
        if part.code_execution_result.outcome == "FAILED":
            print("Execution failed!")
            print(f"Error: {part.code_execution_result.output}")
        else:
            print("Success!")
            print(part.code_execution_result.output)

Execution Limits

Limit	Value
Execution timeout	30 seconds
Memory	1 GB
File size (input)	100 MB
File size (output)	25 MB
Network access	Disabled

Best Practices

1. Be specific: Clear instructions yield better code
2. Request verification: Ask model to verify results
3. Handle errors: Check outcome field for failures
4. Extract artifacts: Save generated files/images
5. Iterative refinement: Multi-turn for complex tasks

Security Considerations

• Sandbox is isolated - no network access
• File system is ephemeral
• Cannot access user's machine
• Time-limited execution
• Memory-limited

Common Patterns

Pattern	Use Case
Data analysis	CSV/JSON processing, statistics
Visualization	Charts, graphs, plots
Math problems	Calculations, equations
File transformation	Format conversion, processing
Algorithm implementation	Sorting, searching, optimization

Model Availability

Model	Code Execution
Gemini 3 Pro	Yes
Gemini 3 Flash	Yes
Gemini 2.5 Pro	Yes
Gemini 2.5 Flash	Yes
Gemini 2.5 Flash-Lite	No

Deliverables

For: $ARGUMENTS

Provide:

1. Code execution configuration
2. Input file handling if needed
3. Output extraction (text, files, images)
4. Error handling for execution failures
5. Integration with your application