code-execution-tool changedagents-and-tools/tool-use/code-execution-tool
Nearest release: v2.1.307, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+38added
Lines−38removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits23to this page, all time
The whole hunk
from line 1, old and new numbered
/
from line 1
11---
22title: Code execution tool
33url: https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool
4description: Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.
4description: Run Python and Bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.
55featureMetadata:
66 status: ga
77 zdr: not-eligible
from line 40
4040Code execution also powers dynamic filtering in the [web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) and [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) tools: Claude filters results inside the code execution environment before they reach the context window. When dynamic filtering runs, the API provisions the code execution it needs for the request automatically, so you don't add the code execution tool to your request for it.
4141
4242<Note>
43 Reach out through the [feedback form](https://forms.gle/LTAU6Xn2puCJMi1n6) to share your feedback on this feature.
43 Use the [feedback form](https://forms.gle/LTAU6Xn2puCJMi1n6) to share your feedback on this feature.
4444</Note>
4545
4646## Tool versions
from line 49
4949
5050* `code_execution_20250825` supports Bash commands and file operations.
5151* `code_execution_20260120` adds REPL state persistence and [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) from within the sandbox. Claude Haiku 4.5 accepts the `code_execution_20260120` and `code_execution_20260521` tool types, but programmatic tool calling and the REPL state persistence that depends on it aren't available on it, so the newer versions behave like `code_execution_20250825` there.
52* `code_execution_20260521` is the same runtime as `code_execution_20260120`. The difference is that the tool description tells Claude about the 90-second wall-clock limit on each Python cell in programmatic tool calling, so Claude can budget long-running cells. A cell that exceeds the limit returns a normal code execution result with a non-zero `return_code` and a `detection_timeout` status message in its output. This is separate from the `execution_time_exceeded` [error code](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#errors), which the API returns when a whole tool invocation exceeds the maximum execution time.
52* `code_execution_20260521` is the same runtime as `code_execution_20260120`. The difference is that the tool description tells Claude about the 90-second wall-clock limit on each Python cell in programmatic tool calling, so Claude can budget long-running cells. A cell that exceeds the limit returns a normal code execution result with a non-zero `return_code` and a `detection_timeout` status message in its output. This is separate from the `execution_time_exceeded` [error code](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#errors), which the API returns when a whole tool call exceeds the maximum execution time.
5353
5454None of the three tool versions requires an `anthropic-beta` header. The legacy code execution beta headers remain valid opt-ins.
5555
from line 230
230230
231231When you add the code execution tool to your API request:
232232
2331. Claude evaluates whether code execution would help answer your question
2331. Claude evaluates whether code execution would help answer your question.
234234
2352352. The tool automatically provides Claude with the following capabilities:
236236
from line 237
237237 * **Bash commands:** Run shell commands for system operations
238238 * **File operations:** Create, view, and edit files directly, including writing code
239239
2403. Claude can use any combination of these capabilities in a single request
2403. Claude can use any combination of these capabilities in a single request.
241241
2424. All operations run in a secure, sandboxed container. The container has no internet access, so Claude can't download packages at runtime: only the [pre-installed libraries](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#pre-installed-libraries) are available
2424. All operations run in a secure, sandboxed container. The container has no internet access, so Claude can't download packages at runtime: only the [pre-installed libraries](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#pre-installed-libraries) are available.
243243
2445. The API runs every command server-side and returns the results to Claude within the same request, so you never execute code or send back `tool_result` blocks yourself. One exception is when Claude calls one of your client tools alongside code execution: the API returns the code execution call without its result. The result arrives in a later response, after you send back the `tool_result` blocks for your client tools
2445. The API runs every command server-side and returns the results to Claude within the same request, so you never run code or send back `tool_result` blocks yourself. One exception is when Claude calls one of your client tools alongside code execution: the API returns the code execution call without its result. The result arrives in a later response, after you send back the `tool_result` blocks for your client tools.
245245
2466. Each request runs in a new container unless you pass an earlier response's container ID back (see [Container reuse](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#container-reuse))
2466. Each request runs in a new container unless you pass an earlier response's container ID back (see [Container reuse](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#container-reuse)).
247247
2487. Claude provides results with any generated charts, calculations, or analysis
2487. Claude provides results with any generated charts, calculations, or analysis.
249249
250250The container has Python pre-installed. Claude writes Python with the file operations sub-tool and runs it with a Bash command. With `code_execution_20260120` or later and [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling), the Python interpreter state (such as variable bindings) also persists across requests that reuse the container.
251251
from line 256
256256* Non-trivial math (large numbers, many steps, precision-sensitive results)
257257* Data analysis, file parsing, or visualization
258258* Algorithm execution or simulation
259* Explicit requests to "run", "compute", or "execute"
259* Explicit requests to "run," "compute," or "execute"
260260
261261Claude answers directly without running code for:
262262
from line 283
283283
284284#### Upload and analyze files
285285
2861. **Upload your file** using the [Files API](https://platform.claude.com/docs/en/build-with-claude/files)
2872. **Reference the file** in your message using a `container_upload` content block
2883. **Include the code execution tool** in your API request
2861. **Upload your file** using the [Files API](https://platform.claude.com/docs/en/build-with-claude/files).
2872. **Reference the file** in your message using a `container_upload` content block.
2883. **Include the code execution tool** in your API request.
289289
290290<CodeGroup>
291291 ```bash cURL
from line 894
894894
895895#### How generated files are captured
896896
897Each `bash_code_execution` call gets a new, empty directory, available to the command as `$OUTPUT_DIR`. When the command finishes, the files at the top level of that directory are captured and returned as the `file_id` entries in the result's `content` list. Files written anywhere else stay in the container and aren't returned.
897Each `bash_code_execution` call gets a new, empty directory, available to the command as `$OUTPUT_DIR`. When the command completes, the files at the top level of that directory are captured and returned as the `file_id` entries in the result's `content` list. Files written anywhere else stay in the container and aren't returned.
898898
899The tool description tells Claude to share files by copying them into `$OUTPUT_DIR`. If your application depends on receiving a file, prompt Claude to copy it into `$OUTPUT_DIR` and list the directory in the same command, so the `ls` output confirms the capture (Claude doesn't see the `content` list):
899The tool description tells Claude to share files by copying them into `$OUTPUT_DIR`. If your application depends on receiving a file, prompt Claude to copy it into `$OUTPUT_DIR` and list the directory in the same command, so the `ls` output confirms the capture (Claude doesn't receive the `content` list):
900900
901901```bash
902902python /tmp/make_report.py && cp /tmp/report.pdf "$OUTPUT_DIR/" && ls "$OUTPUT_DIR"
from line 1073
10731073
10741074**Error codes by tool type:**
10751075
1076| Tool | Error code | Description |
1077| ------------ | ------------------------- | ------------------------------------------------------- |
1078| All tools | `unavailable` | The tool is temporarily unavailable |
1079| All tools | `execution_time_exceeded` | The tool invocation exceeded the maximum execution time |
1080| All tools | `invalid_tool_input` | Invalid parameters provided to the tool |
1081| All tools | `too_many_requests` | Rate limit exceeded for tool usage |
1082| bash | `output_file_too_large` | Command output exceeded the maximum size |
1083| text\_editor | `file_not_found` | File doesn't exist (for view/edit operations) |
1076| Tool | Error code | Description |
1077| ------------ | ------------------------- | ------------------------------------------------- |
1078| All tools | `unavailable` | The tool is temporarily unavailable |
1079| All tools | `execution_time_exceeded` | The tool call exceeded the maximum execution time |
1080| All tools | `invalid_tool_input` | Invalid parameters provided to the tool |
1081| All tools | `too_many_requests` | Rate limit exceeded for tool usage |
1082| bash | `output_file_too_large` | Command output exceeded the maximum size |
1083| text\_editor | `file_not_found` | File doesn't exist (for view/edit operations) |
10841084
10851085An expired container can't be reused: requests that reference it return an error instead of restoring it. Send the request again without the `container` parameter to get a new container.
10861086
from line 1103
11031103* **Memory:** 5 GiB RAM
11041104* **Disk space:** 5 GiB workspace storage
11051105* **CPU:** 1 CPU
1106* **Execution time:** A tool invocation that runs past the maximum execution time returns an `execution_time_exceeded` [error](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#errors). With [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling), each REPL cell also has a 90-second wall-clock limit
1106* **Execution time:** A tool call that runs past the maximum execution time returns an `execution_time_exceeded` [error](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#errors). With [programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling), each REPL cell also has a 90-second wall-clock limit
11071107
11081108### Networking and security
11091109
11101110* **Internet access:** Completely disabled for security
1111* **External connections:** No outbound network requests permitted
1111* **External connections:** No outbound network requests allowed
11121112* **Sandbox isolation:** Full isolation from host system and other containers
11131113* **File access:** Limited to workspace directory only
11141114* **Workspace scoping:** Like the [Files API](https://platform.claude.com/docs/en/build-with-claude/files), containers are scoped to the request's workspace
from line 1423
14231423
14241424## Using code execution with other execution tools
14251425
1426When you provide code execution alongside client-provided tools that also run code (such as a [Bash tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool) or custom REPL), Claude is operating in a multicomputer environment. The code execution tool runs in Anthropic's sandboxed container, while your client-provided tools run in a separate environment that you control. Claude can sometimes confuse these environments, attempting to use the wrong tool or assuming state is shared between them.
1426When you provide code execution alongside client-provided tools that also run code (such as a [Bash tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool) or custom REPL), Claude is operating in a multicomputer environment. The code execution tool runs in Anthropic's sandboxed container, whereas your client-provided tools run in a separate environment that you control. Claude can sometimes use the wrong tool or act as if state is shared between these environments.
14271427
14281428To avoid this, add instructions to your system prompt that clarify the distinction:
14291429
from line 1435
14351435- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state
14361436```
14371437
1438This is especially important when combining code execution with [web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) or [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool), which enable code execution automatically. If your application already provides a client-side shell tool, the automatic code execution creates a second execution environment that Claude needs to distinguish between.
1438This is especially important when combining code execution with [web search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) or [web fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool), which enable code execution automatically. If your application already provides a client-side shell tool, the automatic code execution creates a second execution environment that Claude needs to distinguish from the first.
14391439
14401440When Claude calls one of your client tools alongside code execution, the API returns the code execution call without its result. The result arrives in a later response, after you send back the `tool_result` blocks for your client tools.
14411441
from line 1468
14681468
14691469When used without these tools, code execution is billed by execution time, tracked separately from token usage:
14701470
1471* Execution time has a minimum of 5 minutes
1472* Each organization receives **1,550 free hours** of usage per month
1473* Additional usage beyond 1,550 hours is billed at **$0.05 USD per hour, per container**
1474* If files are included in the request, execution time is billed even if the tool is not called, because files are preloaded onto the container
1471* Execution time has a minimum of 5 minutes.
1472* Each organization receives **1,550 free hours** of usage per month.
1473* Additional usage beyond 1,550 hours is billed at **$0.05 USD per hour, per container**.
1474* If files are included in the request, execution time is billed even if the tool is not called, because files are preloaded onto the container.
14751475
14761476Code execution usage is tracked in the response:
14771477
from line 1518
15181518
15191519**Review response handling** (if parsing responses programmatically):
15201520
1521* The API no longer sends the previous blocks for Python execution responses
1522* Instead, the API sends new response types for Bash and file operations (see [Response format](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#response-format))
1521* The API no longer sends the previous blocks for Python execution responses.
1522* Instead, the API sends new response types for Bash and file operations (see [Response format](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool#response-format)).
15231523
15241524## Data retention
15251525
No line in this hunk matches that.