Code execution

This guide shows you how to use the code execution feature in the Gemini API to generate and run Python code.

• Get started with code execution: Learn how to enable and use the code execution tool in your prompts.
• Code execution versus function calling: Understand the differences between code execution and function calling to choose the right tool for your use case.
• Billing: Find out how usage of the code execution tool is billed.
• Limitations: Review the current limitations of the code execution feature.

With the code execution feature in the Gemini API, the model can generate and run Python code. The model learns iteratively from the results to produce a final output. You can use this capability to build applications that benefit from code-based reasoning and produce text output, such as an application that solves equations or processes text.

The Gemini API provides code execution as a tool, similar to function calling. After you add code execution as a tool in your request, the model decides when to use it.

The code execution environment includes the following libraries. You can't install your own libraries.

• Altair
• Chess
• Cv2
• Matplotlib
• Mpmath
• NumPy
• Pandas
• Pdfminer
• Reportlab
• Seaborn
• Sklearn
• Statsmodels
• Striprtf
• SymPy
• Tabulate

Supported models

The following models support code execution:

• Gemini 2.5 Flash-Lite
• Gemini 2.0 Flash with Live API (Preview)
• Vertex AI Model Optimizer (Experimental)
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

Get started with code execution

This section assumes that you've completed the setup and configuration steps in the Gemini API quickstart.

Enable code execution on the model

To enable code execution, add the code_execution tool when you send a prompt to the model.

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (
    HttpOptions,
    Tool,
    ToolCodeExecution,
    GenerateContentConfig,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.5-flash"

code_execution_tool = Tool(code_execution=ToolCodeExecution())
response = client.models.generate_content(
    model=model_id,
    contents="Calculate 20th fibonacci number. Then find the nearest palindrome to it.",
    config=GenerateContentConfig(
        tools=[code_execution_tool],
        temperature=0,
    ),
)
print("# Code:")
print(response.executable_code)
print("# Outcome:")
print(response.code_execution_result)

# Example response:
# # Code:
# def fibonacci(n):
#     if n <= 0:
#         return 0
#     elif n == 1:
#         return 1
#     else:
#         a, b = 0, 1
#         for _ in range(2, n + 1):
#             a, b = b, a + b
#         return b
#
# fib_20 = fibonacci(20)
# print(f'{fib_20=}')
#
# # Outcome:
# fib_20=6765

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithCodeExec shows how to generate text using the code execution tool.
func generateWithCodeExec(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	prompt := "Calculate 20th fibonacci number. Then find the nearest palindrome to it."
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: prompt},
		},
			Role: "user"},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{CodeExecution: &genai.ToolCodeExecution{}},
		},
		Temperature: genai.Ptr(float32(0.0)),
	}
	modelName := "gemini-2.5-flash"

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	for _, p := range resp.Candidates[0].Content.Parts {
		if p.Text != "" {
			fmt.Fprintf(w, "Gemini: %s", p.Text)
		}
		if p.ExecutableCode != nil {
			fmt.Fprintf(w, "Language: %s\n%s\n", p.ExecutableCode.Language, p.ExecutableCode.Code)
		}
		if p.CodeExecutionResult != nil {
			fmt.Fprintf(w, "Outcome: %s\n%s\n", p.CodeExecutionResult.Outcome, p.CodeExecutionResult.Output)
		}
	}

	// Example response:
	// Gemini: Okay, I can do that. First, I'll calculate the 20th Fibonacci number. Then, I need ...
	//
	// Language: PYTHON
	//
	// def fibonacci(n):
	//    ...
	//
	// fib_20 = fibonacci(20)
	// print(f'{fib_20=}')
	//
	// Outcome: OUTCOME_OK
	// fib_20=6765
	//
	// Now that I have the 20th Fibonacci number (6765), I need to find the nearest palindrome. ...
	// ...

	return nil
}

npm install @google/genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateContent(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const ai = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents:
      'What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50.',
    config: {
      tools: [{codeExecution: {}}],
      temperature: 0,
    },
  });

  console.debug(response.executableCode);
  console.debug(response.codeExecutionResult);

  return response.codeExecutionResult;
}

