/n8n-code-python

name: n8n-code-python
description: Write Python code in n8n Code nodes. Use when writing Python in n8n, using _input/_json/_node syntax, working with standard library, or need to understand Python limitations in n8n Code nodes. Use this skill when the user specifically requests Python for an n8n Code node. Note — JavaScript is recommended for 95% of use cases — only use Python when the user explicitly prefers it or the task requires Python-specific standard library capabilities (regex, hashlib, statistics). EXCEPTION — for Python in the AI-agent-callable Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode), use the n8n-code-tool skill instead (input is _query, return must be a string).

Python Code Node (Beta)

Expert guidance for writing Python code in n8n Code nodes.

---

⚠️ Important: JavaScript First

**Recommendation**: Use **JavaScript for 95% of use cases**. Only use Python when:

• You need specific Python standard library functions
• You're significantly more comfortable with Python syntax
• You're doing data transformations better suited to Python

**Why JavaScript is preferred:**

• Full n8n helper functions (`this.helpers.httpRequest`, etc.)
• Luxon DateTime library for advanced date/time operations
• No external library limitations
• Better n8n documentation and community support

---

Quick Start

# Basic template for Python Code nodes
items = _input.all()

# Process data
processed = []
for item in items:
    processed.append({
        "json": {
            **item["json"],
            "processed": True,
            "timestamp": datetime.now().isoformat()
        }
    })

return processed

Essential Rules

1. **Consider JavaScript first** - Use Python only when necessary 2. **Access data**: `_input.all()`, `_input.first()`, or `_input.item` 3. **CRITICAL**: Must return `[{"json": {...}}]` format 4. **CRITICAL**: Webhook data is under `_json["body"]` (not `_json` directly) 5. **CRITICAL LIMITATION**: **No external libraries** (no requests, pandas, numpy) 6. **Standard library only**: json, datetime, re, base64, hashlib, urllib.parse, math, random, statistics

---

Mode Selection Guide

Same as JavaScript - choose based on your use case:

Run Once for All Items (Recommended - Default)

**Use this mode for:** 95% of use cases

• **How it works**: Code executes **once** regardless of input count
• **Data access**: `_input.all()` or `_items` array (Native mode)
• **Best for**: Aggregation, filtering, batch processing, transformations
• **Performance**: Faster for multiple items (single execution)

# Example: Calculate total from all items
all_items = _input.all()
total = sum(item["json"].get("amount", 0) for item in all_items)

return [{
    "json": {
        "total": total,
        "count": len(all_items),
        "average": total / len(all_items) if all_items else 0
    }
}]

Run Once for Each Item

**Use this mode for:** Specialized cases only

• **How it works**: Code executes **separately** for each input item
• **Data access**: `_input.item` or `_item` (Native mode)
• **Best for**: Item-specific logic, independent operations, per-item validation
• **Performance**: Slower for large datasets (multiple executions)

# Example: Add processing timestamp to each item
item = _input.item

return [{
    "json": {
        **item["json"],
        "processed": True,
        "processed_at": datetime.now().isoformat()
    }
}]

---

Python Modes: Beta vs Native

n8n offers two Python execution modes:

Python (Beta) - Recommended

• **Use**: `_input`, `_json`, `_node` helper syntax
• **Best for**: Most Python use cases
• **Helpers available**: `_now`, `_today`, `_jmespath()`
• **Import**: `from datetime import datetime`

# Python (Beta) example
items = _input.all()
now = _now  # Built-in datetime object

return [{
    "json": {
        "count": len(items),
        "timestamp": now.isoformat()
    }
}]

Python (Native) (Beta)

• **Use**: `_items`, `_item` variables only
• **No helpers**: No `_input`, `_now`, etc.
• **More limited**: Standard Python only
• **Use when**: Need pure Python without n8n helpers

# Python (Native) example
processed = []

for item in _items:
    processed.append({
        "json": {
            "id": item["json"].get("id"),
            "processed": True
        }
    })

return processed

**Recommendation**: Use **Python (Beta)** for better n8n integration.

---

Data Access Patterns

Access input data through underscore-prefixed variables. Each item is a dict shaped `{"json": {...}}`, so the actual fields live under `["json"]`.

# Pattern 1: _input.all() - Most common. Arrays, batch ops, aggregations
all_items = _input.all()            # list of {"json": {...}} dicts

# Pattern 2: _input.first() - Very common. Single objects, API responses
data = _input.first()["json"]       # built-in safety vs all_items[0]

# Pattern 3: _input.item - "Run Once for Each Item" mode ONLY
current = _input.item["json"]       # None/error in All Items mode

# Pattern 4: _node - Reference a specific named node
webhook_data = _node["Webhook"]["json"]
http_data = _node["HTTP Request"]["json"]

**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for the comprehensive guide — six `_input.all()` recipes (filter, transform, aggregate, sort, group, deduplicate), `_input.first()` and `_input.item` examples, multi-node combining, the JS-vs-Python variable table, and the decision tree.

---

Critical: Webhook Data Structure

**MOST COMMON MISTAKE**: Webhook data is nested under `["body"]`

# ❌ WRONG - Will raise KeyError
name = _json["name"]
email = _json["email"]

# ✅ CORRECT - Webhook data is under ["body"]
name = _json["body"]["name"]
email = _json["body"]["email"]

# ✅ SAFER - Use .get() for safe access
webhook_data = _json.get("body", {})
name = webhook_data.get("name")

**Why**: Webhook node wraps all request data under `body` property. This includes POST dat