N8n Code Python

1---
2name: n8n-code-python
3description: 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.
4---
5 
6# Python Code Node (Beta)
7 
8Expert guidance for writing Python code in n8n Code nodes.
9 
10---
11 
12## ⚠️ Important: JavaScript First
13 
14**Recommendation**: Use **JavaScript for 95% of use cases**. Only use Python when:
15- You need specific Python standard library functions
16- You're significantly more comfortable with Python syntax
17- You're doing data transformations better suited to Python
18 
19**Why JavaScript is preferred:**
20- Full n8n helper functions ($helpers.httpRequest, etc.)
21- Luxon DateTime library for advanced date/time operations
22- No external library limitations
23- Better n8n documentation and community support
24 
25---
26 
27## Quick Start
28 
29```python
30# Basic template for Python Code nodes
31items = _input.all()
32 
33# Process data
34processed = []
35for item in items:
36    processed.append({
37        "json": {
38            **item["json"],
39            "processed": True,
40            "timestamp": datetime.now().isoformat()
41        }
42    })
43 
44return processed
45```
46 
47### Essential Rules
48 
491. **Consider JavaScript first** - Use Python only when necessary
502. **Access data**: `_input.all()`, `_input.first()`, or `_input.item`
513. **CRITICAL**: Must return `[{"json": {...}}]` format
524. **CRITICAL**: Webhook data is under `_json["body"]` (not `_json` directly)
535. **CRITICAL LIMITATION**: **No external libraries** (no requests, pandas, numpy)
546. **Standard library only**: json, datetime, re, base64, hashlib, urllib.parse, math, random, statistics
55 
56---
57 
58## Mode Selection Guide
59 
60Same as JavaScript - choose based on your use case:
61 
62### Run Once for All Items (Recommended - Default)
63 
64**Use this mode for:** 95% of use cases
65 
66- **How it works**: Code executes **once** regardless of input count
67- **Data access**: `_input.all()` or `_items` array (Native mode)
68- **Best for**: Aggregation, filtering, batch processing, transformations
69- **Performance**: Faster for multiple items (single execution)
70 
71```python
72# Example: Calculate total from all items
73all_items = _input.all()
74total = sum(item["json"].get("amount", 0) for item in all_items)
75 
76return [{
77    "json": {
78        "total": total,
79        "count": len(all_items),
80        "average": total / len(all_items) if all_items else 0
81    }
82}]
83```
84 
85### Run Once for Each Item
86 
87**Use this mode for:** Specialized cases only
88 
89- **How it works**: Code executes **separately** for each input item
90- **Data access**: `_input.item` or `_item` (Native mode)
91- **Best for**: Item-specific logic, independent operations, per-item validation
92- **Performance**: Slower for large datasets (multiple executions)
93 
94```python
95# Example: Add processing timestamp to each item
96item = _input.item
97 
98return [{
99    "json": {
100        **item["json"],
101        "processed": True,
102        "processed_at": datetime.now().isoformat()
103    }
104}]
105```
106 
107---
108 
109## Python Modes: Beta vs Native
110 
111n8n offers two Python execution modes:
112 
113### Python (Beta) - Recommended
114- **Use**: `_input`, `_json`, `_node` helper syntax
115- **Best for**: Most Python use cases
116- **Helpers available**: `_now`, `_today`, `_jmespath()`
117- **Import**: `from datetime import datetime`
118 
119```python
120# Python (Beta) example
121items = _input.all()
122now = _now  # Built-in datetime object
123 
124return [{
125    "json": {
126        "count": len(items),
127        "timestamp": now.isoformat()
128    }
129}]
130```
131 
132### Python (Native) (Beta)
133- **Use**: `_items`, `_item` variables only
134- **No helpers**: No `_input`, `_now`, etc.
135- **More limited**: Standard Python only
136- **Use when**: Need pure Python without n8n helpers
137 
138```python
139# Python (Native) example
140processed = []
141 
142for item in _items:
143    processed.append({
144        "json": {
145            "id": item["json"].get("id"),
146            "processed": True
147        }
148    })
149 
150return processed
151```
152 
153**Recommendation**: Use **Python (Beta)** for better n8n integration.
154 
155---
156 
157## Data Access Patterns
158 
159### Pattern 1: _input.all() - Most Common
160 
161**Use when**: Processing arrays, batch operations, aggregations
162 
163```python
164# Get all items from previous node
165all_items = _input.all()
166 
167# Filter, transform as needed
168valid = [item for item in all_items if item["json"].get("status") == "active"]
169 
170processed = []
171for item in valid:
172    processed.append({
173        "json": {
174            "id": item["json"]["id"],
175            "name": item["json"]["name"]
176        }
177    })
178 
179return processed
180```
181 
182### Pattern 2: _input.first() - Very Common
183 
184**Use when**: Working with single objects, API responses
185 
186```python
187# Get first item only
188first_item = _input.first()
189data = first_item["json"]
190 
191return [{
192    "json": {
193        "result": process_data(data),
194        "processed_at": datetime.now().isoformat()
195    }
196}]
197```
198 
199### Pattern 3: _input.item - Each Item Mode Only
200 
201**Use when**: In "Run Once for Each Item" mode
202 
203```python
204# Current item in loop (Each Item mode only)
205current_item = _input.item
206 
207return [{
208    "json": {
209        **current_item["json"],
210        "item_processed": True
211    }
212}]
213```
214 
215### Pattern 4: _node - Reference Other Nodes
216 
217**Use when**: Need data from specific nodes in workflow
218 
219```python
220# Get output from specific node
221webhook_data = _node["Webhook"]["json"]
222http_data = _node["HTTP Request"]["json"]
223 
224return [{
225    "json": {
226        "combined": {
227            "webhook": webhook_data,
228            "api": http_data
229        }
230    }
231}]
232```
233 
234**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for comprehensive guide
235 
236---
237 
238## Critical: Webhook Data Structure
239 
240**MOST COMMON MISTAKE**: Webhook data is nested under `["body"]`
241 
242```python
243# ❌ WRONG - Will raise KeyError
244name = _json["name"]
245email = _json["email"]
246 
247# ✅ CORRECT - Webhook data is under ["body"]
248name = _json["body"]["name"]
249email = _json["body"]["email"]
250 
251# ✅ SAFER - Use .get() for safe access
252webhook_data = _json.get("body", {})
253name = webhook_data.get("name")
254```
255 
256**Why**: Webhook node wraps all request data under `body` property. This includes POST data, query parameters, and JSON payloads.
257 
258**See**: [DATA_ACCESS.md](DATA_ACCESS.md) for full webhook structure details
259 
260---
261 
262## Return Format Requirements
263 
264**CRITICAL RULE**: Always return list of dictionaries with `"json"` key
265 
266### Correct Return Formats
267 
268```python
269# ✅ Single result
270return [{
271    "json": {
272        "field1": value1,
273        "field2": value2
274    }
275}]
276 
277# ✅ Multiple results
278return [
279    {"json": {"id": 1, "data": "first"}},
280    {"json": {"id": 2, "data": "second"}}
281]
282 
283# ✅ List comprehension
284transformed = [
285    {"json": {"id": item["json"]["id"], "processed": True}}
286    for item in _input.all()
287    if item["json"].get("valid")
288]
289return transformed
290 
291# ✅ Empty result (when no data to return)
292return []
293 
294# ✅ Conditional return
295if should_process:
296    return [{"json": processed_data}]
297else:
298    return []
299```
300 
301### Incorrect Return Formats
302 
303```python
304# ❌ WRONG: Dictionary without list wrapper
305return {
306    "json": {"field": value}
307}
308 
309# ❌ WRONG: List without json wrapper
310return [{"field": value}]
311 
312# ❌ WRONG: Plain string
313return "processed"
314 
315# ❌ WRONG: Incomplete structure
316return [{"data": value}]  # Should be {"json": value}
317```
318 
319**Why it matters**: Next nodes expect list format. Incorrect format causes workflow execution to fail.
320 
321**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) #2 for detailed error solutions
322 
323---
324 
325## Critical Limitation: No External Libraries
326 
327**MOST IMPORTANT PYTHON LIMITATION**: Cannot import external packages
328 
329### What's NOT Available
330 
331```python
332# ❌ NOT AVAILABLE - Will raise ModuleNotFoundError
333import requests  # ❌ No
334import pandas  # ❌ No
335import numpy  # ❌ No
336import scipy  # ❌ No
337from bs4 import BeautifulSoup  # ❌ No
338import lxml  # ❌ No
339```
340 
341### What IS Available (Standard Library)
342 
343```python
344# ✅ AVAILABLE - Standard library only
345import json  # ✅ JSON parsing
346import datetime  # ✅ Date/time operations
347import re  # ✅ Regular expressions
348import base64  # ✅ Base64 encoding/decoding
349import hashlib  # ✅ Hashing functions
350import urllib.parse  # ✅ URL parsing
351import math  # ✅ Math functions
352import random  # ✅ Random numbers
353import statistics  # ✅ Statistical functions
354```
355 
356### Workarounds
357 
358**Need HTTP requests?**
359- ✅ Use **HTTP Request node** before Code node
360- ✅ Or switch to **JavaScript** and use `$helpers.httpRequest()`
361 
362**Need data analysis (pandas/numpy)?**
363- ✅ Use Python **statistics** module for basic stats
364- ✅ Or switch to **JavaScript** for most operations
365- ✅ Manual calculations with lists and dictionaries
366 
367**Need web scraping (BeautifulSoup)?**
368- ✅ Use **HTTP Request node** + **HTML Extract node**
369- ✅ Or switch to **JavaScript** with regex/string methods
370 
371**See**: [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) for complete reference
372 
373---
374 
375## Common Patterns Overview
376 
377Based on production workflows, here are the most useful Python patterns:
378 
379### 1. Data Transformation
380Transform all items with list comprehensions
381 
382```python
383items = _input.all()
384 
385return [
386    {
387        "json": {
388            "id": item["json"].get("id"),
389            "name": item["json"].get("name", "Unknown").upper(),
390            "processed": True
391        }
392    }
393    for item in items
394]
395```
396 
397### 2. Filtering & Aggregation
398Sum, filter, count with built-in functions
399 
400```python
401items = _input.all()
402total = sum(item["json"].get("amount", 0) for item in items)
403valid_items = [item for item in items if item["json"].get("amount", 0) > 0]
404 
405return [{
406    "json": {
407        "total": total,
408        "count": len(valid_items)
409    }
410}]
411```
412 
413### 3. String Processing with Regex
414Extract patterns from text
415 
416```python
417import re
418 
419items = _input.all()
420email_pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
421 
422all_emails = []
423for item in items:
424    text = item["json"].get("text", "")
425    emails = re.findall(email_pattern, text)
426    all_emails.extend(emails)
427 
428# Remove duplicates
429unique_emails = list(set(all_emails))
430 
431return [{
432    "json": {
433        "emails": unique_emails,
434        "count": len(unique_emails)
435    }
436}]
437```
438 
439### 4. Data Validation
440Validate and clean data
441 
442```python
443items = _input.all()
444validated = []
445 
446for item in items:
447    data = item["json"]
448    errors = []
449 
450    # Validate fields
451    if not data.get("email"):
452        errors.append("Email required")
453    if not data.get("name"):
454        errors.append("Name required")
455 
456    validated.append({
457        "json": {
458            **data,
459            "valid": len(errors) == 0,
460            "errors": errors if errors else None
461        }
462    })
463 
464return validated
465```
466 
467### 5. Statistical Analysis
468Calculate statistics with statistics module
469 
470```python
471from statistics import mean, median, stdev
472 
473items = _input.all()
474values = [item["json"].get("value", 0) for item in items if "value" in item["json"]]
475 
476if values:
477    return [{
478        "json": {
479            "mean": mean(values),
480            "median": median(values),
481            "stdev": stdev(values) if len(values) > 1 else 0,
482            "min": min(values),
483            "max": max(values),
484            "count": len(values)
485        }
486    }]
487else:
488    return [{"json": {"error": "No values found"}}]
489```
490 
491**See**: [COMMON_PATTERNS.md](COMMON_PATTERNS.md) for 10 detailed Python patterns
492 
493---
494 
495## Error Prevention - Top 5 Mistakes
496 
497### #1: Importing External Libraries (Python-Specific!)
498 
499```python
500# ❌ WRONG: Trying to import external library
501import requests  # ModuleNotFoundError!
502 
503# ✅ CORRECT: Use HTTP Request node or JavaScript
504# Add HTTP Request node before Code node
505# OR switch to JavaScript and use $helpers.httpRequest()
506```
507 
508### #2: Empty Code or Missing Return
509 
510```python
511# ❌ WRONG: No return statement
512items = _input.all()
513# Processing...
514# Forgot to return!
515 
516# ✅ CORRECT: Always return data
517items = _input.all()
518# Processing...
519return [{"json": item["json"]} for item in items]
520```
521 
522### #3: Incorrect Return Format
523 
524```python
525# ❌ WRONG: Returning dict instead of list
526return {"json": {"result": "success"}}
527 
528# ✅ CORRECT: List wrapper required
529return [{"json": {"result": "success"}}]
530```
531 
532### #4: KeyError on Dictionary Access
533 
534```python
535# ❌ WRONG: Direct access crashes if missing
536name = _json["user"]["name"]  # KeyError!
537 
538# ✅ CORRECT: Use .get() for safe access
539name = _json.get("user", {}).get("name", "Unknown")
540```
541 
542### #5: Webhook Body Nesting
543 
544```python
545# ❌ WRONG: Direct access to webhook data
546email = _json["email"]  # KeyError!
547 
548# ✅ CORRECT: Webhook data under ["body"]
549email = _json["body"]["email"]
550 
551# ✅ BETTER: Safe access with .get()
552email = _json.get("body", {}).get("email", "no-email")
553```
554 
555**See**: [ERROR_PATTERNS.md](ERROR_PATTERNS.md) for comprehensive error guide
556 
557---
558 
559## Standard Library Reference
560 
561### Most Useful Modules
562 
563```python
564# JSON operations
565import json
566data = json.loads(json_string)
567json_output = json.dumps({"key": "value"})
568 
569# Date/time
570from datetime import datetime, timedelta
571now = datetime.now()
572tomorrow = now + timedelta(days=1)
573formatted = now.strftime("%Y-%m-%d")
574 
575# Regular expressions
576import re
577matches = re.findall(r'\d+', text)
578cleaned = re.sub(r'[^\w\s]', '', text)
579 
580# Base64 encoding
581import base64
582encoded = base64.b64encode(data).decode()
583decoded = base64.b64decode(encoded)
584 
585# Hashing
586import hashlib
587hash_value = hashlib.sha256(text.encode()).hexdigest()
588 
589# URL parsing
590import urllib.parse
591params = urllib.parse.urlencode({"key": "value"})
592parsed = urllib.parse.urlparse(url)
593 
594# Statistics
595from statistics import mean, median, stdev
596average = mean([1, 2, 3, 4, 5])
597```
598 
599**See**: [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) for complete reference
600 
601---
602 
603## Best Practices
604 
605### 1. Always Use .get() for Dictionary Access
606 
607```python
608# ✅ SAFE: Won't crash if field missing
609value = item["json"].get("field", "default")
610 
611# ❌ RISKY: Crashes if field doesn't exist
612value = item["json"]["field"]
613```
614 
615### 2. Handle None/Null Values Explicitly
616 
617```python
618# ✅ GOOD: Default to 0 if None
619amount = item["json"].get("amount") or 0
620 
621# ✅ GOOD: Check for None explicitly
622text = item["json"].get("text")
623if text is None:
624    text = ""
625```
626 
627### 3. Use List Comprehensions for Filtering
628 
629```python
630# ✅ PYTHONIC: List comprehension
631valid = [item for item in items if item["json"].get("active")]
632 
633# ❌ VERBOSE: Manual loop
634valid = []
635for item in items:
636    if item["json"].get("active"):
637        valid.append(item)
638```
639 
640### 4. Return Consistent Structure
641 
642```python
643# ✅ CONSISTENT: Always list with "json" key
644return [{"json": result}]  # Single result
645return results  # Multiple results (already formatted)
646return []  # No results
647```
648 
649### 5. Debug with print() Statements
650 
651```python
652# Debug statements appear in browser console (F12)
653items = _input.all()
654print(f"Processing {len(items)} items")
655print(f"First item: {items[0] if items else 'None'}")
656```
657 
658---
659 
660## When to Use Python vs JavaScript
661 
662### Use Python When:
663- ✅ You need `statistics` module for statistical operations
664- ✅ You're significantly more comfortable with Python syntax
665- ✅ Your logic maps well to list comprehensions
666- ✅ You need specific standard library functions
667 
668### Use JavaScript When:
669- ✅ You need HTTP requests ($helpers.httpRequest())
670- ✅ You need advanced date/time (DateTime/Luxon)
671- ✅ You want better n8n integration
672- ✅ **For 95% of use cases** (recommended)
673 
674### Consider Other Nodes When:
675- ❌ Simple field mapping → Use **Set** node
676- ❌ Basic filtering → Use **Filter** node
677- ❌ Simple conditionals → Use **IF** or **Switch** node
678- ❌ HTTP requests only → Use **HTTP Request** node
679 
680---
681 
682## Integration with Other Skills
683 
684### Works With:
685 
686**n8n Expression Syntax**:
687- Expressions use `{{ }}` syntax in other nodes
688- Code nodes use Python directly (no `{{ }}`)
689- When to use expressions vs code
690 
691**n8n MCP Tools Expert**:
692- How to find Code node: `search_nodes({query: "code"})`
693- Get configuration help: `get_node_essentials("nodes-base.code")`
694- Validate code: `validate_node_operation()`
695 
696**n8n Node Configuration**:
697- Mode selection (All Items vs Each Item)
698- Language selection (Python vs JavaScript)
699- Understanding property dependencies
700 
701**n8n Workflow Patterns**:
702- Code nodes in transformation step
703- When to use Python vs JavaScript in patterns
704 
705**n8n Validation Expert**:
706- Validate Code node configuration
707- Handle validation errors
708- Auto-fix common issues
709 
710**n8n Code JavaScript**:
711- When to use JavaScript instead
712- Comparison of JavaScript vs Python features
713- Migration from Python to JavaScript
714 
715---
716 
717## Quick Reference Checklist
718 
719Before deploying Python Code nodes, verify:
720 
721- [ ] **Considered JavaScript first** - Using Python only when necessary
722- [ ] **Code is not empty** - Must have meaningful logic
723- [ ] **Return statement exists** - Must return list of dictionaries
724- [ ] **Proper return format** - Each item: `{"json": {...}}`
725- [ ] **Data access correct** - Using `_input.all()`, `_input.first()`, or `_input.item`
726- [ ] **No external imports** - Only standard library (json, datetime, re, etc.)
727- [ ] **Safe dictionary access** - Using `.get()` to avoid KeyError
728- [ ] **Webhook data** - Access via `["body"]` if from webhook
729- [ ] **Mode selection** - "All Items" for most cases
730- [ ] **Output consistent** - All code paths return same structure
731 
732---
733 
734## Additional Resources
735 
736### Related Files
737- [DATA_ACCESS.md](DATA_ACCESS.md) - Comprehensive Python data access patterns
738- [COMMON_PATTERNS.md](COMMON_PATTERNS.md) - 10 Python patterns for n8n
739- [ERROR_PATTERNS.md](ERROR_PATTERNS.md) - Top 5 errors and solutions
740- [STANDARD_LIBRARY.md](STANDARD_LIBRARY.md) - Complete standard library reference
741 
742### n8n Documentation
743- Code Node Guide: https://docs.n8n.io/code/code-node/
744- Python in n8n: https://docs.n8n.io/code/builtin/python-modules/
745 
746---
747 
748**Ready to write Python in n8n Code nodes - but consider JavaScript first!** Use Python for specific needs, reference the error patterns guide to avoid common mistakes, and leverage the standard library effectively.
749