Agents And Tools Tool Use Code Execution Tool

Claude can analyze data, create visualizations, perform complex calculations, run system commands, create and edit files, and process uploaded files directly within the API conversation. The code execution tool allows Claude to run Bash commands and manipulate files, including writing code, in a secure, sandboxed environment.

Note: The code execution tool is currently in public beta.

To use this feature, add the "code-execution-2025-08-25" beta header to your API requests.

Model compatibility

The code execution tool is available on the following models:

Note: The current version code_execution_20250825 supports Bash commands and file operations. A legacy version code_execution_20250522 (Python only) is also available. See Upgrade to latest tool version for migration details.

Warning: Older tool versions are not guaranteed to be backwards-compatible with newer models. Always use the tool version that corresponds to your model version.

Quick start

Here's a simple example that asks Claude to perform a calculation:

How code execution works

When you add the code execution tool to your API request:

1. Claude evaluates whether code execution would help answer your question
2. The tool automatically provides Claude with the following capabilities:
   • Bash commands: Execute shell commands for system operations and package management
   • File operations: Create, view, and edit files directly, including writing code
3. Claude can use any combination of these capabilities in a single request
4. All operations run in a secure sandbox environment
5. Claude provides results with any generated charts, calculations, or analysis

How to use the tool

Execute Bash commands

Ask Claude to check system information and install packages:

Create and edit files directly

Claude can create, view, and edit files directly in the sandbox using the file manipulation capabilities:

Upload and analyze your own files

To analyze your own data files (CSV, Excel, images, etc.), upload them via the Files API and reference them in your request:

Note: Using the Files API with Code Execution requires two beta headers: "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14"

The Python environment can process various file types uploaded via the Files API, including:

• CSV
• Excel (.xlsx, .xls)
• JSON
• XML
• Images (JPEG, PNG, GIF, WebP)
• Text files (.txt, .md, .py, etc)

Upload and analyze files

1. Upload your file using the Files API
2. Reference the file in your message using a container_upload content block
3. Include the code execution tool in your API request

Retrieve generated files

When Claude creates files during code execution, you can retrieve these files using the Files API:

Tool definition

The code execution tool requires no additional parameters:

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

When this tool is provided, Claude automatically gains access to two sub-tools:

• bash_code_execution: Run shell commands
• text_editor_code_execution: View, create, and edit files, including writing code

Response format

The code execution tool can return two types of results depending on the operation:

Bash command response

{
  "type": "server_tool_use",
  "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "name": "bash_code_execution",
  "input": {
    "command": "ls -la | head -5"
  }
},
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "content": {
    "type": "bash_code_execution_result",
    "stdout": "total 24\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 11:00 ..\n-rw-r--r-- 1 user user  220 Jan 1 12:00 data.csv\n-rw-r--r-- 1 user user  180 Jan 1 12:00 config.json",
    "stderr": "",
    "return_code": 0
  }
}

File operation responses

View file:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "text_editor_code_execution",
  "input": {
    "command": "view",
    "path": "config.json"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": {
    "type": "text_editor_code_execution_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "numLines": 4,
    "startLine": 1,
    "totalLines": 4
  }
}

Create file:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "text_editor_code_execution",
  "input": {
    "command": "create",
    "path": "new_file.txt",
    "file_text": "Hello, World!"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": {
    "type": "text_editor_code_execution_result",
    "is_file_update": false
  }
}

Edit file (str_replace):

{
  "type": "server_tool_use",
  "id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "name": "text_editor_code_execution",
  "input": {
    "command": "str_replace",
    "path": "config.json",
    "old_str": "\"debug\": true",
    "new_str": "\"debug\": false"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "content": {
    "type": "text_editor_code_execution_result",
    "oldStart": 3,
    "oldLines": 1,
    "newStart": 3,
    "newLines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}

Results

All execution results include:

• stdout: Output from successful execution
• stderr: Error messages if execution fails
• return_code: 0 for success, non-zero for failure

Additional fields for file operations:

• View: file_type, content, numLines, startLine, totalLines
• Create: is_file_update (whether file already existed)
• Edit: oldStart, oldLines, newStart, newLines, lines (diff format)

Errors

Each tool type can return specific errors:

Common errors (all tools):

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Error codes by tool type:

pause_turn stop reason

The response may include a pause_turn stop reason, which indicates that the API paused a long-running turn. You may provide the response back as-is in a subsequent request to let Claude continue its turn, or modify the content if you wish to interrupt the conversation.

Containers

The code execution tool runs in a secure, containerized environment designed specifically for code execution, with a higher focus on Python.

Runtime environment

• Python version: 3.11.12
• Operating system: Linux-based container
• Architecture: x86_64 (AMD64)

Resource limits

• Memory: 5GiB RAM
• Disk space: 5GiB workspace storage
• CPU: 1 CPU

Networking and security

• Internet access: Completely disabled for security
• External connections: No outbound network requests permitted
• Sandbox isolation: Full isolation from host system and other containers
• File access: Limited to workspace directory only
• Workspace scoping: Like Files, containers are scoped to the workspace of the API key
• Expiration: Containers expire 30 days after creation

Pre-installed libraries

The sandboxed Python environment includes these commonly used libraries:

• Data Science: pandas, numpy, scipy, scikit-learn, statsmodels
• Visualization: matplotlib, seaborn
• File Processing: pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
• Math & Computing: sympy, mpmath
• Utilities: tqdm, python-dateutil, pytz, joblib, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite

Container reuse

You can reuse an existing container across multiple API requests by providing the container ID from a previous response. This allows you to maintain created files between requests.

Example

Streaming

With streaming enabled, you'll receive code execution events as they occur:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "code_execution"}}

// Code execution streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"code\":\"import pandas as pd\\ndf = pd.read_csv('data.csv')\\nprint(df.head())\"}"}}

// Pause while code executes

// Execution results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": ""}}}

Batch requests

You can include the code execution tool in the Messages Batches API. Code execution tool calls through the Messages Batches API are priced the same as those in regular Messages API requests.

Usage and pricing

Code execution tool usage is tracked separately from token usage. Execution time has a minimum of 5 minutes. If files are included in the request, execution time is billed even if the tool is not used due to files being preloaded onto the container.

Each organization receives 50 free hours of usage with the code execution tool per day. Additional usage beyond the first 50 hours is billed at $0.05 per hour, per container.

Upgrade to latest tool version

By upgrading to code-execution-2025-08-25, you get access to file manipulation and Bash capabilities, including code in multiple languages. There is no price difference.

What's changed

Backward compatibility

• All existing Python code execution continues to work exactly as before
• No changes required to existing Python-only workflows

Upgrade steps

To upgrade, you need to make the following changes in your API requests:

1. Update the beta header:

   diff

   - "anthropic-beta": "code-execution-2025-05-22"
   + "anthropic-beta": "code-execution-2025-08-25"
   

2. Update the tool type:

   diff

   - "type": "code_execution_20250522"
   + "type": "code_execution_20250825"
   

3. Review response handling (if parsing responses programmatically):

   • The previous blocks for Python execution responses will no longer be sent
   • Instead, new response types for Bash and file operations will be sent (see Response Format section)

Using code execution with Agent Skills

The code execution tool enables Claude to use Agent Skills. Skills are modular capabilities consisting of instructions, scripts, and resources that extend Claude's functionality.

Learn more in the Agent Skills documentation and Agent Skills API guide.