Skip to content

docs: Mark native Python as stable #3972

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ivov wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: Mark native Python as stable #3972

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9b38c6d
docs: Move native Python to stable
ivov Dec 4, 2025
af6e0b6
Update _snippets/integrations/builtin/core-nodes/code-node.md
ivov Dec 4, 2025
9108381
Update docs/hosting/configuration/task-runners.md
ivov Dec 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions _snippets/integrations/builtin/core-nodes/code-node.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ The Code node editing environment supports time-saving and useful keyboard short

## Python (Pyodide - legacy)

Pyodide is a legacy feature. Future versions of n8n will no longer support this feature.
Pyodide is a legacy feature. n8n v2 no longer supports this feature.

n8n added Python support in version 1.0. It doesn't include a Python executable. Instead, n8n provides Python support using [Pyodide](https://pyodide.org/en/stable/), which is a port of CPython to WebAssembly. This limits the available Python packages to the [Packages included with Pyodide](https://pyodide.org/en/stable/usage/packages-in-pyodide.html#packages-in-pyodide). n8n downloads the package automatically the first time you use it.

Expand All @@ -82,9 +82,9 @@ You can't access the file system or make HTTP requests. Use the following nodes
* [Read/Write File From Disk](/integrations/builtin/core-nodes/n8n-nodes-base.readwritefile.md)
* [HTTP Request](/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/index.md)

## Python (Native - beta)
## Python (Native)

n8n added native Python support using task runners (beta) in version 1.111.0.
n8n added native Python support using task runners in version 1.111.0 and is stable as of n8n v2.

Main differences from Pyodide:

Expand All @@ -93,9 +93,7 @@ Main differences from Pyodide:
- Native Python denies insecure built-ins by default. See [task runners environment variables](/hosting/configuration/environment-variables/task-runners.md) for more details.
- Unlike Pyodide, which accepts dot access notation, for example, `item.json.myNewField`, native Python only accepts bracket access notation, for example, `item["json"]["my_new_field"]`. There may be other minor syntax differences where Pyodide accepts constructs that aren't legal in native Python.

Keep in mind upgrading to native Python is a breaking change, so you may need to adjust your Python scripts to use the native Python runner.

This feature is in beta and is subject to change. As it becomes stable, n8n will roll it out progressively to n8n cloud users during 2025. Self-hosting users can [try it out](/hosting/configuration/task-runners.md) and provide feedback.
Upgrading to native Python is a breaking change, so you may need to adjust your Python scripts to use the native Python runner.

## Coding in n8n

Expand Down
2 changes: 1 addition & 1 deletion docs/2-0-breaking-changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Starting with v2.0, the main `n8nio/n8n` Docker image will no longer include the

