mirror of
https://github.com/open-webui/docs.git
synced 2026-03-27 13:28:37 +07:00
docs: update code interpreter docs for persistent Pyodide FS, file browser, and Jupyter legacy status
This commit is contained in:
DrMelone
@@ -25,17 +25,27 @@ Open WebUI supports multiple code execution backends, each suited to different u
|
||||
|
||||
### Pyodide (Default)
|
||||
|
||||
Pyodide runs Python in the browser via WebAssembly. It is sandboxed and safe for multi-user environments, but comes with constraints:
|
||||
Pyodide runs Python in the browser via WebAssembly. It is sandboxed and safe for multi-user environments, but comes with some constraints:
|
||||
|
||||
- **No persistent storage** — the filesystem resets between executions.
|
||||
- **Persistent file storage** — the virtual filesystem at `/mnt/uploads/` is backed by IndexedDB (IDBFS). Files persist across code executions within the same session and survive page reloads.
|
||||
- **Built-in file browser** — when Code Interpreter is enabled, a file browser panel appears in the chat controls sidebar. You can browse, preview, upload, download, and delete files in the Pyodide filesystem — no terminal needed.
|
||||
- **User file access** — files attached to messages are automatically placed in `/mnt/uploads/` before code execution, so the model (and your code) can read them directly.
|
||||
- **Limited library support** — only a subset of Python packages are available. Libraries that rely on C extensions or system calls may not work.
|
||||
- **No shell access** — cannot run shell commands, install packages, or interact with the OS.
|
||||
|
||||
:::tip
|
||||
Pyodide works well for **text analysis, hash computation, chart generation**, and other self-contained tasks. Chart libraries like matplotlib produce base64-encoded images that Open WebUI automatically captures, uploads as files, and injects direct image links into the output — so models can display charts directly in chat without any extra setup.
|
||||
Pyodide works well for **text analysis, hash computation, chart generation, file processing**, and other self-contained tasks. Chart libraries like matplotlib produce base64-encoded images that Open WebUI automatically captures, uploads as files, and injects direct image links into the output — so models can display charts directly in chat without any extra setup.
|
||||
:::
|
||||
|
||||
### Jupyter
|
||||
:::note Mutually exclusive with Open Terminal
|
||||
The Code Interpreter toggle and the Open Terminal toggle cannot be active at the same time. Activating one will deactivate the other — they serve similar purposes but use different execution backends.
|
||||
:::
|
||||
|
||||
### Jupyter (Legacy)
|
||||
|
||||
:::caution Legacy Engine
|
||||
Jupyter is now considered a **legacy** code execution engine. The Pyodide engine is recommended for most use cases, and Open Terminal is recommended when you need full server-side execution. Jupyter support may be deprecated in a future release.
|
||||
:::
|
||||
|
||||
Jupyter provides a full Python environment and can handle virtually any task — file creation, package installation, and complex library usage. However, it has significant drawbacks in shared deployments:
|
||||
|
||||
@@ -58,15 +68,17 @@ If you are running a multi-user or organizational deployment, **Jupyter is not r
|
||||
|
||||
### Comparison
|
||||
|
||||
| Consideration | Pyodide | Jupyter | Open Terminal |
|
||||
| Consideration | Pyodide | Jupyter (Legacy) | Open Terminal |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Runs in** | Browser (WebAssembly) | Server (Python kernel) | Server (Docker container) |
|
||||
| **Library support** | Limited subset | Full Python ecosystem | Full OS — any language, any tool |
|
||||
| **Shell access** | ❌ None | ⚠️ Limited | ✅ Full shell |
|
||||
| **File persistence** | ❌ Resets each execution | ✅ Shared filesystem | ✅ Container filesystem (until removal) |
|
||||
| **File persistence** | ✅ IDBFS (persists across executions & reloads) | ✅ Shared filesystem | ✅ Container filesystem (until removal) |
|
||||
| **File browser** | ✅ Built-in sidebar panel | ❌ None | ✅ Built-in sidebar panel |
|
||||
| **User file access** | ✅ Attached files placed in `/mnt/uploads/` | ❌ Manual | ✅ Attached files available |
|
||||
| **Isolation** | ✅ Browser sandbox | ❌ Shared environment | ✅ Container-level (when using Docker) |
|
||||
| **Multi-user safety** | ✅ Per-user by design | ⚠️ Not isolated | ⚠️ Single instance (per-user containers planned) |
|
||||
| **File generation** | ❌ Very limited | ✅ Full support | ✅ Full support with upload/download |
|
||||
| **File generation** | ✅ Write to `/mnt/uploads/`, download via file browser | ✅ Full support | ✅ Full support with upload/download |
|
||||
| **Setup** | None (built-in) | Admin configures globally | Native integration via Settings → Integrations, or as a Tool Server |
|
||||
| **Recommended for orgs** | ✅ Safe default | ❌ Not without isolation | ✅ Per-user by design |
|
||||
| **Enterprise scalability** | ✅ Client-side, no server load | ❌ Single shared instance | ⚠️ Manual per-user instances |
|
||||
|
||||
@@ -12,7 +12,7 @@ Open WebUI provides two ways to execute Python code:
|
||||
1. **Manual Code Execution**: Run Python code blocks generated by LLMs using a "Run" button in the browser (uses Pyodide/WebAssembly).
|
||||
2. **Code Interpreter**: An AI capability that allows models to automatically write and execute Python code as part of their response (uses Pyodide or Jupyter).
|
||||
|
||||
Both methods support visual outputs like matplotlib charts that can be displayed inline in your chat.
|
||||
Both methods support visual outputs like matplotlib charts that can be displayed inline in your chat. When using the Pyodide engine, a **persistent virtual filesystem** at `/mnt/uploads/` is available — files survive across code executions and page reloads, and files attached to messages are automatically placed there for your code to access.
|
||||
|
||||
## Code Interpreter Capability
|
||||
|
||||
@@ -35,7 +35,7 @@ The Code Interpreter is a model capability that enables LLMs to write and execut
|
||||
|
||||
These settings can be configured at **Admin Panel → Settings → Code Execution**:
|
||||
- Enable/disable code interpreter
|
||||
- Select engine (Pyodide or Jupyter)
|
||||
- Select engine: **Pyodide** (recommended) or **Jupyter (Legacy)**
|
||||
- Configure Jupyter connection settings
|
||||
- Set blocked modules
|
||||
|
||||
@@ -44,12 +44,16 @@ These settings can be configured at **Admin Panel → Settings → Code Executio
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `ENABLE_CODE_INTERPRETER` | `true` | Enable/disable code interpreter globally |
|
||||
| `CODE_INTERPRETER_ENGINE` | `pyodide` | Engine to use: `pyodide` (browser) or `jupyter` (server) |
|
||||
| `CODE_INTERPRETER_ENGINE` | `pyodide` | Engine to use: `pyodide` (browser, recommended) or `jupyter` (server, legacy) |
|
||||
| `CODE_INTERPRETER_PROMPT_TEMPLATE` | (built-in) | Custom prompt template for code interpreter |
|
||||
| `CODE_INTERPRETER_BLACKLISTED_MODULES` | `""` | Comma-separated list of blocked Python modules |
|
||||
|
||||
For Jupyter configuration, see the [Jupyter Notebook Integration](/tutorials/integrations/dev-tools/jupyter) tutorial.
|
||||
|
||||
:::note Filesystem Prompt Injection
|
||||
When the Pyodide engine is selected, Open WebUI automatically appends a filesystem-awareness prompt to the code interpreter instructions. This tells the model about `/mnt/uploads/` and how to discover user-uploaded files. When using Jupyter, this filesystem prompt is not appended (since Jupyter has its own filesystem). You do not need to include filesystem instructions in your custom `CODE_INTERPRETER_PROMPT_TEMPLATE` — they are added automatically.
|
||||
:::
|
||||
|
||||
### Native Function Calling (Native Mode)
|
||||
|
||||
When using **Native function calling mode** with a capable model (e.g., GPT-5, Claude 4.5, MiniMax M2.5), the code interpreter is available as a builtin tool called `execute_code`. This provides a more integrated experience:
|
||||
@@ -126,6 +130,8 @@ If you see raw base64 text appearing in chat responses, the model is incorrectly
|
||||
|
||||
Open WebUI includes a browser-based Python environment using [Pyodide](https://pyodide.org/) (WebAssembly). This allows running Python scripts directly in your browser with no server-side setup.
|
||||
|
||||
The Pyodide worker is **persistent** — it is created once and reused across code executions. This means variables, imported modules, and files written to the virtual filesystem are retained between executions within the same session.
|
||||
|
||||
### Running Code Manually
|
||||
|
||||
1. Ask an LLM to write Python code
|
||||
@@ -152,6 +158,41 @@ Pyodide includes the following pre-configured packages:
|
||||
Packages not pre-compiled in Pyodide cannot be installed at runtime. For additional packages, consider using the Jupyter integration or forking Pyodide to add custom packages.
|
||||
:::
|
||||
|
||||
## Persistent File System
|
||||
|
||||
When using the Pyodide engine, a persistent virtual filesystem is mounted at `/mnt/uploads/`. This filesystem is backed by the browser's IndexedDB via [IDBFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#filesystem-api-idbfs) and provides:
|
||||
|
||||
- **Cross-execution persistence** — files written by one code execution are accessible in subsequent executions.
|
||||
- **Cross-reload persistence** — files survive page reloads (stored in IndexedDB).
|
||||
- **Automatic upload mounting** — files attached to messages are fetched from the server and placed in `/mnt/uploads/` before code execution, so the model can read them directly.
|
||||
- **File browser panel** — when Code Interpreter is enabled, a file browser appears in the chat controls sidebar. You can browse, preview, upload, download, and delete files — no terminal needed.
|
||||
|
||||
### Working with Files in Code
|
||||
|
||||
```python
|
||||
import os
|
||||
|
||||
# List uploaded files
|
||||
print(os.listdir('/mnt/uploads'))
|
||||
|
||||
# Read a user-uploaded CSV
|
||||
import pandas as pd
|
||||
df = pd.read_csv('/mnt/uploads/data.csv')
|
||||
print(df.head())
|
||||
|
||||
# Write output to the persistent filesystem (downloadable via file browser)
|
||||
df.to_csv('/mnt/uploads/result.csv', index=False)
|
||||
print('Saved result.csv to /mnt/uploads/')
|
||||
```
|
||||
|
||||
:::tip
|
||||
The file browser panel lets you download any file the model creates. Ask the model to save its output to `/mnt/uploads/` and it will appear in the file browser for download.
|
||||
:::
|
||||
|
||||
:::note Jupyter Engine
|
||||
The persistent filesystem prompt and `/mnt/uploads/` integration are **Pyodide-only**. When using the Jupyter engine, files are managed through Jupyter's own filesystem. The file browser panel is not available for Jupyter.
|
||||
:::
|
||||
|
||||
## Example: Creating a Chart
|
||||
|
||||
**Prompt:**
|
||||
|
||||
Reference in New Issue
Block a user