n8n 패키지는 gzip으로 압축된 tar 아카이브입니다. 표준 도구로 읽을 수 있으므로 n8n 없이도 내용을 확인할 수 있습니다:

tar -tzf triage.n8np    # list what's inside
tar -xzf triage.n8np    # extract it

.n8np 확장자는 명명 규칙일 뿐입니다. n8n은 가져오기 시 파일 이름을 검사하지 않으며, 같은 구조의 압축되지 않은 tar도 허용합니다.

아카이브 안에서 모든 엔터티는 각자의 디렉터리에 있는 작은 JSON 파일 하나로 저장되며, 루트의 manifest.json이 전체를 색인합니다. n8n이 나머지를 읽기 전에 패키지를 검증할 수 있도록 manifest.json은 반드시 아카이브의 첫 번째 파일이어야 합니다.

세 가지 패키지 형태#

패키지 형태는 무엇을 내보냈는지에 따라 달라집니다. 세 가지 모두 같은 종류의 파일을 담고 있으며, 배치 방식만 다릅니다.

워크플로 패키지#

워크플로 ID로 내보내면 개별 워크플로가 만들어지며, 워크플로가 의존하는 모든 항목이 최상위 수준에 놓입니다:

triage.n8np
├── manifest.json
├── workflows/
│   ├── triage-inbound/
│   │   └── workflow.json
│   └── send-email/
│       └── workflow.json
├── credentials/
│   └── linear-api/
│       └── credential.json
├── variables/
│   └── slackchannelid/
│       └── variable.json
├── data-tables/
│   └── countries/
│       └── data-table.json
└── tags/
    └── prod/
        └── tag.json

폴더 패키지#

폴더 ID로 내보내면 폴더 트리가 유지됩니다. 폴더의 워크플로는 해당 폴더 안의 workflows/ 디렉터리에 놓이고, 중첩된 폴더는 folders/ 세그먼트를 반복하지 않고 부모 폴더 바로 안에 놓입니다. 자격 증명, 변수, 데이터 테이블, 태그는 최상위 수준에 유지됩니다:

in-progress.n8np
├── manifest.json
├── folders/
│   ├── to-production/
│   │   └── folder.json            # an empty folder is just the shell
│   └── in-progress/
│       ├── folder.json
│       ├── workflows/
│       │   └── triage-inbound/
│       │       └── workflow.json
│       └── nested/
│           ├── folder.json
│           └── workflows/
│               └── playground/
│                   └── workflow.json
├── credentials/
│   └── linear-api/
│       └── credential.json
└── tags/
    └── prod/
        └── tag.json

프로젝트 패키지#

프로젝트 ID로 내보내면 네임스페이스 계층이 추가됩니다. 여러 프로젝트를 하나의 패키지로 함께 옮길 수 있습니다. 내보낸 프로젝트가 소유한 자격 증명, 변수, 데이터 테이블은 해당 프로젝트 아래에 중첩됩니다. 전역 항목이거나 패키지에 포함되지 않은 프로젝트가 소유한 항목은 최상위 수준에 유지됩니다. n8n에서 태그는 전역이므로 태그는 항상 최상위 수준에 놓입니다:

team-ligo.n8np
├── manifest.json
├── projects/
│   └── team-ligo/
│       ├── project.json
│       ├── workflows/                    # workflows at the project root
│       │   └── triage-inbound/
│       │       └── workflow.json
│       ├── folders/
│       │   └── in-progress/
│       │       ├── folder.json
│       │       └── workflows/
│       │           └── send-email/
│       │               └── workflow.json
│       ├── credentials/                  # owned by this project
│       │   └── linear-api/
│       │       └── credential.json
│       ├── variables/                    # scoped to this project
│       │   └── slackchannelid/
│       │       └── variable.json
│       └── data-tables/
│           └── countries/
│               └── data-table.json
├── credentials/                          # a global credential
│   └── shared-smtp/
│       └── credential.json
├── variables/                            # a global variable
│   └── region/
│       └── variable.json
└── tags/                                 # always global
    └── prod/
        └── tag.json

디렉터리 이름 규칙#

각 엔터티는 이름의 슬러그(slug)로 지은 디렉터리를 가지며, 그 안에 JSON 파일 하나가 있습니다. 슬러그 변환은 이름을 소문자로 바꾸고, 영문자 a~z, 숫자, 공백, 하이픈이 아닌 문자를 모두 제거한 다음, 연속된 공백을 하이픈 하나로 바꿉니다:

마지막 행은 대체 규칙을 보여줍니다. 슬러그 변환 후 아무것도 남지 않으면 n8n은 엔터티 유형을 이름으로 사용합니다(workflow, folder, project, credential, variable, data-table, tag). 슬러그가 동일한 이름에는 2부터 시작하는 숫자 접미사가 붙으므로, 두 번째 Triage inbound는 triage-inbound-2가 됩니다.

디렉터리 이름은 아카이브를 읽는 사람을 위한 것입니다. n8n은 디렉터리 이름이 아니라 매니페스트와 JSON 파일에 있는 ID로 엔터티를 식별합니다.

manifest.json#

매니페스트는 색인입니다. 패키지에 무엇이 들어 있는지, 대상 인스턴스가 무엇을 제공해야 하는지를 n8n에 알려 주므로, 모든 파일을 읽지 않고도 가져오기를 빠르게 실패 처리할 수 있습니다.

다음 네 필드는 항상 존재합니다:

• packageFormatVersion: 패키지 형식의 버전이며, 현재는 문자열 "1"입니다.
• exportedAt: n8n이 패키지를 생성한 시각으로, ISO 8601 타임스탬프입니다.
• sourceN8nVersion: 패키지를 생성한 n8n 버전입니다.
• sourceId: 패키지를 생성한 인스턴스의 식별자입니다.

그 다음에는 존재하는 엔터티 유형별 항목 목록이 옵니다: workflows, folders, projects, credentials, dataTables, variables, tags. 비어 있는 목록은 아예 생략됩니다. 모든 항목은 동일한 세 필드를 가집니다:

• id: 소스 인스턴스에서의 엔터티 ID입니다.
• name: 엔터티의 이름입니다.
• target: 엔터티의 JSON 파일이 들어 있는 디렉터리이며, 패키지 루트를 기준으로 한 상대 경로입니다.

마지막으로 requirements가 오며, 워크플로가 대상 인스턴스에서 실행되는 데 필요한 항목을 나열합니다. 최대 여섯 개의 섹션이 있고, 각 항목은 그 항목이 필요한 워크플로의 ID인 usedByWorkflows를 포함합니다:

워크플로 두 개를 담은 워크플로 패키지의 전체 매니페스트 예시입니다:

{
	"packageFormatVersion": "1",
	"exportedAt": "2026-08-04T09:14:02.117Z",
	"sourceN8nVersion": "2.34.0",
	"sourceId": "f9e1e962bba26edf357042c12f367dab17f4c63ec368e1f39cbf7ce43c8b9f8b",

	"workflows": [
		{ "id": "wf7Kq2", "name": "Triage inbound", "target": "workflows/triage-inbound" },
		{ "id": "wf9Zx1", "name": "Send email", "target": "workflows/send-email" }
	],
	"credentials": [
		{ "id": "crLin44", "name": "Linear api", "target": "credentials/linear-api" }
	],
	"dataTables": [
		{ "id": "dtCn12", "name": "countries", "target": "data-tables/countries" }
	],
	"variables": [
		{ "id": "vaSl03", "name": "slackChannelId", "target": "variables/slackchannelid" }
	],
	"tags": [
		{ "id": "tgPr01", "name": "prod", "target": "tags/prod" }
	],

	"requirements": {
		"credentials": [
			{ "id": "crLin44", "name": "Linear api", "type": "linearApi", "usedByWorkflows": ["wf7Kq2"] }
		],
		"dataTables": [
			{ "id": "dtCn12", "name": "countries", "usedByWorkflows": ["wf7Kq2"] }
		],
		"workflows": [
			{ "id": "wf9Zx1", "name": "Send email", "usedByWorkflows": ["wf7Kq2"] }
		],
		"variables": [
			{ "name": "slackChannelId", "usedByWorkflows": ["wf7Kq2"] }
		],
		"tags": [
			{ "id": "tgPr01", "name": "prod", "usedByWorkflows": ["wf7Kq2"] }
		],
		"nodeTypes": [
			{ "type": "n8n-nodes-base.formTrigger", "typeVersion": 2.5, "usedByWorkflows": ["wf7Kq2"] },
			{ "type": "n8n-nodes-base.linear", "typeVersion": 1, "usedByWorkflows": ["wf7Kq2"] },
			{ "type": "n8n-nodes-base.executeWorkflow", "typeVersion": 1.2, "usedByWorkflows": ["wf7Kq2"] },
			{ "type": "n8n-nodes-base.dataTable", "typeVersion": 1, "usedByWorkflows": ["wf7Kq2"] },
			{ "type": "n8n-nodes-base.emailSend", "typeVersion": 2.1, "usedByWorkflows": ["wf9Zx1"] }
		]
	}
}

data-table.json#

각 데이터 테이블 파일에는 테이블의 스키마가 들어 있습니다. 행(row)은 절대 함께 이동하지 않습니다.

{
	"id": "dtCn12",
	"name": "countries",
	"columns": [
		{ "id": "dcNm01", "name": "name", "type": "string", "index": 0 },
		{ "id": "dcCd02", "name": "code", "type": "string", "index": 1 }
	]
}

칼럼 ID 덕분에 가져오기 시 이름이 바뀐 칼럼을 인식할 수 있으므로 칼럼이 값을 그대로 유지합니다. n8n 2.44.0 이전에 내보낸 패키지에는 칼럼 ID가 없으므로 n8n은 칼럼을 이름으로 짝지으며, 이름이 바뀐 칼럼은 파괴적 변경으로 간주됩니다. 데이터 테이블을 참조하세요.

버전 호환성#

packageFormatVersion은 현재 "1"입니다. n8n 인스턴스는 버전이 정확히 일치할 때만 패키지를 가져옵니다. 호환 범위도 마이그레이션 경로도 없습니다. 다른 버전을 선언한 패키지는 아무것도 쓰기 전에 400으로 거부됩니다.

sourceN8nVersion은 참고용으로만 기록됩니다. 어떤 것도 이 값을 대상 인스턴스와 비교하지 않으므로, 형식 버전이 일치하고 대상 인스턴스에 워크플로가 사용하는 노드 유형이 있기만 하면 서로 다른 n8n 버전을 실행하는 인스턴스 사이에서 패키지를 자유롭게 옮길 수 있습니다.

예외는 데이터 테이블 칼럼 ID입니다. n8n 2.44.0부터 내보낸 데이터 테이블에는 칼럼 ID가 포함되며, 이전 버전의 인스턴스는 칼럼 ID가 있는 패키지를 400으로 거부합니다. 가져오는 인스턴스를 먼저 업그레이드하세요.

파이프라인에서 패키지 비교#

아카이브는 결정적(deterministic)입니다. 파일 타임스탬프는 Unix 에포크로 고정되고, 권한도 고정되며, gzip은 이식 가능 모드로 실행됩니다. 내용이 동일한 두 번의 내보내기는 컨테이너에서 동일한 바이트를 생성합니다.

유일한 예외는 manifest.json이며, 내보낼 때마다 새로운 exportedAt을 포함합니다. 이 필드 하나만으로도 변경되지 않은 내용의 두 내보내기는 바이트 단위로 동일하지 않습니다. 파이프라인에서 변경을 감지하기 위해 패키지의 체크섬을 계산한다면 비교에서 exportedAt을 제외하세요. 그렇지 않으면 실행할 때마다 차이가 나타납니다.

다음 읽을거리#

• 세 가지 형태를 각각 만드는 방법은 패키지 내보내기를 참조하세요.
• 내용이 놓이는 위치를 제어하는 옵션은 패키지 가져오기를 참조하세요.
• n8n이 각 엔터티 파일을 어떻게 처리하는지는 가져오기 동작 방식을 참조하세요.

관련 리소스#

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