n8n에서 Python을 쓸 때는
코드보다 실행 환경부터 봅니다

먼저 Python이 필요한 이유를 한 줄로 적습니다

리스트 정리, 문자열 변환, 간단한 계산이라면 JavaScript와 Python 모두 가능합니다. 팀이 Python 문법에 익숙하거나 기존 계산 로직을 옮겨야 할 때 Python이 자연스럽습니다. 반대로 n8n의 내장 변수와 노드 생태계를 폭넓게 쓰고 싶거나 처리 속도가 중요한 단순 변환이라면 기본 언어인 JavaScript가 더 수월할 수 있습니다.

실행 모드에 따라 입력과 반환 모양이 달라집니다

Run Once for All Items는 입력 아이템 수와 관계없이 코드를 한 번 실행합니다. 여러 행을 묶어 정렬하거나 합계를 계산할 때 알맞고 Native Python에서는 _items로 전체 입력을 받습니다. Run Once for Each Item은 입력마다 코드를 실행하며 _item을 사용합니다.

n8n 아이템은 보통 {"json": {...}} 형태입니다. Native Python에서는 item["json"]["name"]처럼 대괄호로 접근합니다. item.json.name 같은 점 표기법은 Pyodide 예제와 혼동하기 쉬운 부분입니다.

아이템 수나 순서를 바꾸면 item linking도 확인해야 합니다. 이전 노드의 어느 입력에서 결과가 왔는지 다음 노드가 알아야 하는 흐름에서는 단순히 새 배열만 반환하면 연결 정보가 사라질 수 있습니다. 처음에는 입력과 출력 개수를 유지하는 변환으로 테스트하고, 병합·분할은 공식 데이터 구조 문서의 linking 규칙을 함께 적용하세요.

코드를 쓰기 전에 INPUT 패널에서 구조를 읽습니다

n8n은 노드 사이의 데이터를 객체 하나가 아니라 객체 배열로 전달합니다. 각 아이템의 일반 데이터는 json 키 아래에 있고 파일 같은 바이너리 데이터는 binary 아래에 있습니다. Code 노드에서 값이 보이지 않을 때는 Python 문법보다 이전 노드 출력의 JSON 탭부터 펼쳐보는 편이 빠릅니다.

예를 들어 이전 노드 출력이 {"json":{"customer":{"name":"민지"},"amount":"12000"}}라면 이름은 item["json"]["customer"]["name"]으로 읽습니다. 중첩 키가 항상 온다는 보장이 없다면 바로 대괄호을 이어 쓰지 말고 .get()으로 단계별 기본값을 둡니다. 운영 데이터 한 건의 누락 필드 때문에 전체 묶음이 실패하는 일을 줄일 수 있습니다.

Cloud에서는 Python 라이브러리를 import할 수 없습니다

Cloud의 Python Code 노드에서 pandas나 requests를 import하는 설계는 출발부터 맞지 않습니다. HTTP 호출은 HTTP Request 노드에 맡기고, 파일 처리는 Read/Write Files from Disk 같은 목적별 노드를 검토하세요. 이 편이 인증, 재시도, 실행 기록도 워크플로우 화면에서 확인하기 쉽습니다.

셀프호스팅이라고 Code 노드 안에서 즉시 pip install하면 되는 것도 아닙니다. 공식 문서 기준 Native Python은 task runner에서 실행되며, 필요한 모듈을 runner 이미지에 포함한 뒤 명시적으로 허용해야 합니다. 운영 이미지를 바꿀 때 의존성 버전과 취약점 업데이트까지 관리할 수 있어야 합니다.

운영에서는 Code 노드를 작은 순수 변환으로 둡니다

Code 노드 한 개가 데이터 변환, API 호출, 예외 재시도, 메시지 발송까지 모두 맡으면 실패 원인을 찾기 어렵습니다. ‘입력 정규화 → Code에서 계산 → IF로 분기 → 전용 노드로 외부 작업’처럼 한 단계씩 나누면 실행 이력에서 어느 지점이 문제인지 바로 보입니다.

실패 데이터까지 포함한 테스트 표를 만듭니다

정상 데이터 하나로 성공한 실행은 운영 준비가 끝났다는 뜻이 아닙니다. 금액 필드가 없는 아이템, 빈 문자열, 쉼표가 들어간 숫자, 음수, 예상하지 못한 상태값을 각각 넣어보세요. 처리 정책도 함께 정해야 합니다. 누락 금액을 0으로 바꿀지, validation_error 필드를 붙여 별도 분기로 보낼지에 따라 이후 노드의 행동이 달라집니다.

오류가 난 아이템을 조용히 버리면 워크플로우 실행은 초록색으로 끝나도 실제 업무 데이터가 사라집니다. 반환값에 원본 식별자와 오류 이유를 남기고 IF 노드로 성공·검수 대상을 나누면, 재실행할 때 어느 데이터만 다시 처리해야 하는지 알 수 있습니다.

자주 막히는 오류는 네 가지부터 봅니다

NameError로 _items를 찾지 못합니다.
현재 실행 모드가 Each Item인지 확인하세요. Each Item 모드에서는 _item, All Items 모드에서는 _items를 사용합니다.

ModuleNotFoundError가 납니다.
Cloud에서는 라이브러리 import가 허용되지 않습니다. 셀프호스팅이라면 runner 이미지에 모듈이 설치됐는지와 허용 목록을 함께 봐야 합니다.

반환 뒤 다음 노드에 데이터가 없습니다.
리스트 안의 각 값이 n8n 아이템 구조인지 확인합니다. 계산값 하나만 반환하기보다 return [{"json": {"total": 1000}}]처럼 JSON 객체를 감싼 아이템 배열을 반환합니다.

브라우저나 로컬에서는 되는데 Code 노드에서는 안 됩니다.
Python Code 노드는 임의의 파일시스템 접근과 HTTP 요청을 위한 범용 셸이 아닙니다. 필요한 기능을 제공하는 n8n 노드로 분리하거나, 통제된 외부 서비스에 API로 위임합니다.

첫 워크플로우는 10개 아이템으로 검증합니다

Set 또는 Edit Fields 노드로 이름, 금액, 상태가 담긴 샘플 10개를 만듭니다. Code 노드에서 누락 금액을 0으로 바꾸고 상태를 표준화한 뒤, 다음 노드에서 출력 키와 개수를 확인하세요. 빈 문자열, 숫자처럼 보이는 문자열, 키 자체가 없는 아이템을 하나씩 섞으면 운영 전에 타입 문제를 발견할 수 있습니다.

그다음 실제 입력 복사본으로 실행 시간과 오류를 보고, 마지막에만 외부 쓰기 노드를 연결합니다. 고객 메시지나 삭제처럼 되돌리기 어려운 작업은 수동 승인 분기를 둔 채 충분한 실행 이력이 쌓인 뒤 자동화하는 것이 좋습니다.