> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/build/manage-workflows/n8n-packages.md).

# n8n packages

Bundle workflows, agents, and the structure they need into a portable .n8np file, and move them between n8n instances.

{% hint style="info" %}
**Feature availability**

n8n packages are available from n8n 2.27.0, and n8n has added options in most releases since, so check your version if an option here isn't recognized.
{% endhint %}

{% hint style="info" %}
**Preview status**

n8n packages are in Preview. The package format and the API may change in future releases, so avoid relying on them for critical automation without a plan to update.
{% endhint %}

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](/build/manage-workflows/n8n-packages/package-format.md) for the full layout.

Packages are an API feature. You export and import them through the [n8n API](/connect/n8n-api.md), or through the [n8n CLI](/connect/n8n-cli.md), 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

| Travels                                                                   | Doesn't travel                                                |
| ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| 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](/build/manage-workflows/n8n-packages/export-a-package.md#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:

```bash
n8n-cli config set-url https://source.example.com
n8n-cli config set-api-key <your-api-key>

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

Point it at the target instance and import the file:

```bash
n8n-cli config set-url https://target.example.com
n8n-cli config set-api-key <your-api-key>

n8n-cli package import --file=triage.n8np --project-id=<target-project-id>
```

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](/build/manage-workflows/n8n-packages/package-format.md): what's inside a `.n8np` file, the three package shapes, and the manifest.
* [Export a package](/build/manage-workflows/n8n-packages/export-a-package.md): export workflows, folders, or whole projects into a package.
* [Import a package](/build/manage-workflows/n8n-packages/import-a-package.md): import a package and control where its contents land.
* [How import works](/build/manage-workflows/n8n-packages/how-import-works.md): how n8n checks a package and resolves its dependencies before writing it.
* [Limits and permissions](/build/manage-workflows/n8n-packages/limits-and-permissions.md): 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](/build/manage-workflows/export-and-import.md).

## Related resources

* [Manage workflows](/build/manage-workflows.md)
* [Configure workflow settings](/build/manage-workflows/configure-workflow-settings.md)
* [Tag workflows](/build/manage-workflows/tag-workflows.md)
* [Favorite items](/build/manage-workflows/favorite-items.md)
* [View change history](/build/manage-workflows/view-change-history.md)
* [Review workflows](/build/manage-workflows/workflow-reviews.md)
* [Export and import](/build/manage-workflows/export-and-import.md)
* [Share with others](/build/manage-workflows/share-with-others.md)