N8n Code Python

Python Code Node (Beta)

Expert guidance for writing Python code in n8n Code nodes.

When to use

• Writing or reviewing a Python Code node in n8n.
• Using _input / _json / _node syntax.
• Selecting between Python (Beta) and Python (Native).
• Understanding what is and is not available in the n8n Python runtime.
• Switching between Python and JavaScript Code nodes.
• Debugging ModuleNotFoundError, KeyError, or empty-output issues.

Required input contract

Before writing or reviewing a Python Code node, identify:

• Mode — "Run Once for All Items" (default, 95% of cases) vs "Run Once for Each Item".
• Runtime — Python (Beta, recommended) vs Python (Native, Beta).
• Upstream node(s) — which provides the input; webhook, HTTP, manual, or another Code node.
• Required output cardinality — single, list, empty, or filtered.
• Reason for Python over JavaScript — Python is justified only by stdlib needs, comfort, or list-comprehension fit.

JavaScript first

Use JavaScript for 95% of use cases. Choose Python only when:

• You need a specific stdlib module (e.g., statistics).
• You are significantly more comfortable in Python.
• The transform maps cleanly to Python idioms.

JavaScript advantages: full $helpers (incl. $helpers.httpRequest()), Luxon DateTime, no external-library limit, better n8n documentation.

n8n Python Code node constraints

These constraints apply to every Python Code node and must always be respected.

1. No external libraries. requests, pandas, numpy, bs4, lxml, httpx, etc. produce ModuleNotFoundError. Standard library only.
2. Available stdlib: json, datetime, re, base64, hashlib, urllib.parse, math, random, statistics.
3. Return shape: every code path returns a list of dicts each with a "json" key. Single returns are wrapped in a list. Empty result is return [].
4. Webhook data nests under ["body"]. Use _json.get("body", {}).get(...).
5. Dictionary access uses .get() — fields may be missing.
6. HTTP requests cannot originate inside the Code node. Use the HTTP Request node upstream, or switch to JavaScript.
7. Beta and Native runtimes have different variables (_input/_json/_node vs _items/_item). Do not mix them.

Workflow (compact)

1. Language: JavaScript first; Python only when justified.
2. Mode: All Items (default) vs Each Item.
3. Runtime: Beta (recommended) vs Native.
4. Read: _input.all() / .first() / .item / _node["..."]["json"].
5. Transform: stdlib only; list comprehensions preferred.
6. Return: [{"json": {...}}, ...] on every code path.
7. Validate: walk the validation-gates checklist (below).

Full workflow + mode and runtime examples: references/python-code-workflow.md.

Decision logic

Mode selection

Runtime selection

Data access

Python vs JavaScript

Minimal critical examples

Quick Start

from datetime import datetime

items = _input.all()
return [
    {"json": {**it["json"], "processed": True, "ts": datetime.now().isoformat()}}
    for it in items
]

Webhook field access

data = _json.get("body", {})
name = data.get("name", "")
return [{"json": {"name": name.strip()}}]

Return-format right/wrong

return [{"json": {"id": 1}}]   # RIGHT — single item
return [{"json": {"id": 1}}, {"json": {"id": 2}}]  # RIGHT — multiple
return []                       # RIGHT — empty
return {"json": {"id": 1}}      # WRONG — dict not wrapped
return [{"id": 1}]              # WRONG — missing "json" key

Worked end-to-end examples (webhook, aggregation, multi-node merge, regex extract, checksum, per-item conditional): references/examples.md.

Validation gates

Before deploying a Python Code node:

• Considered JavaScript first — Python is the right choice.
• Code is not empty.
• Final return statement exists.
• Return shape is [{"json": {...}}, ...] on every code path.
• Data access uses only _input.all() / _input.first() / _input.item / _node["..."]["json"].
• No external library imports — stdlib only.
• .get(key, default) everywhere for dictionary access.
• Webhook data accessed via _json.get("body", {}).
• Mode is "All Items" unless per-item independence is required.
• Output is consistent across every branch and exception path.

Full top-5-mistakes catalog, best practices, debugging playbook, anti-patterns: references/validation-troubleshooting-and-antipatterns.md.

Output expectations

When delivering a Python Code node:

• Provide the full code block, ready to paste into the Code node.
• State the mode (All Items / Each Item) and runtime (Beta / Native).
• Note any required upstream nodes (HTTP Request, Webhook, etc.).
• List required stdlib imports at the top.
• Flag any branch that returns [] and what that means downstream.

Integration with other skills

• n8n Expression Syntax — expressions use {{ }} in other nodes; Code nodes use Python directly, no {{ }}.
• n8n MCP Tools Expert — find Code node via search_nodes({query: "code"}); configure via get_node({nodeType: "nodes-base.code"}); validate via validate_node({nodeType: "nodes-base.code", config: {...}}).
• n8n Node Configuration — mode and language selection are node properties.
• n8n Validation Expert — interpret validation errors, auto-fix issues.
• n8n Code JavaScript — when to switch; feature comparison.

Reference map