smolagents/pr_2321/en/reference/python_executors.md

# Python code executors

Python executors are responsible for running the code generated by code agents in a controlled environment.
Since agents dynamically generate and execute Python code to accomplish tasks, choosing the right executor is critical
for both functionality and security.

To learn more about code execution and its risks, make sure to read the [Secure code execution](../tutorials/secure_code_execution)
tutorial. This reference contains the API docs for the underlying classes: the base `PythonExecutor` interface and all 
available executor implementations.

## Python executor[[smolagents.PythonExecutor]]

#### smolagents.PythonExecutor[[smolagents.PythonExecutor]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/local_python_executor.py#L1677)

## Local Python executor[[smolagents.LocalPythonExecutor]]

#### smolagents.LocalPythonExecutor[[smolagents.LocalPythonExecutor]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/local_python_executor.py#L1688)

Executor of Python code in a local environment.

This executor evaluates Python code with restricted access to imports and built-in functions.
It is not a security sandbox: for isolated execution of untrusted code, use a remote executor.
It maintains state between executions, allows for custom tools and functions to be made available
to the code, and captures print outputs separately from return values.

**Parameters:**

additional_authorized_imports (`list[str]`) : Additional authorized imports for the executor.

max_print_outputs_length (`int`, defaults to `DEFAULT_MAX_LEN_OUTPUT=50_000`) : Maximum length of the print outputs.

additional_functions (`dict[str, Callable]`, *optional*) : Additional Python functions to be added to the executor.

timeout_seconds (`int`, *optional*, defaults to `MAX_EXECUTION_TIME_SECONDS`) : Maximum time in seconds allowed for code execution. Set to `None` to disable timeout.

## Remote Python executors[[smolagents.remote_executors.RemotePythonExecutor]]

#### smolagents.remote_executors.RemotePythonExecutor[[smolagents.remote_executors.RemotePythonExecutor]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L53)

Executor of Python code in a remote environment.

run_code_raise_errorssmolagents.remote_executors.RemotePythonExecutor.run_code_raise_errorshttps://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L82[{"name": "code", "val": ": str"}]- **code** (`str`) -- Python code to execute.0`CodeOutput`Code output containing the result, logs, and whether it is the final answer.

Execute Python code in the remote environment and return the result.

**Parameters:**

additional_imports (`list[str]`) : Additional Python packages to install.

logger (`Logger`) : Logger to use for output and errors.

allow_pickle (`bool`, default `False`) : Whether to allow pickle serialization for objects that cannot be safely serialized to JSON. - `False` (default, recommended): Only safe JSON serialization is used. Raises error if object cannot be safely serialized. - `True` (legacy mode): Tries safe JSON serialization first, falls back to pickle with warning if needed.  **Security Warning:** Pickle deserialization can execute arbitrary code. Only set `allow_pickle=True` if you fully trust the execution environment and need backward compatibility with custom types.

**Returns:**

``CodeOutput``

Code output containing the result, logs, and whether it is the final answer.
#### send_variables[[smolagents.remote_executors.RemotePythonExecutor.send_variables]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L115)

Send variables to the kernel namespace using SafeSerializer.

Uses prefix-based format ("safe:..." or "pickle:...").
When allow_pickle=False, only safe JSON serialization is allowed.
When allow_pickle=True, pickle fallback is enabled for complex types.

### BlaxelExecutor[[smolagents.BlaxelExecutor]]

#### smolagents.BlaxelExecutor[[smolagents.BlaxelExecutor]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L859)

Remote Python code executor in a Blaxel sandbox.

Blaxel provides fast-launching virtual machines that start from hibernation in under 25ms
and scale back to zero after inactivity while maintaining memory state.

cleanupsmolagents.BlaxelExecutor.cleanuphttps://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L1049[]
Sync wrapper to clean up sandbox and resources.

**Parameters:**

additional_imports (`list[str]`) : Additional Python packages to install.

logger (`Logger`) : Logger to use for output and errors.

allow_pickle (`bool`, default `False`) : Whether to allow pickle serialization for objects that cannot be safely serialized to JSON. - `False` (default, recommended): Only safe JSON serialization is used. Raises error if object cannot be safely serialized. - `True` (legacy mode): Tries safe JSON serialization first, falls back to pickle with warning if needed.  **Security Warning:** Pickle deserialization can execute arbitrary code. Only set `allow_pickle=True` if you fully trust the execution environment and need backward compatibility with custom types.

sandbox_name (`str`, *optional*) : Name for the sandbox. Defaults to "smolagent-executor".

image (`str`, default `"blaxel/jupyter-notebook"`) : Docker image to use.

memory (`int`, default `4096`) : Memory allocation in MB.

ttl (`str`, *optional*) : Time to live in seconds.

region (`str`, *optional*) : Deployment region. If not specified, Blaxel chooses default.
#### delete[[smolagents.BlaxelExecutor.delete]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L1067)

Ensure cleanup on deletion.
#### install_packages[[smolagents.BlaxelExecutor.install_packages]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L982)

Helper method to install packages asynchronously.
#### run_code_raise_errors[[smolagents.BlaxelExecutor.run_code_raise_errors]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L963)

Execute Python code in the Blaxel sandbox and return the result.

