Importing a theme from a ZIP

Already have a theme packaged as a .zip — exported from a developer, copied from another store, or built locally? You can import it straight into your theme library. The platform creates a brand-new theme, unpacks the archive into its draft, and hands you back a report of anything it skipped.

Open Online store → Themes, then Add theme → Upload zip file (there’s also a quick Upload zip button in the Theme library header). Both open the Import theme from .zip dialog.

Note

Importing a theme is part of theme management, so you need the Manage themes permission. Store owners and staff with that permission can import; see Staff accounts.

What a theme ZIP looks like

A theme archive is just the standard theme folder structure zipped up. The importer reads files from these top-level folders:

• assets/ — CSS, JavaScript, images, fonts, and other static files
• blocks/ — reusable theme blocks
• config/ — settings_schema.json and settings data
• layout/ — theme.liquid and any alternate layouts
• locales/ — translation JSON files
• sections/ — section Liquid and JSON
• snippets/ — reusable Liquid snippets
• templates/ — page templates (index.json, product.json, and so on)

Anything outside these folders, or with an extension the folder doesn’t allow, counts as an unsupported file (see below). The archive can wrap everything in a single top-level folder (for example my-theme/templates/index.json) — the importer detects that wrapper and strips it automatically, so both flat and wrapped zips work.

Import a theme

1. Open Online store → Themes and choose Add theme → Upload zip file.

2. Enter a Theme name (required) and an optional Description. The name is how the theme shows up in your library — there’s no rename later, so pick it now. If the name clashes with an existing theme it’s still allowed; names don’t have to be unique.

3. Under Theme .zip file, pick your archive. The field accepts .zip only. Once selected, the dialog shows the file name and size so you can confirm you grabbed the right one.

4. Decide on the two options (covered below), then press Import theme. The button shows Importing… while the archive uploads and unpacks.

5. On a clean import the new theme is created as Unpublished, its draft is populated from the archive, and you’re taken straight into the editor. If anything was skipped, you stay on a summary screen first — see The skipped-files report.

The new theme always lands as an Unpublished library theme with a fresh working draft. Importing never touches your live storefront — publishing it is a separate, deliberate step. See Managing themes for how to activate it once you’re happy.

Import options

Two checkboxes in the dialog control how strict the import is.

Validate the imported theme is publishable

On by default. With this checked, the importer refuses any archive that couldn’t actually go live, so you don’t end up with a broken theme in your library. To pass, the archive must contain:

• at least one file in layout/, including layout/theme.liquid
• config/settings_schema.json
• templates/index.json
• exactly one default locale file (a locales/*.default.json)

If one of these is missing, the import fails with a message explaining what’s absent, and no theme is created. Uncheck this only when you’re deliberately importing a partial theme — for example a starter you intend to finish in the editor before publishing.

Tip

Leave validation on for any theme you plan to publish. It catches the most common “imported but won’t go live” problems up front, where they’re easy to fix, instead of after you try to activate the theme.

Ignore unsupported files instead of failing the import

Off by default. This decides what happens when the archive contains a file the importer doesn’t recognise — something in an unknown folder, or a file type a folder doesn’t allow.

• Unchecked (default): the whole import fails the moment it hits an unsupported path, telling you which file caused it. Use this when you expect the archive to be a clean theme and want to know about anything unexpected.
• Checked: unsupported files are skipped, the rest of the theme imports, and every skipped file is listed in the report afterwards. Use this for archives that carry extra baggage — documentation, build artifacts, source files — alongside the real theme.

What the importer handles automatically

Some entries are always dropped quietly, whether or not “ignore unsupported files” is on — they’re never errors and never appear in the skipped list:

• Operating-system clutter: __MACOSX/ folders, .DS_Store, Thumbs.db, and desktop.ini
• Empty directory entries
• A single wrapping top-level folder, which is stripped so paths line up

The importer also enforces a few safety rules and will reject the whole archive if it sees:

• Symlinks — not allowed in theme zips
• Duplicate paths, or two files whose paths differ only in letter case (e.g. Sections/Hero.liquid and sections/hero.liquid)
• Path traversal or non-canonical paths — entries containing .., control characters, or backslash tricks
• Code files that aren’t valid UTF-8 — Liquid, CSS, JS, and JSON must be text

Size and count limits

Archives are capped to keep imports fast and safe:

Limit	Maximum
Compressed .zip size	50 MB
Uncompressed total	120 MB
Supported theme files	1,500
Single code file (Liquid/CSS/JS/JSON)	256 KB
Single asset (image/font/etc.)	20 MB

If an archive exceeds any of these, the import fails with a message naming the limit it hit. Trim large assets or split the theme before retrying.

The skipped-files report

When you import with Ignore unsupported files on and the archive did contain unsupported entries, the dialog switches to an Import complete summary instead of dropping you in the editor. It shows:

• A banner noting how many files were not imported
• Files imported and Total size for what did come in
• A scrollable Skipped files list — each row shows the file’s path and the reason it was skipped (for example unsupported theme file path or outside detected theme root)

Review the list to make sure nothing important was left out. Then press Open editor to start working on the imported theme, or Close to return to the Themes page (the theme is already saved either way). A clean import with nothing skipped won’t show this screen — it goes straight to the editor.

Troubleshooting

• “theme zip is not publishable” / “theme must have …” — the Validate option is on and a required file is missing. Add the named file to the archive, or uncheck Validate the imported theme is publishable to import it as a partial theme and finish it in the editor.
• “unsupported theme file path in zip” — the archive has a file outside the recognised folders. Either remove it, or turn on Ignore unsupported files to skip it and import the rest.
• “theme zip does not contain any supported theme files” — nothing in the archive matched a theme folder. Check that you zipped the theme folders themselves (templates/, sections/, …) and not, say, a parent directory full of unrelated files.
• “duplicate file” / “case-conflicting files” — two entries resolve to the same path. Rename or remove one and re-zip.
• ”… is a symlink” — replace symlinks with the real files before zipping.
• Exceeds a size or file-count limit — see the table above; reduce the archive and retry.

Caution

There is no theme export to a .zip from the Themes page — import is one-way. To copy or branch an existing theme, use Use as draft on a published version instead. See Managing themes.

Next steps

Manage your themes

Activate, preview, and roll back themes in Managing themes.

Edit theme code

Open the imported theme’s Liquid, CSS, and JSON in Edit theme code.

Visual editor

Adjust sections, blocks, and settings in Using the visual editor.

Theme architecture

How the folder structure fits together in Theme architecture.

Related: Themes & the visual editor · Files · Staff accounts