n8n will remove the Pyodide-based Python Code node and tool and replace them with a [task runner-based](/hosting/configuration/task-runners.md) implementation that uses native Python for better security and performance. Starting in v2.0, you can only use Python Code nodes with task runners in [external mode](/hosting/configuration/task-runners.md#external-mode) and native Python tools.

The native Python Code node doesn't support built-in variables like `_input` or dot access notation, which were available in the Pyodide-based version. For details, see the [Code node documentation](/integrations/builtin/core-nodes/n8n-nodes-base.code/index.md#python-native-beta).
The native Python Code node doesn't support built-in variables like `_input` or dot access notation, which were available in the Pyodide-based version. For details, see the [Code node documentation](/integrations/builtin/core-nodes/n8n-nodes-base.code/index.md#python-native).

The native Python tool supports `_query` for the input string that the AI Agent passes to the tool when it calls it.

Expand Down
2 changes: 1 addition & 1 deletion docs/code/builtin/n8n-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ You can use Python in the Code node. It isn't available in expressions.
| `$workflow.active` | Whether the workflow is active (true) or not (false). | :white_check_mark: |
| `$workflow.id` | The workflow ID. | :white_check_mark: |
| `$workflow.name` | The workflow name. | :white_check_mark: |
=== "Python (native, beta)"
=== "Python (native)"
| Method | Description |
| ------ | ----------- |
| `_items` | Contains incoming items in "Run once for all items" mode. |
Expand Down
21 changes: 10 additions & 11 deletions docs/hosting/configuration/task-runners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,6 @@

Task runners are a generic mechanism to execute tasks in a secure and performant way. They're used to execute user-provided JavaScript and Python code in the [Code node](/integrations/builtin/core-nodes/n8n-nodes-base.code/index.md).

/// note | In beta
Task runner support for native Python and the `n8nio/runners` image are in beta. Until this feature is stable, you must use the `N8N_NATIVE_PYTHON_RUNNER=true` environment variable to enable the Python runner.
///

This document describes how task runners work and how you can configure them.

## How it works
Expand Down Expand Up @@ -79,6 +75,8 @@
n8n_data:
```
There are three layers of configuration: the n8n container, the runners container, and the launcher inside the runners container.
### Configuring n8n container in external mode
These are the main environment variables that you can set on the n8n container running in external mode:
Expand Down Expand Up @@ -106,14 +104,19 @@

### Configuring launcher in runners container in external mode

The launcher will read environment variables from runners container environment, and will pass them along to each runner as defined in the [default launcher configuration file](https://github.com/n8n-io/n8n/blob/master/docker/images/runners/n8n-task-runners.json), located in the container at `/etc/task-runners.json`. The default launcher configuration file is locked down, but you will likely want to edit this file, for example, to allowlist first- or third-party modules. To customize the launcher configuration file, mount to this path:
The launcher will read environment variables from runners container environment, and will...

Check warning on line 107 in docs/hosting/configuration/task-runners.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[from-microsoft.Ellipses] In general, don't use an ellipsis.

Raw Output:
{"message": "[from-microsoft.Ellipses] In general, don't use an ellipsis.", "location": {"path": "docs/hosting/configuration/task-runners.md", "range": {"start": {"line": 107, "column": 90}}}, "severity": "WARNING"}

- pass environment variables from the launcher's own environment to all runners (`allowed-env`)
- set specific environment variables on specific runners (`env-overrides`)

Which environment variables to pass and to set defined in the [launcher config file](https://github.com/n8n-io/n8n/blob/master/docker/images/runners/n8n-task-runners.json) included in the runners image. This config file is located in the container at `/etc/task-runners.json`. To learn more about the launcher config file, see [here](https://github.com/n8n-io/task-runner-launcher/blob/main/docs/setup.md#config-file).

Check failure on line 112 in docs/hosting/configuration/task-runners.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'config'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'config'?", "location": {"path": "docs/hosting/configuration/task-runners.md", "range": {"start": {"line": 112, "column": 73}}}, "severity": "ERROR"}

The default launcher configuration file is locked down, but you will likely want to edit this file, for example, to allowlist first- or third-party modules. To customize the launcher configuration file, mount to this path:

Check warning on line 114 in docs/hosting/configuration/task-runners.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[from-write-good.Weasel] 'likely' is a weasel word!

Raw Output:
{"message": "[from-write-good.Weasel] 'likely' is a weasel word!", "location": {"path": "docs/hosting/configuration/task-runners.md", "range": {"start": {"line": 114, "column": 70}}}, "severity": "WARNING"}

Check warning on line 114 in docs/hosting/configuration/task-runners.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[from-write-good.Passive] 'is locked' may be passive voice. Use active voice if you can.

Raw Output:
{"message": "[from-write-good.Passive] 'is locked' may be passive voice. Use active voice if you can.", "location": {"path": "docs/hosting/configuration/task-runners.md", "range": {"start": {"line": 114, "column": 41}}}, "severity": "WARNING"}

```
path/to/n8n-task-runners.json:/etc/n8n-task-runners.json
```

For further information about the launcher config file, see [here](https://github.com/n8n-io/task-runner-launcher/blob/main/docs/setup.md#config-file).

## Adding extra dependencies

### 1. Extend the `n8nio/runners` image
Expand Down Expand Up @@ -158,10 +161,6 @@
* `N8N_RUNNERS_STDLIB_ALLOW`: comma-separated list of allowed Python standard library packages.
* `N8N_RUNNERS_EXTERNAL_ALLOW`: comma-separated list of allowed Python packages.

#### Multiple runners and the port for the runner's health check server

When a single runner is configured, the *"health-check-server-port"* field found in the `n8n-task-runners.json` configuration file is optional and defaults to 5681. When multiple runners are configured, this is required and must be unique per runner. Refer to the launcher’s [config file documentation](https://github.com/n8n-io/task-runner-launcher/blob/main/docs/setup.md#config-file) for the full list of options and examples.

Comment on lines -161 to -164
Copy link
Member Author

@ivov ivov Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moving this out of here as

  1. Port config doesn't belong in the image extension steps
  2. The default config file already specifies the correct ports
  3. The launcher's page about the config file already explains how to set ports in case the user messes up the default config file

Expanded the config file section above.

### 2. Build your custom image

For example, from the n8n repository root:
Expand Down