n8n-code-python

Python コードノード（ベータ版）

n8n のコードノードで Python コードを書くための専門的なガイダンスです。

---

⚠️ 重要：まずは JavaScript を使いましょう

推奨：ユースケースの 95% では JavaScript を使用してください。Python を使うのは、次の場合に限ります。

• 特定の Python 標準ライブラリ関数が必要な場合
• Python の構文のほうが大幅に使い慣れている場合
• Python に適したデータ変換を行う場合

JavaScript が推奨される理由：

• n8n のヘルパー関数をすべて利用できます（this.helpers.httpRequest など）
• 高度な日付・時刻操作に使える Luxon DateTime ライブラリ
• 外部ライブラリの制限がありません
• n8n のドキュメントやコミュニティのサポートが充実しています

---

クイックスタート

# 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

必須ルール

1. まず JavaScript を検討してください — 必要な場合にのみ Python を使います
2. データへのアクセス：_input.all()、_input.first()、または _input.item
3. 重要：[{"json": {...}}] 形式で返す必要があります
4. 重要：Webhook データは _json 直下ではなく、_json["body"] の下にあります
5. 重大な制限：外部ライブラリは使用できません（requests、pandas、numpy など）
6. 標準ライブラリのみ使用可能：json、datetime、re、base64、hashlib、urllib.parse、math、random、statistics

---

モード選択ガイド

JavaScript と同様に、ユースケースに応じて選択します。

すべてのアイテムに対して一度実行（推奨・デフォルト）

このモードを使うケース： ユースケースの 95%

• 動作：入力数に関係なく、コードを一度だけ実行します
• データアクセス：_input.all() または _items 配列（Native モード）
• 最適な用途：集計、フィルタリング、バッチ処理、変換
• パフォーマンス：複数のアイテムを処理する場合に高速（実行は一度だけ）

# 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
    }
}]

各アイテムに対して一度実行

このモードを使うケース： 特殊なケースのみ

• 動作：コードを入力アイテムごとに個別に実行します
• データアクセス：_input.item または _item（Native モード）
• 最適な用途：アイテム固有のロジック、独立した処理、アイテムごとの検証
• パフォーマンス：大規模なデータセットでは低速（複数回実行）

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

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

---

Python モード：ベータ版と Native

n8n には、2 種類の Python 実行モードがあります。

Python（ベータ版）— 推奨

• 使用するもの：_input、_json、_node ヘルパー構文
• 最適な用途：ほとんどの Python ユースケース
• 利用可能なヘルパー：_now、_today、_jmespath()
• インポート：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）（ベータ版）

• 使用するもの：_items、_item 変数のみ
• ヘルパーなし：_input、_now などは使用できません
• 制限が多い：標準 Python のみ
• 使用するケース：n8n ヘルパーを使わず、純粋な Python が必要な場合

# Python (Native) example
processed = []

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

return processed

推奨：n8n との連携に優れた Python（ベータ版） を使用してください。

---

データアクセスパターン

アンダースコアで始まる変数を使って入力データにアクセスします。各アイテムは {"json": {...}} という形の辞書で、実際のフィールドは ["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"]

参照：DATA_ACCESS.md には、詳しいガイドが記載されています。_input.all() を使った 6 つのレシピ（フィルタリング、変換、集計、ソート、グループ化、重複排除）、_input.first() と _input.item の例、複数ノードのデータ結合、JS と Python の変数比較表、判断フローチャートが含まれています。

---

重要：Webhook のデータ構造

最もよくある間違い：Webhook データは ["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")

理由：Webhook ノードは、すべてのリクエストデータを body プロパティの下に格納します。これには、POST データ、クエリパラメーター、JSON ペイロードが含まれます。

参照：Webhook のデータ構造の詳細は、DATA_ACCESS.md をご覧ください。

---

戻り値の形式に関する要件

重要なルール：必ず "json" キーを含む辞書のリストを返してください。

正しい戻り値の形式

# ✅ Single result
return [{
    "json": {
        "field1": value1,
        "field2": value2
    }
}]

# ✅ Multiple results
return [
    {"json": {"id": 1, "data": "first"}},
    {"json": {"id": 2, "data": "second"}}
]

# ✅ List comprehension
transformed = [
    {"json": {"id": item["json"]["id"], "processed": True}}
    for item in _input.all()
    if item["json"].get("valid")
]
return transformed

# ✅ Empty result (when no data to return)
return []

# ✅ Conditional return
if should_process:
    return [{"json": processed_data}]
else:
    return []

正しくない戻り値の形式

# ❌ WRONG: Dictionary without list wrapper
return {
    "json": {"field": value}
}

# ❌ WRONG: List without json wrapper
return [{"field": value}]

# ❌ WRONG: Plain string
return "processed"

# ❌ WRONG: Incomplete structure
return [{"data": value}]  # Should be {"json": value}

