Document Docker image variants and Python migration

Sync documentation for PR #259 which introduces lean and Python image variants:

- Add documentation for two image variants (default lean vs -python)
- Document migration guide for Python users upgrading from <0.5.6
- Add PYTHON_NOT_AVAILABLE error handling examples
- Update all Dockerfile examples to show appropriate variant usage

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: claude

src/content/docs/sandbox/api/interpreter.mdx

@@ -104,6 +104,26 @@ if (result.error) {
 ```
 </TypeScriptExample>
 
+**Python not available**:
+
+If you attempt to execute Python code without the Python image variant, you will receive a `PYTHON_NOT_AVAILABLE` error:
+
+<TypeScriptExample>
+```
+try {
+  const ctx = await sandbox.createCodeContext({ language: 'python' });
+} catch (error) {
+  if (error.code === 'PYTHON_NOT_AVAILABLE') {
+    // Update Dockerfile to use Python variant:
+    // FROM docker.io/cloudflare/sandbox:0.5.6-python
+    console.error('Python is not available in the default image');
+  }
+}
+```
+</TypeScriptExample>
+
+See [Dockerfile reference](/sandbox/configuration/dockerfile/) for migration instructions.
+
 ### `listCodeContexts()`
 
 List all active code execution contexts.

src/content/docs/sandbox/configuration/dockerfile.mdx

@@ -9,35 +9,57 @@ Customize the sandbox container image with your own packages, tools, and configu
 
 ## Base image
 
-The Sandbox SDK uses a Ubuntu-based Linux container with Python, Node.js (via Bun), and common development tools pre-installed:
+The Sandbox SDK provides two image variants optimized for different use cases:
+
+### Default (lean) image
+
+Optimized for shell commands and JavaScript/TypeScript execution (~600-800MB):
 
 ```dockerfile
 FROM docker.io/cloudflare/sandbox:0.3.3
 ```
 
-:::caution[Version synchronization required]
-Always match the Docker image version to your npm package version. If you're using `@cloudflare/sandbox@0.3.3`, use `docker.io/cloudflare/sandbox:0.3.3` as your base image.
-
-**Why this matters**: The SDK automatically checks version compatibility on startup. Mismatched versions can cause features to break or behave unexpectedly. If versions don't match, you'll see warnings in your logs.
-
-See [Version compatibility](/sandbox/concepts/sandboxes/#version-compatibility) for troubleshooting version mismatch warnings.
-:::
-
 **What's included:**
 
 - Ubuntu 22.04 LTS base
-- Python 3.11.14 with pip and venv
 - Node.js 20 LTS with npm
 - Bun 1.x (JavaScript/TypeScript runtime)
-- Pre-installed Python packages: matplotlib, numpy, pandas, ipython
 - System utilities: curl, wget, git, jq, zip, unzip, file, procps, ca-certificates
 
+### Python image
+
+Full image with Python and data science packages (~1.3GB):
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:0.3.3-python
+```
+
+**What's included (in addition to default image):**
+
+- Python 3.11.14 with pip and venv
+- Pre-installed Python packages: matplotlib, numpy, pandas, ipython
+
+:::note[Choosing the right variant]
+Use the default (lean) image for shell operations, JavaScript/TypeScript execution, and Git workflows. Only use the `-python` variant if you need Python code execution with [`CodeInterpreter.runCode()`](/sandbox/api/interpreter/).
+
+Using the lean image reduces image size by ~500MB and improves cold start times.
+:::
+
+:::caution[Version synchronization required]
+Always match the Docker image version to your npm package version. If you're using `@cloudflare/sandbox@0.3.3`, use `docker.io/cloudflare/sandbox:0.3.3` (or `0.3.3-python`) as your base image.
+
+**Why this matters**: The SDK automatically checks version compatibility on startup. Mismatched versions can cause features to break or behave unexpectedly. If versions don't match, you'll see warnings in your logs.
+
+See [Version compatibility](/sandbox/concepts/sandboxes/#version-compatibility) for troubleshooting version mismatch warnings.
+:::
+
 ## Creating a custom image
 
 Create a `Dockerfile` in your project root:
 
 ```dockerfile title="Dockerfile"
-FROM docker.io/cloudflare/sandbox:0.3.3
+# Use Python variant if you need Python packages
+FROM docker.io/cloudflare/sandbox:0.3.3-python
 
 # Install additional Python packages
 RUN pip install --no-cache-dir \
@@ -75,6 +97,7 @@ When you run `wrangler dev` or `wrangler deploy`, Wrangler automatically builds
 Run services automatically when the container starts by creating a custom startup script:
 
 ```dockerfile title="Dockerfile"
+# Choose appropriate variant (default or -python)
 FROM docker.io/cloudflare/sandbox:0.3.3
 
 COPY my-app.js /workspace/my-app.js
@@ -108,6 +131,19 @@ node /workspace/api-server.js &
 exec bun /container-server/dist/index.js
 ```
 
+## Migration guide
+
+If you are upgrading from a version prior to 0.5.6 and use Python code execution, update your Dockerfile to use the `-python` variant:
+
+```diff title="Dockerfile"
+- FROM docker.io/cloudflare/sandbox:0.5.5
++ FROM docker.io/cloudflare/sandbox:0.5.6-python
+```
+
+**Why this change was made**: Separating Python into its own image variant reduces the default image size by ~500MB, improving cold start times for workloads that do not require Python.
+
+If you attempt to execute Python code without the `-python` variant, you will receive a `PYTHON_NOT_AVAILABLE` error with instructions to update your Dockerfile.
+
 ## Related resources
 
 - [Image Management](/containers/platform-details/image-management/) - Building and pushing images to Cloudflare\'s registry

src/content/docs/sandbox/guides/code-execution.mdx

@@ -10,6 +10,16 @@ import { TypeScriptExample } from "~/components";
 
 This guide shows you how to execute Python and JavaScript code with rich outputs using the Code Interpreter API.
 
+:::note[Python execution requires Python image variant]
+To execute Python code, your Dockerfile must use the `-python` image variant:
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:0.5.6-python
+```
+
+The default (lean) image does not include Python. If you attempt Python execution without the Python variant, you will receive a `PYTHON_NOT_AVAILABLE` error. See [Dockerfile reference](/sandbox/configuration/dockerfile/) for details.
+:::
+
 ## When to use code interpreter
 
 Use the Code Interpreter API for **simple, direct code execution** with minimal setup: