내보내기는 요청한 항목과 해당 워크플로가 대상 인스턴스에서 필요로 하는 모든 것에 대한 참조를 담은 n8n 패키지, 즉 .n8np 아카이브를 작성합니다. 내보내기는 소스 인스턴스를 수정하지 않습니다.

n8n CLI를 사용합니다.

n8n-cli package export --workflow-id=<workflow-id> --output=triage.n8np

또는 엔드포인트를 직접 호출합니다.

curl -X POST 'https://n8n.example.com/api/v1/n8n-packages/export' \
	-H "X-N8N-API-KEY: <your-api-key>" \
	-H 'Content-Type: application/json' \
	-d '{"workflowIds": ["<workflow-id>"]}' \
	-o triage.n8np

전체 요청 및 응답 스키마는 엔드포인트 참조의 N8nPackage 섹션을 참고하세요.

내보낼 항목 선택#

ID를 하나 이상 전달합니다. 여러 항목을 지정하려면 플래그를 반복합니다. 쉼표로 구분하는 형식은 없습니다.

# Two workflows
n8n-cli package export --workflow-id=wf7Kq2 --workflow-id=wf9Zx1 --output=triage.n8np

# A folder, and everything nested inside it
n8n-cli package export --folder-id=fdInProg --output=in-progress.n8np

# A workflow and a folder together
n8n-cli package export --workflow-id=wf7Kq2 --folder-id=fdInProg --output=mixed.n8np

# Two whole projects
n8n-cli package export --project-id=prTeam9 --project-id=prOps3 --output=teams.n8np

워크플로 ID와 폴더 ID는 함께 사용할 수 있습니다. 프로젝트 ID는 둘 중 어느 것과도 함께 사용할 수 없습니다. 프로젝트 패키지는 구조가 다르기 때문입니다. 두 그룹을 섞으면 400이 반환됩니다.

폴더는 항상 중첩된 폴더와 그 안의 워크플로를 함께 가져옵니다. 지정한 폴더 안에 있는 워크플로를 따로 지정하더라도 한 번만, 폴더 안에 포함되어 내보내집니다.

n8n은 각 ID 그룹을 300개로 제한합니다. 이는 그룹별 제한이므로 한 번의 내보내기에서 워크플로 300개와 폴더 300개를 지정할 수 있습니다. 제한을 초과하면 400이 반환되며, CLI는 요청을 보내기 전에 이를 확인하지 않습니다.

비어 있는 프로젝트는 프로젝트 메타데이터만 내보내지며, 매니페스트에 workflows 목록이 없습니다.

내보내기 플래그#

--output은 기존 파일을 경고 없이 덮어씁니다. 내보내기가 실패하면 n8n은 아무것도 기록하지 않으므로, 실패한 실행은 이전 파일을 그대로 남깁니다.

서브 워크플로 의존성#

워크플로가 서브 워크플로를 호출하거나 오류 워크플로를 지정하면, 이는 패키지의 의존성입니다. --missing-workflow-dependency-policy는 의존성이 지정한 ID 집합에 없을 때 n8n이 수행할 동작을 결정합니다.

fail과 include-in-package는 전체 체인을 따라갑니다. 워크플로 A가 B를 호출하고 B가 C를 호출하는 경우, A와 B를 내보내도 C에서 여전히 실패합니다. reference-only만 직접 참조에서 멈추는데, 참조된 워크플로와 그 의존성이 대상에 함께 이미 존재한다고 가정하기 때문입니다.

오류 워크플로도 의존성으로 간주됩니다. Settings > Error workflow에 오류 워크플로가 구성된 워크플로는 해당 워크플로를 함께 포함하지 않으면 기본 내보내기가 실패합니다. 예외는 리터럴 값 DEFAULT와 표현식으로 설정된 오류 워크플로이며, n8n은 이를 무시합니다.

n8n은 표현식으로 설정된 참조를 의존성으로 취급하지 않으며, 가져오기 시에도 다시 쓰지 않습니다. 정적 참조만 계산됩니다.

일반적인 프로모션 사례에는 두 가지 형태가 있습니다.

# Name the dependency yourself
n8n-cli package export --workflow-id=wf7Kq2 --workflow-id=wf9Zx1 --output=triage.n8np

# Or let n8n work it out
n8n-cli package export --workflow-id=wf7Kq2 \
	--missing-workflow-dependency-policy=include-in-package \
	--output=triage.n8np

변수 값#

기본적으로 내보내는 워크플로가 참조하는 변수는 값과 함께 전달됩니다. --include-variable-values=false를 사용하면 변수는 여전히 전달되고 매니페스트와 requirements.variables에도 나타나지만, value 필드는 제외됩니다.

값을 끄면 가져오기 시 동작이 달라집니다. 대상 인스턴스는 변수를 값으로 채우지 않고 빈 상태로 생성합니다. 변수가 전달되는 것 자체를 막지는 않습니다.

