n8n packages
An n8n package is a single file that holds a slice of your n8n instance: some workflows or agents, plus the structure and references they need to run. Export a package from one instance, move the file, and import it into another. Think of it as an npm package for part of your n8n instance.
A package is a gzipped tar archive with the .n8np extension. Inside it, each entity is a small JSON file, and a manifest.json lists what's in the package and what the target instance has to supply. See Package format for the full layout.
Packages are an API feature. You export and import them through the n8n API, or through the n8n CLI, which wraps the same endpoints. There's no way to export or import a package from the n8n editor.
Three package shapes
What you export decides the shape of the package, and the shape decides how the contents land on import:
Workflow package: one or more workflows. On import, they land in the project and folder you choose.
Folder package: one or more folders, always including everything nested inside them. On import, the folder tree lands in the project you choose.
Project package: one or more whole projects. The package carries its own projects, so it decides where its contents land and ignores any target project you pass.
You can combine workflows, agents, and folders in one export, and a project package includes the agents in its projects. You can't combine workflows, agents, or folders with projects.
What travels in a package
Workflows: nodes, connections, settings, published state, archived state
Credential secrets and most values typed in directly
Folders and their nesting
Data table rows
Projects: name, description, icon
Executions and execution history
Credential references: ID, name, type, and fields set by an expression
Users, project members, roles, and sharing
Data table schemas: column IDs, names, and types
Pinned data and workflow static data
Variables: name and type, and the value unless you exclude it
Workflow version history
Tags
Whether a workflow is marked as a favorite
Agents: definition, custom tools, schedules, skills, and channel settings
Agent channel connections, sessions, and knowledge base files
Credential secrets never travel. A credential file in a package holds the credential's ID, name, and type. By default, it also holds the fields set by an n8n expression, such as ={{ $secrets.apiKey }}, and the settings those fields depend on. It never holds a secret or another value typed in directly, such as a host or region. See Credential values. On import, n8n matches each reference to a credential that already exists on the target instance, or creates one for you to fill in.
Data table rows never travel. Only the schema does. An imported data table starts empty.
When to use packages
Use packages when you need a repeatable, automatable way to move work between instances:
Promote between environments. Push workflows from development to staging to production as part of a pipeline. Repeated imports update in place rather than creating duplicates, so the same command works the first time and every time after.
Migrate to a new instance. Move a project, its folders, and its workflows in one file.
Share work without sharing secrets. Hand a workflow to another team knowing no credential secrets are in the file.
Back up structure. Keep a copy of the workflows and structure you'd need to rebuild, though a package isn't a full backup: no execution data travels.
Quick start
Point the CLI at your source instance, then export a workflow:
Point it at the target instance and import the file:
n8n checks the whole package before it writes anything. If something would block the import, such as a workflow that uses a node type the target instance doesn't have, the command exits with a non-zero status and lists every problem it found at once.
In this section
Package format: what's inside a
.n8npfile, the three package shapes, and the manifest.Export a package: export workflows, folders, or whole projects into a package.
Import a package: import a package and control where its contents land.
How import works: how n8n checks a package and resolves its dependencies before writing it.
Limits and permissions: size limits, license features, and API key scopes.
For other ways to move a workflow, including copy and paste and the editor's download and import options, see Export and import.
Related resources
Last updated
Was this helpful?