重要な理由：後続のノードはリスト形式を想定しています。形式が正しくないと、ワークフローの実行に失敗します。

参照：エラーの詳しい解決方法は、ERROR_PATTERNS.md の #2 をご覧ください。

---

重大な制限事項：外部ライブラリは利用できません

最も重要な Python の制限事項：デフォルトのインストール環境では、外部パッケージをインポートできません。

セルフホスト時の例外：外部パッケージが利用できるかどうかは、インスタンスの Python ランナーの設定に完全に依存します。セルフホストインスタンスの Python ランナー環境で特定のパッケージを利用できるとユーザーが明言した場合は、それらを使用してください。利用を断らないでください。不明な場合は確認するか、標準ライブラリのみを使用するコードを記述してください。

❌ 利用不可（ModuleNotFoundError が発生）：requests、pandas、numpy、scipy、bs4/BeautifulSoup、lxml。

✅ 利用可能（標準ライブラリのみ）：json、datetime、re、base64、hashlib、urllib.parse、math、random、statistics。

回避策

HTTP リクエストが必要ですか？

• ✅ Code ノードの前に HTTP Request ノードを使用します
• ✅ または JavaScript に切り替えて、this.helpers.httpRequest() を使用します（タスクランナーのサンドボックスでは、裸の $helpers グローバルは未定義です）

データ分析（pandas/numpy）が必要ですか？

• ✅ 基本的な統計には Python の statistics モジュールを使用します
• ✅ または、ほとんどの処理では JavaScript に切り替えます
• ✅ リストや辞書を使って手動で計算します

ウェブスクレイピング（BeautifulSoup）が必要ですか？

• ✅ HTTP Request ノードと HTML Extract ノードを使用します
• ✅ または、正規表現や文字列メソッドを使う JavaScript に切り替えます

参照先：STANDARD_LIBRARY.md に完全なリファレンスがあります

---

よく使われるパターンの概要

本番ワークフローでよく使われる Python パターンは次のとおりです。

1. データ変換 - リスト内包表記ですべてのアイテムを変換します
2. フィルタリングと集計 - 組み込み関数で合計、フィルタリング、カウントを行います
3. 正規表現による文字列処理 - re でテキストからパターンを抽出します
4. データ検証 - データを検証・クリーンアップし、エラーリストを付加します
5. 統計分析 - statistics モジュールで平均値、中央値、標準偏差を計算します

5 つすべてのコピーしてすぐ使えるスニペットは、COMMON_PATTERNS.md にあります。また、詳細な本番向けパターンも 10 種類掲載されています（複数ソースの集計、Markdown の解析、JSON の比較、CRM の正規化、辞書検索、上位 N 件のフィルタリングなど）。

---

エラーの予防 - よくある間違いトップ 5

1. 外部ライブラリのインポート（Python 固有）→ import requests は ModuleNotFoundError を発生させます。代わりに HTTP Request ノードまたは JavaScript を使用してください。
2. コードが空、または return がない → すべての処理経路の末尾に return [{"json": ...}] を記述する必要があります。
3. 戻り値の形式が正しくない → リストでラップします：{"json": {...}} は [{"json": {...}}] にします。
4. 辞書へのアクセス時の KeyError → .get() を使用します：_json.get("user", {}).get("name", "Unknown")。
5. Webhook のボディのネスト → ["body"] 経由で読み取ります：_json.get("body", {}).get("email", "no-email")。

参照先：ERROR_PATTERNS.md に包括的なガイドがあります。各エラーの誤ったコードと正しいコード、エラーメッセージ、ネストされた値へのアクセスの修正方法、AttributeError の追加事例、予防チェックリスト、クイック修正表を掲載しています。

---

標準ライブラリのリファレンス

特に便利なモジュール：json（解析・生成）、datetime（日付と timedelta）、re（正規表現）、base64（エンコード・デコード）、hashlib（ハッシュ計算）、urllib.parse（URL 操作）、statistics（平均値・中央値・標準偏差）。ほかにも、math、random、collections、itertools、functools を利用できます。

簡潔なチートシートと、モジュールごとの詳しい例については、STANDARD_LIBRARY.md を参照してください。

---

ベストプラクティス

1. 辞書へのアクセスには必ず .get() を使用する

# ✅ SAFE: Won't crash if field missing
value = item["json"].get("field", "default")

# ❌ RISKY: Crashes if field doesn't exist
value = item["json"]["field"]

2. None/Null 値を明示的に処理する

# ✅ GOOD: Default to 0 if None
amount = item["json"].get("amount") or 0

# ✅ GOOD: Check for None explicitly
text = item["json"].get("text")
if text is None:
    text = ""

3. フィルタリングにはリスト内包表記を使用する

# ✅ PYTHONIC: List comprehension
valid = [item for item in items if item["json"].get("active")]

