Importing

Importing takes a package built on another environment and applies it here, resolving every UID reference to the matching local element. The control panel runs a four-step wizard; the CLI does it in one command.

The Four-Step Wizard

Go to Transport → Import and follow the steps:

1. Upload the package .zip.
2. Configure — review every element with its action (Add, Update, or Unchanged) and select which to import. Pre-flight validation flags any missing sections, entry types, groups, or volumes before you proceed.
3. Preview — see field-level changes (current vs. incoming) for every element being updated. Uncheck any field to keep the target’s current value. Choose whether to be emailed when it finishes, or tick Dry run to simulate it.
4. Run — Transport queues the import and works through the selected elements in dependency order. Its report appears in Transport → History when it finishes.

Imports Run in the Background

Real imports always run on Craft’s queue, so a large package can’t hit a request timeout half-way through. You can leave the page as soon as it’s queued; the control panel shows the job’s progress in the queue widget, and the finished report is waiting for you in History. Tick Email me the report to have it sent to you as well.

Dry runs are the exception — they change nothing and report back immediately on the next screen, which is the whole point of running one.

Queued work needs a queue runner. Craft’s built-in web-based runner handles this by default; if you’ve disabled it, make sure something runs craft queue/listen.

Dependency Ordering

Transport performs a topological sort so each element is imported only after the elements it depends on — structure parents, authors, and relations — with cycle detection built in. You never have to reason about import order yourself.

Field-Level Merge

On the Preview step, each changed field is shown side by side. Leave a field checked to accept the incoming value, or uncheck it to preserve what’s currently in the target. This makes it safe to pull in most of a package while protecting specific fields you’ve customized downstream.

From the CLI

Simulate first — a dry run reports exactly what would change without writing anything:

craft transport/import content.zip --dry-run

Then run it for real:

craft transport/import content.zip

Console imports are always synchronous — never queued — and stream their progress to the terminal as they work, finishing with a detailed report of every element added, updated, skipped, and failed. Add --verbose to list each element as it is processed:

craft transport/import content.zip --verbose

Pre-Flight Validation

Before importing, Transport checks that the target has the schema the package references — the right sections, entry types, category groups, and volumes. If something is missing, the import is blocked with a clear message so you can deploy your Project Config first. See Troubleshooting for the common cases.

Content That Already Exists

Transport identifies elements by UID, but the same content often exists in two environments with unrelated UIDs — a single created independently on each, or content seeded before Transport was installed. When a package element’s UID isn’t found, Transport matches the element that already exists by its natural key — a single’s section, a slug within its section or group, an asset’s filename in its folder, a user’s email — and updates it rather than adding a second copy. Matched elements are flagged as such in the wizard, so you see it before you run. Turn it off in settings for strict UID-only identity.

Every Import Is Reversible

Transport snapshots the affected elements before it writes anything. If an import doesn’t look right, roll it back with one click from History & Rollback.