E2B SDK

Common errors

• ImportError: cannot import name 'CodeInterpreter' from 'e2b_code_interpreter'

  cause The `CodeInterpreter` class has likely been deprecated or moved, and the current recommended way to interact with the e2b sandbox for code execution is through the `Sandbox` class directly from the `e2b_code_interpreter` package or the main `e2b` package.
  fix Replace `from e2b_code_interpreter import CodeInterpreter` with `from e2b_code_interpreter import Sandbox` (if using the code interpreter specific package) or `from e2b import Sandbox` (for the general SDK), and use `Sandbox.create()` to initialize the sandbox.

• e2b.exceptions.AuthenticationException: Authentication failed

  cause This error occurs when the E2B API key is missing or invalid, preventing the SDK from authenticating with the E2B service.
  fix Ensure your E2B API key is correctly set as an environment variable named `E2B_API_KEY` or passed explicitly when creating the sandbox, for example: `sandbox = Sandbox.create(api_key='YOUR_API_KEY')`.

• e2b.exceptions.TimeoutException: The sandbox is running but port is not open

  cause This error often indicates that the sandbox timed out before the expected service (like a code interpreter) could become ready and open its port, or that the default start command is not properly configured for a custom template.
  fix Increase the sandbox timeout when creating it (e.g., `Sandbox.create(timeout=60)`), ensure your custom template is built on a `code-interpreter` base image, and verify the `setStartCmd` is correct if building from a Docker image.

• RuntimeError: Attempted to access 'response.content' on a streaming response. Call 'response.read()' first.

  cause This happens when trying to directly access the content of a streaming command response before it has been fully read and buffered, particularly with older SDK versions.
  fix Explicitly call the `.read()` or `.aread()` (for async) method on the command result object to ensure the entire output stream is consumed before attempting to access its content. For example: `result = sandbox.commands.run('ls -l'); output = result.read().stdout`

Warnings

• breaking The method for creating a Sandbox instance changed in v2. Instead of direct instantiation `Sandbox()`, you must now use the class method `Sandbox.create()`.
  Fix: Replace `sandbox = Sandbox()` with `sandbox = Sandbox.create()`.
• breaking File operation APIs were updated in v2 for consistency. Single file writes now use `sandbox.files.write()`, and multiple file writes use `sandbox.files.write_files()`.
  Fix: Migrate file write operations from older patterns to `sandbox.files.write(path, content)` or `sandbox.files.write_files([{'path': ..., 'data': ...}])`.
• gotcha An E2B API Key is required for most operations and must be provided, typically via the `E2B_API_KEY` environment variable or explicitly passed during sandbox creation. Failing to provide it will result in errors or limited functionality.
  Fix: Sign up on the E2B dashboard, obtain your API key, and set it as an environment variable (`export E2B_API_KEY=e2b_***`) or pass it as an argument (`Sandbox.create(api_key='e2b_***')`).
• gotcha There are two distinct Python packages for E2B: `e2b` (for general sandbox management and commands) and `e2b-code-interpreter` (specifically for `run_code()` functionality). Both can export a `Sandbox` class, leading to potential import confusion if not installed and used correctly.
  Fix: Install `e2b-code-interpreter` separately if `run_code()` is needed. Pay attention to the import statements: `from e2b import Sandbox` for core SDK, and `from e2b_code_interpreter import Sandbox` for code interpretation.
• gotcha In v2, sandboxes are secure by default. If you are using custom templates created before `envd v0.2.0`, you might need to rebuild them to enable secure communication, or you may encounter errors.
  Fix: Rebuild older custom templates or temporarily disable secure communication by setting `secure=False` during sandbox creation (not recommended for production). Check template `envd` version using `e2b template list` CLI command.

Install

• pip install e2b Core SDK
• pip install e2b-code-interpreter Code Interpreter SDK (for run_code)

Imports

• Sandbox

  from e2b import Sandbox

  Use this for general sandbox management (commands, files, lifecycle).
• Sandbox

  from e2b_code_interpreter import Sandbox

  Use this specifically when you need `run_code()` functionality. Requires the `e2b-code-interpreter` package. In v2, the synchronous SDK's primary Sandbox class is imported from here.

Quickstart

This quickstart demonstrates how to create an E2B sandbox, run a shell command inside it, and print the output. It highlights the importance of setting the E2B_API_KEY environment variable for authentication.

import os
from e2b import Sandbox

# Ensure E2B_API_KEY is set in your environment
# You can get your API key from the E2B dashboard: https://e2b.dev/docs/quickstart/running-your-first-sandbox
api_key = os.environ.get('E2B_API_KEY', '')
if not api_key:
    print("Warning: E2B_API_KEY environment variable not set. Sandbox creation may fail or default to a limited scope.")

with Sandbox.create(api_key=api_key) as sandbox:
    print(f"Sandbox created with ID: {sandbox.sandbox_id}")
    result = sandbox.commands.run('echo "Hello from E2B!"')
    print(f"Stdout: {result.stdout}")
    if result.stderr:
        print(f"Stderr: {result.stderr}")

print("Sandbox session ended.")