# ❌ VERBOSE: Manual loop
valid = []
for item in items:
    if item["json"].get("active"):
        valid.append(item)

4. 一貫した構造を返す

# ✅ CONSISTENT: Always list with "json" key
return [{"json": result}]  # Single result
return results  # Multiple results (already formatted)
return []  # No results

5. print() 文でデバッグする

# Debug statements appear in browser console (F12)
items = _input.all()
print(f"Processing {len(items)} items")
print(f"First item: {items[0] if items else 'None'}")

---

本番環境での注意点

SplitInBatches のループの動作

SplitInBatches ノードには 2 つの出力があります。

• main[0] = 完了 — すべてのバッチの処理後に 1 回だけ実行されます
• main[1] = 各バッチ — すべてのバッチで実行されます（ループ本体）

完了出力の後には、必ず Limit 1 ノードを追加してください。

正しいノード参照構文

# ❌ WRONG
data = _node['HTTP Request']['json']

# ✅ CORRECT - call .first() then access json
data = _node['HTTP Request'].first()['json']

Python では反復間のデータを利用できません

$getWorkflowStaticData('global') は Python ベータモードでは利用できない場合があります。SplitInBatches の反復をまたいでデータを蓄積する必要がある場合は、蓄積処理に JavaScript Code ノードを使用してください。

---

Python と JavaScript の使い分け

Python を使う場合：

• ✅ 統計処理に statistics モジュールが必要な場合
• ✅ Python の構文のほうが大幅に使いやすい場合
• ✅ 処理がリスト内包表記に適している場合
• ✅ 標準ライブラリの特定の関数が必要な場合

JavaScript を使う場合：

• ✅ HTTP リクエスト（this.helpers.httpRequest()）が必要な場合
• ✅ 高度な日付／時刻処理（DateTime／Luxon）が必要な場合
• ✅ n8n との連携を強化したい場合
• ✅ ユースケースの 95% で使用する場合（推奨）

他のノードを検討する場合：

• ❌ 簡単なフィールドマッピング → Set ノードを使用
• ❌ 基本的なフィルタリング → Filter ノードを使用
• ❌ 簡単な条件分岐 → IF または Switch ノードを使用
• ❌ HTTP リクエストのみ → HTTP Request ノードを使用

---

他のスキルとの連携

連携するスキル：

n8n Expression Syntax：

• 他のノードでは {{ }} 構文を使用します
• Code ノードでは Python を直接使用します（{{ }} は不要です）
• 式とコードの使い分け

n8n MCP Tools Expert：

• Code ノードの検索方法：search_nodes({query: "code"})
• 設定のヘルプの取得：get_node({nodeType: "nodes-base.code"})
• コードの検証：validate_node({nodeType: "nodes-base.code", config: {...}})

n8n Node Configuration：

• モードの選択（All Items と Each Item）
• 言語の選択（Python と JavaScript）
• プロパティ間の依存関係の理解

n8n Workflow Patterns：

• 変換ステップでの Code ノードの使用
• パターン内で Python と JavaScript を使い分ける方法

n8n Validation Expert：

• Code ノード設定の検証
• 検証エラーへの対処
• よくある問題の自動修正

n8n Code JavaScript：

• 代わりに JavaScript を使う場合
• JavaScript と Python の機能の比較
• Python から JavaScript への移行

---

クイックリファレンスチェックリスト

Python Code ノードをデプロイする前に、次の項目を確認してください。

• まず JavaScript を検討した - 必要な場合にのみ Python を使用する
• コードが空ではない - 意味のあるロジックが必要です
• return 文がある - 辞書のリストを返す必要があります
• 戻り値の形式が正しい - 各項目：{"json": {...}}
• データアクセスが正しい - _input.all()、_input.first()、または _input.item を使用している
• 外部インポートがない - 標準ライブラリ（json、datetime、re など）のみを使用する
• 辞書へのアクセスが安全 - KeyError を避けるために .get() を使用する
• Webhook データ - Webhook 由来の場合は ["body"] からアクセスする
• モードを選択した - ほとんどの場合は「All Items」
• 出力に一貫性がある - すべてのコードパスで同じ構造を返す

---

追加リソース

関連ファイル

• DATA_ACCESS.md - Python のデータアクセスパターンの詳細
• COMMON_PATTERNS.md - n8n で使える Python パターン 10 選
• ERROR_PATTERNS.md - よくあるエラー上位 5 件と解決方法
• STANDARD_LIBRARY.md - 標準ライブラリの完全リファレンス

n8n ドキュメント

• Code Node Guide: https://docs.n8n.io/code/code-node/
• Python in n8n: https://docs.n8n.io/code/builtin/python-modules/

---

n8n Code ノードで Python を使う準備はできました。ただし、まず JavaScript を検討してください！ 特定のニーズには Python を使い、よくある間違いを避けるためにエラーパターンガイドを参照し、標準ライブラリを効果的に活用してください。