값을 번들에 포함하려면 variable:list API 키 스코프가 필요하지만, 이는 내보내는 워크플로가 변수를 하나 이상 참조할 때만 해당합니다. 스코프가 없으면 내보내기는 스코프를 추가하거나 --include-variable-values=false를 설정하라는 403을 반환합니다. API 키를 생성할 수 있는 모든 역할은 variable:list를 할당할 수 있으므로, 여기서 403이 발생했다면 사용한 키가 이 스코프 없이 생성되었다는 뜻입니다.

n8n은 노드 파라미터와 워크플로 설정에서 $vars.NAME, $vars['NAME'], $vars["NAME"]을 검색하여 변수 참조를 찾습니다.

같은 패키지에서 하나의 변수 이름이 서로 다른 두 변수로 해석될 경우 내보내기가 차단됩니다. 패키지는 둘 중 하나만 담을 수 있기 때문입니다.

태그#

--include-tags=false를 사용하면 태그 데이터가 전달되지 않습니다. 내보내는 워크플로에 태그 참조가 없고 아카이브에 tags/ 디렉터리가 없습니다.

이는 가져오기에서 보이는 것보다 더 중요합니다. 태그 목록(빈 목록 포함)을 가진 워크플로는 대상 워크플로의 태그를 정확히 그 목록으로 덮어씁니다. 태그 목록이 전혀 없는 워크플로는 대상의 태그를 그대로 둡니다. 따라서 --include-tags=false가 대상의 기존 태그를 보존하는 옵션입니다.

소스 인스턴스에서 N8N_WORKFLOW_TAGS_DISABLED=true를 설정하면 이 플래그와 관계없이 모든 내보내기에서 태그가 경고 없이 제외됩니다.

응답이 알려 주는 내용#

내보내기에 성공하면 아카이브가 application/gzip으로 반환되며, 엔티티별 실제 개수를 담은 X-N8n-Export-Counts 헤더가 포함됩니다.

X-N8n-Export-Counts: {"workflows":2,"folders":0,"credentials":1,"dataTables":1,"variables":1,"tags":1}

이 개수는 폴더 내용과 자동으로 포함된 서브 워크플로를 반영한 뒤 아카이브에 실제로 들어간 항목의 개수이므로, 요청한 ID 개수와 일치할 필요는 없습니다. 헤더에는 projects 키가 없습니다. CLI는 이 헤더로 요약을 만들어 출력합니다.

credentials는 번들된 자격 증명 파일의 개수를 집계하므로, 읽을 수 없는 자격 증명은 개수를 늘리지 않고 요구 사항으로만 기록됩니다. variables는 참조된 이름이 아니라 번들된 변수 파일의 개수를 집계합니다.

다운로드 파일 이름은 내보낸 항목과 관계없이 항상 export.n8np입니다. CLI는 대신 --output에 기록합니다.

권한#

내보내기에는 다음 권한이 있는 API 키가 필요합니다.

• workflow:export: 워크플로 또는 폴더 ID를 지정할 때 필요합니다. 폴더는 워크플로 스코프를 사용합니다.
• project:export: 프로젝트 ID를 지정할 때 필요합니다.
• variable:list: 값을 번들에 포함하고 워크플로가 변수를 하나 이상 참조할 때 필요합니다.

API 키 외에도 읽을 수 있는 항목만 내보낼 수 있습니다. n8n은 패키지를 만드는 동안 각 워크플로, 폴더, 프로젝트, 자격 증명에 대한 사용자 본인의 접근 권한을 확인합니다. 읽을 수 없는 자격 증명은 번들되지 않고 요구 사항으로 기록됩니다.

내보내기에는 라이선스 기능이 필요하지 않습니다. 전체 매트릭스는 제한 및 권한을 참고하세요.

오류#

존재하지 않는 엔티티와 접근할 수 없는 엔티티는 동일한 메시지의 동일한 400을 반환하므로, 내보내기를 사용하여 ID의 존재 여부를 확인할 수 없습니다. 내보내기는 404를 반환하지 않습니다.

오류 본문에는 message만 포함됩니다.

이벤트#

모든 내보내기는 로그 스트리밍 경로와 텔레메트리 경로 모두에서 이벤트를 발생시키므로, 인스턴스에서 무엇이 나갔는지 감사할 수 있습니다.

성공 이벤트에는 사용자와 패키지에 실제로 들어간 workflowIds, folderIds, projectIds가 포함되므로, 요청한 항목이 아니라 폴더 내용과 자동으로 포함된 서브 워크플로를 반영합니다. 각 목록은 비어 있지 않을 때만 존재합니다.

실패 이벤트에는 사용자, 요청한 ID, 그리고 access-denied, entity-not-found, blocked, validation 중 하나인 reason이 포함됩니다.

로그 스트리밍 이벤트에는 ID가 포함됩니다. 텔레메트리 이벤트는 데이터를 익명으로 유지하기 위해 개수를 내보냅니다.

다음 읽을거리#

• 파일을 다른 인스턴스로 옮기려면 패키지 가져오기를 참고하세요.
• 아카이브 내부의 구성은 패키지 형식을 참고하세요.
• 크기 제한과 전체 스코프 매트릭스는 제한 및 권한을 참고하세요.

관련 리소스#

• n8n 패키지
• 패키지 형식
• 패키지 가져오기
• 가져오기 작동 방식
• 제한 및 권한