n8nでPythonを使う！公式Task Runnerを導入する方法

2026-07-17

Dockerなどのコンテナ環境を用いてn8nを構築した場合、初期状態のまま「Codeノード」でPythonを実行しようとすると、システムエラーが発生します。具体的には、画面上やログに以下のメッセージが表示され、処理が中断されます。

Python runner unavailable: Python 3 is missing from this system
Internal mode is intended only for debugging. For production, deploy in external mode: https://docs.n8n.io/hosting/configuration/task-runners/#setting-up-external-mode

これは、n8nの標準コンテナイメージにPythonの実行環境（ランタイム）が同梱されていないために発生する現象です。

既存データを維持しつつ公式コンテナへ移行する方針

本記事の目的は、すでに運用中のn8n環境において、これまで蓄積された設定やワークフローのデータを完全に維持したまま、Pythonコードが正常に実行できる環境を構築することです。目標として、外部の専用コンテナを連携させる「External mode（外部モード）」を導入し、n8n本体のバージョンアップ時にも運用の手間が変わらない、保守性の高いDocker Compose環境の完成を目指します。

よくある躓きポイント：通信拒否と環境変数の罠

外部モードに移行する際、単にTask Runnerコンテナを追加するだけでは連携に失敗します。これには2つの大きな原因があります。

1つ目は、n8n本体に内蔵されている通信窓口（Task Broker）のセキュリティ制限です。初期状態ではコンテナ自身（127.0.0.1）からのアクセスしか許可していないため、外部ネットワークからの接続を受け付けるよう明示的な設定変更が必要です。
2つ目は、近年のバージョンアップデートに伴う仕様変更です。過去の古い解説記事に記載されている環境変数（N8N_RUNNERS_ENABLEDなど）は現在非推奨となっており、これらを使用すると正常にコンテナ間連携が行われません。最新の仕様に準拠した正しい変数名と、通信のバインド設定を行うことが不可欠です。

docker-compose.ymlの具体的な修正と環境変数設定

既存のデータを残したまま環境を移行するには、docker-compose.yml を以下のように修正します。データの保存先である volumes の記述（./n8n_data）はそのまま維持するため、過去の設定や作成済みのワークフローはすべて引き継がれます。

変更前：

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - NODE_ENV=production
      - WEBHOOK_URL=http://localhost:5678/ # 外部公開する場合はドメインを指定
      - GENERIC_TIMEZONE=Asia/Tokyo
      - N8N_SECURE_COOKIE=false
    volumes:
      - ./n8n_data:/home/node/.n8n

変更後：

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - NODE_ENV=production
      - WEBHOOK_URL=http://localhost:5678/
      - GENERIC_TIMEZONE=Asia/Tokyo
      - N8N_SECURE_COOKIE=false
      # 【修正】最新版でのTask Runner外部モード指定
      - N8N_RUNNERS_MODE=external
      # 【修正】Brokerの待受アドレスをすべてのネットワーク(0.0.0.0)に開放
      - N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0
      # 本体とRunner間の認証トークン（任意の文字列を設定）
      - N8N_RUNNERS_AUTH_TOKEN=my-secure-runner-token-2026
    volumes:
      - ./n8n_data:/home/node/.n8n

  n8n-runner:
    image: n8nio/runners:latest
    container_name: n8n-runner
    restart: always
    environment:
      # 【修正】正しい環境変数名でn8n本体のコンテナ名とポートを指定
      - N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679
      # 本体と同じ認証トークンを設定
      - N8N_RUNNERS_AUTH_TOKEN=my-secure-runner-token-2026
      # 使用を許可するPythonの標準ライブラリ（カンマ区切り）
      - N8N_RUNNERS_STDLIB_ALLOW=json,math,datetime
    depends_on:
      - n8n

コンテナの再起動とCodeノードの動作検証

設定ファイルの修正が完了したら、コンテナを再生成して設定を反映させます。以下のコマンドを実行し、古いコンテナを削除した上で、新しい公式イメージとTask Runnerをバックグラウンドで起動します。

docker compose down
docker compose up -d

起動後、n8nの管理画面にアクセスし、既存のワークフローがそのまま残っていることを確認してください。
次に、新しく「Code」ノードを配置し、Language（言語設定）を「Python」に変更します。Modeは「Run Once for All Items」を選択し、デフォルトで記載されている状態のまま「Execute step」をクリックします。

# Loop over input items and add a new field called 'my_new_field' to the JSON of each one
for item in _items:
item["json"]["my_new_field"] = 1
return _items

エラーが出ずにJSON形式の"my_new_field": 1結果が返ってくれば、Task Runnerとの連携は成功です。なお、セキュリティの制限により、標準ライブラリ（jsonやmathなど）を使用する場合は、環境変数 N8N_RUNNERS_STDLIB_ALLOW に明示的にライブラリ名を記述する必要がある点に留意してください。詳細な仕様は公式ドキュメントを参照してください。

まとめ

コンテナ版n8nでPythonが利用できない課題に対し、既存データを保持したまま公式のTask Runnerコンテナを導入して解決しました。独自ビルドを排除し、環境変数による制御と内蔵Brokerを介した外部モード（External mode）へ移行したことで、アップデートへの追従性と安全性が向上しました。検証の結果、現在のCodeノードでのPython実行が正常に機能することを確認しました。

サーバ＆テクノロジdocker,docker-compose,HTTPS,JSON,n8n,python

Posted by 納戸工房

Home