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 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

Local Python executor[[smolagents.LocalPythonExecutor]]

smolagents.LocalPythonExecutor[[smolagents.LocalPythonExecutor]]

Source

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

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.0CodeOutputCode 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

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

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

Ensure cleanup on deletion.

install_packages[[smolagents.BlaxelExecutor.install_packages]]

Source

Helper method to install packages asynchronously.

run_code_raise_errors[[smolagents.BlaxelExecutor.run_code_raise_errors]]

Source

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

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

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

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 for all the keyword arguments.

delete[[smolagents.ModalExecutor.delete]]

Source

Ensure cleanup on deletion.

run_code_raise_errors[[smolagents.ModalExecutor.run_code_raise_errors]]

Source

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

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

Ensure cleanup on deletion.

run_code_raise_errors[[smolagents.DockerExecutor.run_code_raise_errors]]

Source

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.