**Parameters:**

code (`str`) : Python code to execute.

**Returns:**

``CodeOutput``

Code output containing the result, logs, and whether it is the final answer.

### E2BExecutor[[smolagents.E2BExecutor]]

#### smolagents.E2BExecutor[[smolagents.E2BExecutor]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L335)

Remote Python code executor in an E2B sandbox.

cleanupsmolagents.E2BExecutor.cleanuphttps://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L438[]
Clean up the E2B sandbox and resources.

**Parameters:**

additional_imports (`list[str]`) : Additional Python packages to install.

logger (`Logger`) : Logger to use for output and errors.

allow_pickle (`bool`, default `False`) : Whether to allow pickle serialization for objects that cannot be safely serialized to JSON. - `False` (default, recommended): Only safe JSON serialization is used. Raises error if object cannot be safely serialized. - `True` (legacy mode): Tries safe JSON serialization first, falls back to pickle with warning if needed.  **Security Warning:** Pickle deserialization can execute arbitrary code. Only set `allow_pickle=True` if you fully trust the execution environment and need backward compatibility with custom types.

- ****kwargs** : Additional keyword arguments to pass to the E2B Sandbox instantiation.
#### run_code_raise_errors[[smolagents.E2BExecutor.run_code_raise_errors]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L374)

Execute Python code in the E2B sandbox and return the result.

**Parameters:**

code (`str`) : Python code to execute.

**Returns:**

``CodeOutput``

Code output containing the result, logs, and whether it is the final answer.

### ModalExecutor[[smolagents.ModalExecutor]]

#### smolagents.ModalExecutor[[smolagents.ModalExecutor]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L726)

Remote Python code executor in a Modal sandbox.

cleanupsmolagents.ModalExecutor.cleanuphttps://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L828[]
Clean up the Modal sandbox by terminating it.

**Parameters:**

additional_imports (`list[str]`) : Additional Python packages to install.

logger (`Logger`) : Logger to use for output and errors.

allow_pickle (`bool`, default `False`) : Whether to allow pickle serialization for objects that cannot be safely serialized to JSON. - `False` (default, recommended): Only safe JSON serialization is used. Raises error if object cannot be safely serialized. - `True` (legacy mode): Tries safe JSON serialization first, falls back to pickle with warning if needed.  **Security Warning:** Pickle deserialization can execute arbitrary code. Only set `allow_pickle=True` if you fully trust the execution environment and need backward compatibility with custom types.

app_name (`str`, default `"smolagent-executor"`) : App name.

port (`int`, default `8888`) : Port for jupyter to bind to.

create_kwargs (`dict`, *optional*) : Additional keyword arguments to pass to the Modal Sandbox create command. See `modal.Sandbox.create` [docs](https://modal.com/docs/reference/modal.Sandbox#create) for all the keyword arguments.
#### delete[[smolagents.ModalExecutor.delete]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L833)

Ensure cleanup on deletion.
#### run_code_raise_errors[[smolagents.ModalExecutor.run_code_raise_errors]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L813)

Execute Python code in the Modal sandbox and return the result.

**Parameters:**

code (`str`) : Python code to execute.

**Returns:**

``CodeOutput``

Code output containing the result, logs, and whether it is the final answer.

### DockerExecutor[[smolagents.DockerExecutor]]

#### smolagents.DockerExecutor[[smolagents.DockerExecutor]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L551)

Remote Python code executor using Jupyter Kernel Gateway in a Docker container.

cleanupsmolagents.DockerExecutor.cleanuphttps://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L694[]
Clean up the Docker container and resources.

**Parameters:**

additional_imports (`list[str]`) : Additional Python packages to install.

logger (`Logger`) : Logger to use for output and errors.

allow_pickle (`bool`, default `False`) : Whether to allow pickle serialization for objects that cannot be safely serialized to JSON. - `False` (default, recommended): Only safe JSON serialization is used. Raises error if object cannot be safely serialized. - `True` (legacy mode): Tries safe JSON serialization first, falls back to pickle with warning if needed.  **Security Warning:** Pickle deserialization can execute arbitrary code. Only set `allow_pickle=True` if you fully trust the execution environment and need backward compatibility with custom types.

host (`str`, default `"127.0.0.1"`) : Host to bind to.

port (`int`, default `8888`) : Port to bind to.

image_name (`str`, default `"jupyter-kernel"`) : Name of the Docker image to use. If the image doesn't exist, it will be built.

build_new_image (`bool`, default `True`) : Whether to rebuild a new image even if it already exists.

container_run_kwargs (`dict`, *optional*) : Additional keyword arguments to pass to the Docker container run command.

dockerfile_content (`str`, *optional*) : Custom Dockerfile content. If `None`, uses default.
#### delete[[smolagents.DockerExecutor.delete]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L706)

Ensure cleanup on deletion.
#### run_code_raise_errors[[smolagents.DockerExecutor.run_code_raise_errors]]

[Source](https://github.com/huggingface/smolagents/blob/vr_2321/src/smolagents/remote_executors.py#L679)

Execute Python code in the Docker container and return the result.

**Parameters:**

code (`str`) : Python code to execute.

**Returns:**

``CodeOutput``

Code output containing the result, logs, and whether it is the final answer.