---
title: Python Code Execution
sidebarTitle: Code Execution
---

Add code execution as a capability for your AG2 agents with the [`PythonCodeExecutionTool`](/docs/api-reference/autogen/tools/experimental/PythonCodeExecutionTool)! Utilizing a provided Python environment, whether that's the system one, a local virtual one, or a Docker container, your agents can generate, run and utilize the results of Python code.

The ability to execute code enables your agents to not only create code for applications but also to validate hypotheses, validate existing code, and cycle through code iterations until a working solution can be found.

<Warning>
Executing code, particularly code generated by an LLM, has inherent risks.

Different environments offer different levels of isolation:
- System environment: No isolation - code runs directly on your system
- Virtual environment: Package isolation only - still executes within your operating system
- Docker environment: Container isolation - provides stronger separation from your host system
</Warning>

The [`PythonCodeExecutionTool`](/docs/api-reference/autogen/tools/experimental/PythonCodeExecutionTool) is comprised of a Python environment and a working directory, both of which you need to specify.

## Installation

No additional extras/packages are required for basic usage, and this tool will work for Mac, Windows, and Linux.

For Docker environments, you need to have Docker installed and running on your system.

You will need to have the Python versions you want to run installed. The tool will not install a specific Python version for you.

## Environments

There are three environments the tool can run code in:
1. **System Environment** - this is equivalent to your terminal or command prompt, and utilizes the Python interpreter (version) available by default at your system-level.
2. **Virtual Environment (venv)** - utilizing Python's virtual environment capabilities, this has its own independent set of Python packages.
3. **Docker Environment** - executes code within Docker containers, providing stronger isolation and environment control.

You create and pass these in using the `python_environment` parameter of the [`PythonCodeExecutionTool`](/docs/api-reference/autogen/tools/experimental/PythonCodeExecutionTool).

<Tip>
In terms of isolation and security:

- System environment is the least isolated
- Virtual environment provides package isolation but still executes on your system
- Docker environment provides the strongest isolation and is recommended for untrusted code
</Tip>

### System Environment

The [`SystemPythonEnvironment`](/docs/api-reference/autogen/environments/SystemPythonEnvironment) uses the operating system's Python environment. It allows you to run code with all the installed packages.

There is only one, optional, parameter for the [`SystemPythonEnvironment`](/docs/api-reference/autogen/environments/SystemPythonEnvironment) and that's `executable` which can be a path (including filename) to the Python executable. This is useful if you have multiple Python interpreters installed and want to execute the code with a specific Python one.

### Venv Environment

The [`VenvPythonEnvironment`](/docs/api-reference/autogen/environments/VenvPythonEnvironment) uses or creates a virtual environment to run the code in. This provides package isolation from the operating system Python environment.

The parameters for the [`VenvPythonEnvironment`](/docs/api-reference/autogen/environments/VenvPythonEnvironment) allow you to use existing, or create new, virtual environments.

| Parameter | Description |
| --- | --- |
| `python_version` | If you do not specify a `python_path` or a `venv_path` with an existing virtual environment, a virtual environment with the specified Python version will be created. The Python version must already exist, it will not be installed. |
| `python_path` | If you want to use a specific Python interpreter you can pass in the path (and filename) of it. This takes precedence over the `python_version`, but will not be used if the `venv_path` is provided and a virtual environment already exists. |
| `venv_path` | If you want to use an existing virtual environment or want a new one to be created in a specific location, you can specify a path for it. |

<Tip>
If you pass in a `python_version` the tool will look for the Python interpreter executable in typical locations on disk. However, if yours is installed elsewhere you will need to use the `python_path` to specify the correct location.
</Tip>

Note: The virtual environment directory will not be removed by the tool.

### Docker Environment

The [`DockerPythonEnvironment`](/docs/api-reference/autogen/environments/DockerPythonEnvironment) executes code within Docker containers, providing stronger isolation from the host system and greater flexibility in environment configuration.

Key parameters for the [`DockerPythonEnvironment`](/docs/api-reference/autogen/environments/DockerPythonEnvironment) include:

| Parameter | Description |
| --- | --- |
| `image` | Docker image to use (e.g., `python:3.11-slim`). Defaults to Python 3.11. |
| `pip_packages` | List of pip packages to install in the container. |
| `requirements_file` | Path to a requirements.txt file to install in the container. |
| `volumes` | Dictionary mapping host paths to container paths for mounting volumes. |
| `dockerfile` | Optional path to a Dockerfile to build and use instead of pulling an image. |
| `cleanup_container` | Whether to remove the container after use. Defaults to `True`. |
| `keep_container_running` | Whether to keep the container running after execution. Defaults to `False`. |

<Tip>
The Docker environment offers the strongest isolation for executing untrusted code. It's highly recommended for running code from LLMs in production systems or when working with potentially risky operations.
</Tip>

Note: Docker must be installed and running on your system to use this environment.

## Working Directory

The tool will create a `script.py` file with the code and execute it. The location of this file is specified by passing in a [`WorkingDirectory`](/docs/api-reference/autogen/environments/WorkingDirectory) to the `working_directory` parameter of the [`PythonCodeExecutionTool`](/docs/api-reference/autogen/tools/experimental/PythonCodeExecutionTool).

If you don't want to specify a directory you can use [`WorkingDirectory`](/docs/api-reference/autogen/environments/WorkingDirectory)'s `create_tmp` method to create a temporary one.

With Docker environments, the working directory is mounted inside the container, allowing files to be shared between the host and the container.

Note: The working directory will not be removed by the tool.

## Timeout

To assist in handling execution that runs beyond a reasonable amount of time, a `timeout` parameter (in seconds) is provided. The default timeout is 30 seconds.

## Packages

Packages are not automatically installed if the code depends on them and they are missing, except in Docker environments where you can specify packages to install.

For system and virtual environments, create and configure your environment with the needed packages beforehand.

For Docker environments, you can specify packages directly via the `pip_packages` parameter or with a `requirements_file`.

## Examples

### System Environment

import CodeExecutionLocalSystem from "/snippets/reference-tools/code-execution-system.mdx";

<CodeExecutionLocalSystem/>

### Venv Environment

import CodeExecutionLocalVenv from "/snippets/reference-tools/code-execution-venv.mdx";

<CodeExecutionLocalVenv/>

### Docker Environment

import CodeExecutionDocker from "/snippets/reference-tools/code-execution-docker.mdx";

<CodeExecutionDocker/>

## Comparing Execution Environments

| Feature | System Environment | Virtual Environment | Docker Environment |
| --- | --- | --- | --- |
| **Isolation** | Minimal | Package-level | Container-level |
| **Security** | Low | Medium | Higher |
| **Setup Complexity** | Low | Medium | Higher |
| **Resource Overhead** | Minimal | Low | Medium |
| **Dependency Management** | Shared | Isolated | Fully isolated |
| **Persistence** | System-wide | Directory-based | Image/Container based |
| **Recommended Use** | Trusted code, simple scripts | General development | Untrusted code, complex dependencies |
