Repository Public
1The Gemini API provides a code execution tool that enables the model to2generate and run Python code. The model can then learn iteratively from the3code execution results until it arrives at a final output. You can use code4execution to build applications that benefit from code-based reasoning. For5example, you can use code execution to solve equations or process text. You can6also use the [libraries](https://ai.google.dev/gemini-api/docs/generate-content/code-execution#supported-libraries) included in the code execution7environment to perform more specialized tasks.89Gemini is only able to execute code in Python. You can still ask Gemini to10generate code in another language, but the model can't use the code execution11tool to run it.1213## Enable code execution1415To enable code execution, configure the code execution tool on the model. This16allows the model to generate and run code.1718### Python1920 from google import genai21 from google.genai import types2223 client = genai.Client()2425 response = client.models.generate_content(26 model="gemini-3.8-flash",27 contents="What is the sum of the first 50 prime numbers? "28 "Generate and run code for the calculation, and make sure you get all 50.",29 config=types.GenerateContentConfig(30 tools=[types.Tool(code_execution=types.ToolCodeExecution)]31 ),32 )3334 for part in response.candidates[0].content.parts:35 if part.text is not None:36 print(part.text)37 if part.executable_code is not None:38 print(part.executable_code.code)39 if part.code_execution_result is not None:40 print(part.code_execution_result.output)4142### JavaScript4344 import { GoogleGenAI } from "@google/genai";4546 const ai = new GoogleGenAI({});4748 let response = await ai.models.generateContent({49 model: "gemini-3.8-flash",50 contents: [51 "What is the sum of the first 50 prime numbers? " +52 "Generate and run code for the calculation, and make sure you get all 50.",53 ],54 config: {55 tools: [{ codeExecution: {} }],56 },57 });5859 const parts = response?.candidates?.[0]?.content?.parts || [];60 parts.forEach((part) => {61 if (part.text) {62 console.log(part.text);63 }6465 if (part.executableCode && part.executableCode.code) {66 console.log(part.executableCode.code);67 }6869 if (part.codeExecutionResult && part.codeExecutionResult.output) {70 console.log(part.codeExecutionResult.output);71 }72 });7374### Go7576 package main7778 import (79 "context"80 "fmt"81 "os"82 "google.golang.org/genai"83 )8485 func main() {8687 ctx := context.Background()88 client, err := genai.NewClient(ctx, nil)89 if err != nil {90 log.Fatal(err)91 }9293 config := &genai.GenerateContentConfig{94 Tools: []*genai.Tool{95 {CodeExecution: &genai.ToolCodeExecution{}},96 },97 }9899 result, _ := client.Models.GenerateContent(100 ctx,101 "gemini-3.8-flash",102 genai.Text("What is the sum of the first 50 prime numbers? " +103 "Generate and run code for the calculation, and make sure you get all 50."),104 config,105 )106107 fmt.Println(result.Text())108 fmt.Println(result.ExecutableCode())109 fmt.Println(result.CodeExecutionResult())110 }111112### REST113114 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \115 -H "x-goog-api-key: $GEMINI_API_KEY" \116 -H 'Content-Type: application/json' \117 -d ' {"tools": [{"code_execution": {}}],118 "contents": {119 "parts":120 {121 "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."122 }123 },124 }'125126> [!NOTE]127> **Note:** This REST example doesn't parse the JSON response as shown in the example output.128129The output might look something like the following, which has been formatted for130readability:131132 Okay, I need to calculate the sum of the first 50 prime numbers. Here's how I'll133 approach this:134135 1. **Generate Prime Numbers:** I'll use an iterative method to find prime136 numbers. I'll start with 2 and check if each subsequent number is divisible137 by any number between 2 and its square root. If not, it's a prime.138 2. **Store Primes:** I'll store the prime numbers in a list until I have 50 of139 them.140 3. **Calculate the Sum:** Finally, I'll sum the prime numbers in the list.141142 Here's the Python code to do this:143144 def is_prime(n):145 """Efficiently checks if a number is prime."""146 if n <= 1:147 return False148 if n <= 3:149 return True150 if n % 2 == 0 or n % 3 == 0:151 return False152 i = 5153 while i * i <= n:154 if n % i == 0 or n % (i + 2) == 0:155 return False156 i += 6157 return True158159 primes = []160 num = 2161 while len(primes) < 50:162 if is_prime(num):163 primes.append(num)164 num += 1165166 sum_of_primes = sum(primes)167 print(f'{primes=}')168 print(f'{sum_of_primes=}')169170 primes=[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67,171 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151,172 157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229]173 sum_of_primes=5117174175 The sum of the first 50 prime numbers is 5117.176177This output combines several content parts that the model returns when using178code execution:179180- `text`: Inline text generated by the model181- `executableCode`: Code generated by the model that is meant to be executed182- `codeExecutionResult`: Result of the executable code183184The naming conventions for these parts vary by programming language.185186## Code Execution with images (Gemini 3)187188The Gemini 3 Flash model can now write and execute Python code to actively189manipulate and inspect images.190191**Use cases**192193- **Zoom and inspect**: The model implicitly detects when details are too small (e.g., reading a distant gauge) and writes code to crop and re-examine the area at higher resolution.194- **Visual math**: The model can run multi-step calculations using code (e.g., summing line items on a receipt).195- **Image annotation**: The model can annotate images to answer questions, such as drawing arrows to show relationships.196197> [!NOTE]198> **Note:** While the model automatically handles zooming for small details, you should prompt it explicitly to use code for other tasks, such as "Write code to count the number of gears" or "Rotate this image to make it upright".199200### Enable Code Execution with images201202Code Execution with images is officially supported in Gemini 3 Flash. You can203activate this behavior by enabling both Code Execution as a tool and Thinking.204205### Python206207 from google import genai208 from google.genai import types209 import requests210 from PIL import Image211 import io212213 image_path = "https://goo.gle/instrument-img"214 image_bytes = requests.get(image_path).content215 image = types.Part.from_bytes(216 data=image_bytes, mime_type="image/jpeg"217 )218219 # Ensure you have your API key set220 client = genai.Client()221222 response = client.models.generate_content(223 model="gemini-3.8-flash",224 contents=[image, "Zoom into the expression pedals and tell me how many pedals are there?"],225 config=types.GenerateContentConfig(226 tools=[types.Tool(code_execution=types.ToolCodeExecution)]227 ),228 )229230 for part in response.candidates[0].content.parts:231 if part.text is not None:232 print(part.text)233 if part.executable_code is not None:234 print(part.executable_code.code)235 if part.code_execution_result is not None:236 print(part.code_execution_result.output)237 if part.as_image() is not None:238 # display() is a standard function in Jupyter/Colab notebooks239 display(Image.open(io.BytesIO(part.as_image().image_bytes)))240241### JavaScript242243 async function main() {244 const ai = new GoogleGenAI({ });245246 // 1. Prepare Image Data247 const imageUrl = "https://goo.gle/instrument-img";248 const response = await fetch(imageUrl);249 const imageArrayBuffer = await response.arrayBuffer();250 const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');251252 // 2. Call the API with Code Execution enabled253 const result = await ai.models.generateContent({254 model: "gemini-3.8-flash",255 contents: [256 {257 inlineData: {258 mimeType: 'image/jpeg',259 data: base64ImageData,260 },261 },262 { text: "Zoom into the expression pedals and tell me how many pedals are there?" }263 ],264 config: {265 tools: [{ codeExecution: {} }],266 },267 });268269 // 3. Process the response (Text, Code, and Execution Results)270 const candidates = result.candidates;271 if (candidates && candidates[0].content.parts) {272 for (const part of candidates[0].content.parts) {273 if (part.text) {274 console.log("Text:", part.text);275 }276 if (part.executableCode) {277 console.log(`\nGenerated Code (${part.executableCode.language}):\n`, part.executableCode.code);278 }279 if (part.codeExecutionResult) {280 console.log(`\nExecution Output (${part.codeExecutionResult.outcome}):\n`, part.codeExecutionResult.output);281 }282 }283 }284 }285286 main();287288### Go289290 package main291292 import (293 "context"294 "fmt"295 "io"296 "log"297 "net/http"298 "os"299300 "google.golang.org/genai"301 )302303 func main() {304 ctx := context.Background()305 // Initialize Client (Reads GEMINI_API_KEY from env)306 client, err := genai.NewClient(ctx, nil)307 if err != nil {308 log.Fatal(err)309 }310311 // 1. Download the image312 imageResp, err := http.Get("https://goo.gle/instrument-img")313 if err != nil {314 log.Fatal(err)315 }316 defer imageResp.Body.Close()317318 imageBytes, err := io.ReadAll(imageResp.Body)319 if err != nil {320 log.Fatal(err)321 }322323 // 2. Configure Code Execution Tool324 config := &genai.GenerateContentConfig{325 Tools: []*genai.Tool{326 {CodeExecution: &genai.ToolCodeExecution{}},327 },328 }329330 // 3. Generate Content331 result, err := client.Models.GenerateContent(332 ctx,333 "gemini-3.8-flash",334 []*genai.Content{335 {336 Parts: []*genai.Part{337 {InlineData: &genai.Blob{MIMEType: "image/jpeg", Data: imageBytes}},338 {Text: "Zoom into the expression pedals and tell me how many pedals are there?"},339 },340 Role: "user",341 },342 },343 config,344 )345 if err != nil {346 log.Fatal(err)347 }348349 // 4. Parse Response (Text, Code, Output)350 for _, cand := range result.Candidates {351 for _, part := range cand.Content.Parts {352 if part.Text != "" {353 fmt.Println("Text:", part.Text)354 }355 if part.ExecutableCode != nil {356 fmt.Printf("\nGenerated Code (%s):\n%s\n", 357 part.ExecutableCode.Language, 358 part.ExecutableCode.Code)359 }360 if part.CodeExecutionResult != nil {361 fmt.Printf("\nExecution Output (%s):\n%s\n", 362 part.CodeExecutionResult.Outcome, 363 part.CodeExecutionResult.Output)364 }365 }366 }367 }368369### REST370371 IMG_URL="https://goo.gle/instrument-img"372 MODEL="gemini-3.8-flash"373374 MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)375 if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then376 MIME_TYPE="image/jpeg"377 fi378379 if [[ "$(uname)" == "Darwin" ]]; then380 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)381 elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then382 IMAGE_B64=$(curl -sL "$IMG_URL" | base64)383 else384 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)385 fi386387 curl "https://generativelanguage.googleapis.com/v1beta/models/$MODEL:generateContent" \388 -H "x-goog-api-key: $GEMINI_API_KEY" \389 -H 'Content-Type: application/json' \390 -X POST \391 -d '{392 "contents": [{393 "parts":[394 {395 "inline_data": {396 "mime_type":"'"$MIME_TYPE"'",397 "data": "'"$IMAGE_B64"'"398 }399 },400 {"text": "Zoom into the expression pedals and tell me how many pedals are there?"}401 ]402 }],403 "tools": [404 {405 "code_execution": {}406 }407 ]408 }'409410## Use code execution in chat411412You can also use code execution as part of a chat.413414### Python415416 from google import genai417 from google.genai import types418419 client = genai.Client()420421 chat = client.chats.create(422 model="gemini-3.8-flash",423 config=types.GenerateContentConfig(424 tools=[types.Tool(code_execution=types.ToolCodeExecution)]425 ),426 )427428 response = chat.send_message("I have a math question for you.")429 print(response.text)430431 response = chat.send_message(432 "What is the sum of the first 50 prime numbers? "433 "Generate and run code for the calculation, and make sure you get all 50."434 )435436 for part in response.candidates[0].content.parts:437 if part.text is not None:438 print(part.text)439 if part.executable_code is not None:440 print(part.executable_code.code)441 if part.code_execution_result is not None:442 print(part.code_execution_result.output)443444### JavaScript445446 import {GoogleGenAI} from "@google/genai";447448 const ai = new GoogleGenAI({});449450 const chat = ai.chats.create({451 model: "gemini-3.8-flash",452 history: [453 {454 role: "user",455 parts: [{ text: "I have a math question for you:" }],456 },457 {458 role: "model",459 parts: [{ text: "Great! I'm ready for your math question. Please ask away." }],460 },461 ],462 config: {463 tools: [{codeExecution:{}}],464 }465 });466467 const response = await chat.sendMessage({468 message: "What is the sum of the first 50 prime numbers? " +469 "Generate and run code for the calculation, and make sure you get all 50."470 });471 console.log("Chat response:", response.text);472473### Go474475 package main476477 import (478 "context"479 "fmt"480 "os"481 "google.golang.org/genai"482 )483484 func main() {485486 ctx := context.Background()487 client, err := genai.NewClient(ctx, nil)488 if err != nil {489 log.Fatal(err)490 }491492 config := &genai.GenerateContentConfig{493 Tools: []*genai.Tool{494 {CodeExecution: &genai.ToolCodeExecution{}},495 },496 }497498 chat, _ := client.Chats.Create(499 ctx,500 "gemini-3.8-flash",501 config,502 nil,503 )504505 result, _ := chat.SendMessage(506 ctx,507 genai.Part{Text: "What is the sum of the first 50 prime numbers? " +508 "Generate and run code for the calculation, and " +509 "make sure you get all 50.",510 },511 )512513 fmt.Println(result.Text())514 fmt.Println(result.ExecutableCode())515 fmt.Println(result.CodeExecutionResult())516 }517518### REST519520 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \521 -H "x-goog-api-key: $GEMINI_API_KEY" \522 -H 'Content-Type: application/json' \523 -d '{"tools": [{"code_execution": {}}],524 "contents": [525 {526 "role": "user",527 "parts": [{528 "text": "Write code to print \"Hello world!\" and execute it"529 }]530 },{531 "role": "model",532 "parts": [533 {534 "executable_code": {535 "id": "a1b2c3d4",536 "language": "PYTHON",537 "code": "\nprint(\"hello world!\")\n"538 }539 "thought_signature": "..."540 },541 {542 "code_execution_result": {543 "id": "a1b2c3d4",544 "outcome": "OUTCOME_OK",545 "output": "hello world!\n"546 }547 },548 {549 "text": "I have printed \"hello world!\" using the provided python code block. \n",550 "thought_signature": "..."551 }552 ],553 },{554 "role": "user",555 "parts": [{556 "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."557 }]558 }559 ]560 }'561562## Input/output (I/O)563564Code execution supports file input and graph output. Using these input and565output capabilities, you can upload CSV and text files, ask questions about the566files, and have [Matplotlib](https://matplotlib.org/) graphs generated as part567of the response. The output files are returned as inline images in the response.568569### I/O pricing570571When using code execution I/O, you're charged for input tokens and output572tokens:573574**Input tokens:**575576- User prompt577578**Output tokens:**579580- Code generated by the model581- Code execution output in the code environment582- Thinking tokens583- Summary generated by the model584585### I/O details586587When you're working with code execution I/O, be aware of the following technical588details:589590- The maximum runtime of the code environment is 30 seconds.591- If the code environment generates an error, the model may decide to regenerate the code output. This can happen up to 5 times.592- The maximum file input size is limited by the model token window. In AI Studio, the maximum input file size is 1 million tokens (roughly 2MB for text files of the supported input types). If you upload a file that's too large, AI Studio won't let you send it.593- Code execution works best with text and CSV files.594- The input file can be passed in `part.inlineData` or `part.fileData` (uploaded via the [Files API](https://ai.google.dev/gemini-api/docs/files)), and the output file is always returned as `part.inlineData`.595596## Billing597598There's no additional charge for enabling code execution from the Gemini API.599You'll be billed at the current rate of input and output tokens based on the600Gemini model you're using.601602Here are a few other things to know about billing for code execution:603604- You're only billed once for the input tokens you pass to the model, and you're billed for the final output tokens returned to you by the model.605- Tokens representing generated code are counted as output tokens. Generated code can include text and multimodal output like images.606- Code execution results are also counted as output tokens.607608The billing model is shown in the following diagram:609610611612- You're billed at the current rate of input and output tokens based on the Gemini model you're using.613- If Gemini uses code execution when generating your response, the original prompt, the generated code, and the result of the executed code are labeled *intermediate tokens* and are billed as *input tokens*.614- Gemini then generates a summary and returns the generated code, the result of the executed code, and the final summary. These are billed as *output tokens*.615- The Gemini API includes an intermediate token count in the API response, so you know why you're getting additional input tokens beyond your initial prompt.616617## Limitations618619- The model can only generate and execute code. It can't return other artifacts like media files.620- In some cases, enabling code execution can lead to regressions in other areas of model output (for example, writing a story).621- There is some variation in the ability of the different models to use code execution successfully.622623## Supported tools combinations624625Code execution tool can be combined with626[Grounding with Google Search](https://ai.google.dev/gemini-api/docs/google-search) to627power more complex use cases.628629Gemini 3 models support combining built-in tools (like Code Execution) with630custom tools (function calling). You must pass back the `id` and631`thought_signature` fields for tool combination to work. Learn more on the632[tool combinations](https://ai.google.dev/gemini-api/docs/tool-combination) page.633634## Supported libraries635636The code execution environment includes the following libraries:637638- attrs639- chess640- contourpy641- fpdf642- geopandas643- imageio644- jinja2645- joblib646- jsonschema647- jsonschema-specifications648- lxml649- matplotlib650- mpmath651- numpy652- opencv-python653- openpyxl654- packaging655- pandas656- pillow657- protobuf658- pylatex659- pyparsing660- PyPDF2661- python-dateutil662- python-docx663- python-pptx664- reportlab665- scikit-learn666- scipy667- seaborn668- six669- striprtf670- sympy671- tabulate672- tensorflow673- toolz674- xlrd675676You can't install your own libraries.677678> [!NOTE]679> **Note:** Only `matplotlib` is supported for graph rendering using code execution.680681## What's next682683- Try the [code execution Colab](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Code_Execution.ipynb).684- Learn about other Gemini API tools:685 - [Function calling](https://ai.google.dev/gemini-api/docs/function-calling)686 - [Grounding with Google Search](https://ai.google.dev/gemini-api/docs/grounding)