Shopify Theme Kit: A Complete Guide to Setup and Customization

Editing Shopify themes in a browser window — without version control, proper tooling, or a local environment, is slow and hard to scale. Mistakes go live instantly, and collaboration becomes a bottleneck.

Shopify Theme Kit solves this. It’s a command-line tool that lets you develop themes locally, sync changes automatically, and manage multiple environments with a single config file. This guide covers installation, authentication, key commands, schema customization, and when to use Theme Kit versus Shopify CLI.

Summary

• What Theme Kit does: Enables local Shopify theme development with automatic file syncing
• Installation: Platform-specific steps for macOS, Windows, and Linux
• Authentication: Requires a Theme Access password from your Shopify admin
• Key commands: theme get, theme watch, theme deploy, and theme new
• Schema customization: Build client-editable settings into sections without exposing code
• Theme Kit vs Shopify CLI: Different tools for different project types — both have a place
• Best practices: Git, .gitignore, and multi-environment configs keep workflows team-ready

What Is Shopify Theme Kit?

Shopify Theme Kit is an open-source CLI tool that connects your local file system to a Shopify theme via API. When you save a file locally, Theme Kit detects the change and syncs it to your store in real time. It works on Windows, macOS, and Linux, and integrates cleanly with Git, VS Code, and build tools like Webpack or Gulp.

It’s particularly useful for teams managing multiple themes, handling frequent updates, or working on complex Shopify custom development projects that require a structured workflow.

Shopify Theme Kit vs. Shopify CLI

Shopify CLI is now the recommended tool for new theme development, especially for Online Store 2.0 themes. Theme Kit remains the right choice for maintaining existing themes and managing multi-environment deployments.

Many developers use both tools depending on the project. Use Shopify CLI for greenfield builds. Use theme kit Shopify for maintaining or updating existing themes.

How to Install Shopify Theme Kit

macOS

Install via Homebrew:

bash

brew tap shopify/shopify

brew install themekit

Verify with theme version. On M1/M2 chips, try running Terminal with Rosetta if you see compatibility errors.

Windows

Open PowerShell as an administrator, install Chocolatey if needed, then run:

powershell

choco install themekit

Verify with theme version. Wrap URLs containing dashes in quotation marks to avoid PowerShell parsing issues.

Linux

bash

curl -s https://shopify.github.io/themekit/scripts/install.py | sudo python

Verify with theme version. If the version output appears, you’re ready to proceed.

Generating a Theme Access Password

Theme Kit authenticates via the Theme Access app — a Shopify-native app that generates scoped API passwords.

Set permissions to “Read and write” for themes. Copy the password immediately — you cannot retrieve it after leaving that screen. Never commit it to a Git repository.

Setting Up config.yml

The config.yml file connects your local environment to a specific Shopify theme. It sits at the root of your theme directory.

Connect to an Existing Theme

List all themes and their IDs:

bash

theme get --list --password=[your-password] --store=[your-store.myshopify.com]

Then download the theme and auto-generate config.yml:

bash

theme get --password=[your-password] --store=[your-store.myshopify.com] --themeid=[your-theme-id]

Multi-Environment Setup

One of the strongest features of Shopify themekit is native multi-environment support:

yaml

development:

  password: dev_password

  theme_id: "123456789"

  store: your-store.myshopify.com

staging:

  password: staging_password

  theme_id: "987654321"

  store: your-store.myshopify.com

Deploy to a specific environment with theme deploy –env=staging. This makes it easy to test changes before pushing to production — a standard practice in any serious Shopify development process.

Core Theme Kit Commands

• theme watch — Monitors all files and uploads changes on save. Stops syncing if a Liquid file has a syntax error, acting as a lightweight quality check. Stop with Ctrl + C.
• theme deploy — Pushes all local files to Shopify in a single batch. Use this when deploying a complete, reviewed set of changes.
• theme download — Pulls the latest theme from Shopify to your local machine. Run this when another developer has made changes directly in the Shopify admin.
• theme new — Creates a blank theme on your store and sets up the local directory structure: assets, config, layout, locales, sections, snippets, and templates.

Schema Customization with Theme Kit