cat > request.json << 'EOF'
{
  "tools": [{'codeExecution': {}}],
  "contents": {
    "role": "ROLE",
    "parts": { "text": "TEXT" }
  },
}
EOF

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"

@'
{
  "tools": [{'codeExecution': {}}],
  "contents": {
    "role": "ROLE",
    "parts": { "text": "TEXT" }
  },
}
'@  | Out-File -FilePath request.json -Encoding utf8

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Okay, I understand. You want me to calculate the sum of the first 10 positive integers and to use code to do so. Here's my plan: I will use a loop to add the numbers from 1 to 10 and then return the final sum.\n\n"
          },
          {
            "executableCode": {
              "language": "PYTHON",
              "code": "\ntotal = 0\nfor i in range(1, 11):\n    total += i\nprint(f'{total=}')\n"
            }
          },
          {
            "codeExecutionResult": {
              "outcome": "OUTCOME_OK",
              "output": "total=55\n"
            }
          },
          {
            "text": "The sum of the first 10 positive numbers is 55.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.19436789,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.17441037
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.0685376,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.14903527
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.23231025,
          "severity": "HARM_SEVERITY_LOW",
          "severityScore": 0.2436427
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08269742,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.10818888
        }
      ],
      "score": -0.50845032930374146,
      "avgLogprobs": -0.0046222757209431042
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 34,
    "candidatesTokenCount": 110,
    "totalTokenCount": 144,
    "billablePromptUsage": {
      "textCount": 119
    },
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2024-12-09T23:33:47.842964Z",
  "responseId": "W35XZ9S5M6acmecP3vDFkQU"
}

Use code execution in chat

You can also use code execution as part of a chat session.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/test-project/locations/global/publishers/google/models/gemini-2.0-flash-001:generateContent -d \
$'{
    "tools": [{'code_execution': {}}],
    "contents": [
      {
        "role": "user",
        "parts": {
          "text": "Can you print \"Hello world!\"?"
        }
      },
      {
        "role": "model",
        "parts": [
          {
            "text": ""
          },
          {
            "executable_code": {
              "language": "PYTHON",
              "code": "\nprint(\"hello world!\")\n"
            }
          },
          {
            "code_execution_result": {
              "outcome": "OUTCOME_OK",
              "output": "hello world!\n"
            }
          },
          {
            "text": "I have printed \"hello world!\" using the provided python code block. \n"
          }
        ],
      },
      {
        "role": "user",
        "parts": {
          "text": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50."
        }
      }
    ]
  }'

Code execution versus function calling

The following table compares code execution with function calling.

In general, use code execution if it can handle your use case, because it's simpler and resolves in a single API request. Use function calling if you need to run your own local functions or call external APIs, which requires an additional API request to send back the output from each function call.

Billing

There is no additional charge for using the code execution tool. You are billed at the standard rate for the Gemini model that you use.

The billing process for requests that use the code execution tool is as follows:

• You're billed for input and output tokens based on the Gemini model that you use.
• When the model uses code execution, the original prompt, the generated code, and the code execution results are considered intermediate tokens. These are billed as input tokens.
• The model's final response, which can include a summary, the generated code, and the execution results, is billed as output tokens.
• The API response includes an intermediate token count so that you can track any additional input tokens beyond your initial prompt.

The output from the generated code can include text and multimodal content, such as images from generated graphs.

Limitations

• The model can only generate and execute code. It can't return other artifacts like media files directly.
• File I/O: The tool doesn't support file URIs for input or output. However, you can provide file input and receive graph output as inlined bytes. For example, you can upload a CSV file, ask questions about it, and receive a generated Matplotlib graph.
  • Supported MIME types: The supported MIME types for inlined bytes are .cpp, .csv, .java, .jpeg, .js, .png, .py, .ts, and .xml.
• Code execution times out after 30 seconds.
• In some cases, enabling code execution can lead to regressions in other areas of model output, such as writing a story.