{"record":{"id":"96a5a97a2403f32e","repo":"crewAIInc/crewAI","slug":"the-e2b-package-is-required-for-e2b-sandbox-tool","errorCode":null,"errorMessage":"The 'e2b' package is required for E2B sandbox tools. Install it with: uv add e2b  (or) pip install e2b","messagePattern":"The 'e2b' package is required for E2B sandbox tools\\. Install it with: uv add e2b  \\(or\\) pip install e2b","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/tools/e2b_sandbox_tool/e2b_base_tool.py","lineNumber":120,"sourceCode":"    _lock: threading.Lock = PrivateAttr(default_factory=threading.Lock)\n    _cleanup_registered: bool = PrivateAttr(default=False)\n\n    _sdk_cache: ClassVar[dict[str, Any]] = {}\n\n    @classmethod\n    def _import_sandbox_class(cls) -> Any:\n        \"\"\"Return the Sandbox class used by this tool.\n\n        Subclasses override this to swap in a different SDK (e.g. the code\n        interpreter sandbox). The default uses plain `e2b.Sandbox`.\n        \"\"\"\n        cached = cls._sdk_cache.get(\"e2b.Sandbox\")\n        if cached is not None:\n            return cached\n        try:\n            from e2b import Sandbox  # type: ignore[import-untyped]\n        except ImportError as exc:\n            raise ImportError(\n                \"The 'e2b' package is required for E2B sandbox tools. \"\n                \"Install it with: uv add e2b  (or) pip install e2b\"\n            ) from exc\n        cls._sdk_cache[\"e2b.Sandbox\"] = Sandbox\n        return Sandbox\n\n    def _connect_kwargs(self) -> dict[str, Any]:\n        kwargs: dict[str, Any] = {}\n        if self.api_key is not None:\n            kwargs[\"api_key\"] = self.api_key.get_secret_value()\n        if self.domain:\n            kwargs[\"domain\"] = self.domain\n        if self.sandbox_timeout is not None:\n            kwargs[\"timeout\"] = self.sandbox_timeout\n        return kwargs\n\n    def _create_kwargs(self) -> dict[str, Any]:\n        kwargs: dict[str, Any] = self._connect_kwargs()","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/e2b_sandbox_tool/e2b_base_tool.py#L102-L138","documentation":"E2B sandbox tools resolve their SDK class lazily via _import_sandbox_class; the first call imports e2b.Sandbox and on ImportError raises a guidance message telling you to install the e2b package. A module-level cache (_sdk_cache) means the import is attempted once per class, after which either the class is reused or the error is re-raised on every call. This fires only when e2b is missing from the environment — not on API or network problems.","triggerScenarios":"Instantiating/first-running any E2B sandbox tool (E2BSandboxTool and subclasses) in an environment where pip show e2b fails; crewai-tools installed without the e2b extra; a venv mismatch where the tool runs under a different interpreter than the one where e2b was installed.","commonSituations":"Fresh clones that installed crewai-tools core only; deploying to containers that prune 'dev' dependencies; multiple virtualenvs or system/pip confusion so e2b exists for one interpreter but not the runtime one.","solutions":["Install the SDK: pip install e2b (or uv add e2b), matching the message.","Confirm it landed in the running interpreter: python -c \"import e2b; print(e2b.__version__)\" using the same python that runs your app.","Add e2b (or crewai-tools[e2b] if provided) to your lockfile/requirements so deployments keep it.","If using a code-interpreter variant, make sure the right e2b extra (e.g. e2b-code-interpreter) is installed per the subclass docs."],"exampleFix":"# before\npip install crewai-tools\nE2BSandboxTool(...)  # ImportError: 'e2b' package required\n\n# after\npip install crewai-tools e2b\nE2BSandboxTool(...)  # SDK class resolves and caches","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec('e2b') is None:\n    raise ImportError(\"The 'e2b' package is required for E2B sandbox tools. Install it with: pip install e2b\")\n\nsandbox_tool = E2BSandboxTool(...)","typeGuard":"def e2b_available() -> bool:\n    return importlib.util.find_spec('e2b') is not None","tryCatchPattern":"try:\n    result = tool._run(code=src)\nexcept ImportError as e:\n    if \"'e2b' package is required\" in str(e):\n        raise DeploymentError('e2b missing in runtime image — add it to requirements') from e\n    raise","preventionTips":["Add e2b to requirements.txt/pyproject and rebuild deployment images.","Run a startup capability check (find_spec) and report missing optional deps clearly.","Verify with the same interpreter that runs the app: python -c 'import e2b'."],"tags":["e2b","importerror","dependency","sandbox","installation"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}