One of the most practical — and often overlooked — features when working with Shopify themekit is schema-driven settings. Schemas are JSON blocks inside section Liquid files that define client-editable options visible in the Shopify theme editor.

json

{% schema %}

{

  "name": "Hero Banner",

  "settings": [

    { "type": "text", "id": "heading", "label": "Banner Heading", "default": "Welcome" },

    { "type": "checkbox", "id": "show_button", "label": "Show CTA Button", "default": true }

  ]

}

{% endschema %}

The Liquid file references those settings directly:

liquid

<h1>{{ section.settings.heading }}</h1>

{% if section.settings.show_button %}<a href="/collections/all">Shop Now</a>{% endif %}

This allows non-developers to update content without touching code — a significant time saver for client projects. You can further extend functionality using Shopify theme app extensions without modifying core theme files. Global theme settings live in /config/settings_schema.json and control the “Theme settings” panel in the editor.

Common Errors and Fixes

For deeper customization challenges, consider working with a team that specializes in Shopify theme customization.

Best Practices

Use Git from day one. Initialize a repository immediately after downloading a theme. This makes rollbacks and code reviews straightforward.

Add config.yml to .gitignore. It contains your Theme Access password. Also exclude node_modules/ and .DS_Store.

Never edit the live theme. Always work on a duplicate or development theme. If theme watch syncs a broken file, a live store can break.

Pair with a build tool. Combine Theme Kit with Gulp or Webpack to compile SCSS, bundle JavaScript, and optimize images before syncing. For a deeper understanding of Liquid syntax that underpins all Shopify themes, see our Shopify Liquid guide.

Key Takeaways

• Install Theme Kit using your platform’s package manager — Homebrew, Chocolatey, or the Linux curl script
• Authentication goes through the Theme Access app — the password is shown only once, so store it immediately
• theme watch is your primary command — auto-syncs on save and blocks syncing when Liquid errors are detected
• Multi-environment config.yml lets you deploy to dev, staging, and production independently with one flag
• Schema settings let non-developers manage content updates without touching code
• Theme Kit is not deprecated — use it for legacy themes; use Shopify CLI for new OS 2.0 builds

Conclusion

Shopify Theme Kit gives developers a clean, scalable alternative to browser-based theme editing. From installation to schema customization and multi-environment deployment, the setup is straightforward once the moving parts are in place.

Whether you’re maintaining a legacy theme or coordinating a development team, Shopify Theme Kit keeps your workflow organized and version-controlled. For next steps, explore our guide to building a custom Shopify theme — or talk to our Shopify team if you need expert help on a theme project.

Frequently Asked Questions

What Is Shopify Theme Kit Used For?

Shopify Theme Kit is a CLI tool for developing and editing themes locally. It syncs changes to your store automatically, works with Git and any code editor, and supports multi-environment deployments. It’s primarily used for legacy theme maintenance and structured team development workflows.

Is Shopify Theme Kit Still Supported?

Yes. Shopify maintains Theme Kit and it remains functional. Shopify CLI is recommended for new Online Store 2.0 builds. Theme Kit is still the better option for maintaining existing themes or managing multi-environment deployments.

How Do I Find My Theme ID for Theme Kit Shopify?

Run theme get –list –password=[password] –store=[store.myshopify.com] to list all themes with their IDs. Alternatively, go to Shopify Admin → Online Store → Themes → Edit code and copy the numeric ID from the URL.

What Is the Difference Between theme watch and theme deploy?

theme watch monitors files continuously and uploads individual changes as you save. theme deploy pushes all local files to Shopify at once. Use watch during active development; use deploy when pushing a complete, reviewed build.

Does Shopify Theme Kit Work with Online Store 2.0?

Theme Kit can read and write OS 2.0 theme files, but doesn’t fully support the JSON template and app block architecture. For new OS 2.0 builds, Shopify CLI is the correct tool. Theme Kit is best for pre-2.0 theme maintenance.

What Should I Add to .gitignore When Using Shopify Themekit?

Always exclude config.yml since it contains your Theme Access password. Also exclude node_modules/, .DS_Store, and any build output directories to keep sensitive credentials out of your repository.