How to Install Shopify Theme Kit?

Need full control over your Shopify theme development? Installing Shopify Theme Kit gives you the power to edit themes locally, push changes instantly, and work with professional development tools. This guide walks you through every step to install Theme Kit on any platform and get your local environment running.

Summary

• Platform Installation: Install Shopify Theme Kit on Windows (via Chocolatey), macOS (via Homebrew), or Linux (via curl script) using simple command-line instructions
• Authentication Setup: Generate a Theme Access password through your Shopify admin to connect Theme Kit securely to your store
• Theme Configuration: Create and configure a config.yml file to establish the connection between your local files and Shopify store
• Development Workflow: Use watch commands to automatically sync local changes with your live or development theme
• Troubleshooting: Identify and resolve common installation errors, connection issues, and file sync problems

What Is Shopify Theme Kit?

Shopify Theme Kit is a command-line tool developed by Shopify that allows developers to build and customize themes locally. Rather than editing code directly in the Shopify admin’s online editor, you can use your preferred code editor, version control systems like Git, and automated workflows.

With Theme Kit, you gain the ability to watch for file changes, upload themes to multiple environments, and collaborate with team members more effectively. It works across Windows, macOS, and Linux, making it accessible regardless of your development setup.

Theme Kit is particularly valuable for developers working on Shopify custom development projects that require advanced customization or frequent updates. While Shopify CLI has become the recommended tool for Online Store 2.0 themes, Theme Kit remains essential for maintaining legacy themes and specific workflows.

Key Features of Shopify Theme Kit

Understanding what Theme Kit can do helps you maximize its potential:

These capabilities make Theme Kit an indispensable tool for professional Shopify development workflows.

Prerequisites for Shopify Theme Kit Installation

Before you install Theme Kit, verify you have:

• Administrative Access: You need admin rights on your computer to install software
• Shopify Store Access: Store owner or staff permissions with theme editing capabilities
• Command Line Knowledge: Basic familiarity with terminal or command prompt operations
• Package Manager (optional but recommended): Chocolatey for Windows, Homebrew for macOS

Having these prerequisites in place ensures a smooth installation process.

How to Install Shopify Theme Kit by Platform

The installation process varies by operating system. Choose the method that matches your development environment.

Installing Theme Kit on macOS

macOS users can install Theme Kit quickly using Homebrew, the standard package manager for Mac.

First, open your Terminal application. If you don’t have Homebrew installed, install it by running:

bash

/bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)“

Once Homebrew is ready, install Theme Kit with this command:

bash

brew tap shopify/shopify

brew install themekit

After installation completes, verify Theme Kit is working by checking the version:

bash

theme version

This should display the installed Theme Kit version, confirming successful installation.

Note: Apple M1/M2 users should run Terminal with Rosetta if you encounter compatibility issues. Right-click Terminal, select “Get Info,” and check “Open using Rosetta.”

How to Install Theme Kit Shopify on Windows

Windows installation requires Chocolatey, a package manager that simplifies software installation.

Open PowerShell as an administrator (right-click and select “Run as Administrator”). If Chocolatey isn’t installed, run:

powershell

Set-ExecutionPolicy Bypass –Scope Process –Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString(‘https://community.chocolatey.org/install.ps1’))

Once Chocolatey is installed, install Shopify Theme Kit with:

powershell

choco install themekit

Verify the installation by running:

powershell

theme version

PowerShell Tip: When using shortened command forms with URLs containing dashes, enclose the entire URL in quotation marks to avoid parsing errors.

Installing Theme Kit on Linux

Linux users can install Theme Kit using a Python installation script provided by Shopify.

Open your terminal and run the following command:

bash

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

This downloads and executes the installation script. After completion, verify with:

bash

theme version

The version output confirms Theme Kit is properly installed and accessible from your command line.

Generating Your Shopify Theme Access Password

After installing Theme Kit, you need a Theme Access password to connect it to your Shopify store. This password provides the authentication required for Theme Kit to read and write theme files.

Important: Theme Access invitations expire after 7 days if not viewed. The password can only be viewed once, so copy and store it securely.

To install the Theme Access app, the store owner or an admin should:

1. Log into Shopify Admin
2. Navigate to the Apps section
3. Search for “Theme Access” and install
4. Create a new Theme Access password
5. Enter the developer’s email address
6. Set permissions to “Read and write” for themes

Once you receive the invitation email, click “Get Theme Password” and immediately copy the password. You’ll use this in your configuration file.

Setting Up Your Configuration File

The config.yml file is how Theme Kit knows which store and theme to work with. This configuration file lives in your theme directory and contains all the connection details.

Creating Your First Config File

Navigate to where you want to store your theme files and create a new directory:

bash

mkdir my-shopify-theme

cd my-shopify-theme

Now you can download an existing theme and automatically generate the config file, or create the config file manually for a new theme.

Connecting to an Existing Shopify Theme

To work with a theme that’s already on your store, you need its Theme ID. Get your theme ID by running:

bash

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

This returns a list of all themes on your store with their corresponding IDs.

Once you have the Theme ID, download the theme and create the config file:

bash

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

This command downloads all theme files to your current directory and creates a config.yml file with the proper settings.

Manual Config File Creation

If you prefer to create the config file manually, create a file named config.yml in your theme directory with this structure:

yaml

development:

  password: your_theme_password_here

  theme_id: “your_theme_id_here”

  store: your-store.myshopify.com

You can add multiple environments to the same config file:

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

production:

  password: prod_password

  theme_id: “live”

  store: your-store.myshopify.com

This multi-environment setup allows you to deploy to different themes with a single command by specifying the environment flag.

Creating a New Theme with Theme Kit

To create a brand new theme from scratch using Theme Kit, use the new command:

bash

theme new –password=[your-theme-password] –store=[your-store.myshopify.com] –name=[YourThemeName]

This command performs several actions:

• Creates a basic theme structure with all necessary directories
• Uploads the new theme to your Shopify store
• Automatically generates or updates your config.yml file
• Links your local environment to the new theme

The basic theme structure includes folders for assets, config, layout, locales, sections, snippets, and templates—everything you need to start building.

Using Theme Kit Watch Command

The watch command is one of Theme Kit’s most powerful features. It monitors your local theme files and automatically uploads changes to your Shopify store the moment you save.

To start watching your theme directory:

bash

theme watch

When watch is active, Theme Kit continuously monitors all files in your theme directory. Any changes you make to HTML, CSS, JavaScript, or Liquid files are immediately synced to your connected theme.

To stop watching, press Ctrl + C in your terminal.

Watch Command Tips:

• Open your theme preview URL in a browser while watching to see changes instantly
• Use watch with the –notify flag to get desktop notifications on successful uploads
• Combine watch with browser live reload extensions for a seamless development experience

For working with specific environments, use:

bash

theme watch –env production

This ensures changes go to the correct theme when you have multiple environments configured.

Shopify CLI vs Theme Kit: Which Should You Use?

Shopify now recommends using Shopify CLI for theme development, especially for Online Store 2.0 themes. However, Theme Kit still has essential use cases.

• When to use Shopify CLI: Building new themes from scratch, working with Online Store 2.0 features, want integrated development server.
• When to use Theme Kit: Maintaining existing themes, prefer simpler tooling, need multi-environment deployment capabilities, working with older theme architectures.

Many developers use both tools depending on the project requirements. For Shopify migration projects or maintaining multiple client stores, Theme Kit’s simplicity and reliability remain valuable.

Common Theme Kit Installation Issues and Solutions

Even with straightforward installation steps, you might encounter issues. Here are the most common problems and their solutions.

Installation Errors

Problem: “Command not found” after installation Solution: Ensure the installation directory is in your system PATH. On Windows, restart PowerShell or Command Prompt. On Mac/Linux, restart your terminal or run source ~/.bash_profile (or equivalent for your shell).

Problem: Permission denied errors during installation Solution: Run the installation command with administrator privileges (sudo on Mac/Linux, Run as Administrator on Windows).

Connection Problems

Problem: “401 Unauthorized” error when running commands Solution: Your Theme Access password may be incorrect or expired. Generate a new password from the Theme Access app.

Problem: Theme ID not found Solution: Verify the Theme ID by running theme get –list with your credentials. Ensure you’re using the numeric ID, not the theme name.

File Sync Issues

Problem: Changes not appearing after upload Solution: Clear your browser cache and Shopify’s CDN cache. Add a query parameter to your preview URL (e.g., ?v=2) to bypass caching.

Problem: “File too large” errors Solution: Theme Kit has file size limits. Optimize large assets or consider hosting them on a CDN rather than including them in the theme.

For persistent issues, check the Shopify development documentation or consult with experienced developers.

Advanced Theme Kit Configuration

Once you’re comfortable with basic Theme Kit usage, these advanced configurations can improve your workflow.

Ignore Files and Directories

Create a file named .themekitignore in your theme directory to prevent certain files from syncing:

config/settings_data.json

*.swp

.git/

.DS_Store

node_modules/

This keeps temporary files, version control directories, and generated files from cluttering your theme.

Using Environment Variables

For team projects, avoid committing passwords to version control by using environment variables in your config:

yaml

development:

  password: ${SHOPIFY_PASSWORD}

  theme_id: ${SHOPIFY_THEME_ID}

  store: ${SHOPIFY_STORE}

Set these variables in your system environment rather than hardcoding sensitive credentials.

Deploying Specific Files

To upload only certain files instead of your entire theme:

bash

theme deploy templates/product.liquid sections/header.liquid

This selective deployment is faster and reduces the risk of overwriting unintended changes.

Best Practices for Theme Kit Development

Following these practices helps you avoid common pitfalls and maintain a professional development workflow.

• Always work on a duplicate theme first. Before making changes to your live theme, duplicate it and work on the copy. This protects your live store from experimental changes.
• Use version control. Initialize a Git repository in your theme directory and commit changes regularly. This gives you a complete history and makes it easy to revert problematic changes.
• Test across devices and browsers. Theme Kit makes development faster, but always test your changes on multiple devices before deploying to production.
• Maintain separate development and production environments. Use Theme Kit’s multi-environment configuration to keep development work isolated from your live store.
• Document custom functionality. If you add custom features or modify standard theme behavior, document your changes for future reference.

These practices align with professional Shopify integration standards and help teams collaborate effectively.

Troubleshooting Theme Development Issues

Beyond installation problems, you might encounter theme-specific issues during development.

Liquid Syntax Errors

Symptom: Theme fails to render or displays error messages Diagnosis: Check for unclosed tags, incorrect variable names, or missing delimiters in your Liquid code Fix: Review recent changes in your .liquid files. The Shopify admin’s code editor highlights syntax errors in red.

CSS Changes Not Applying

Symptom: Updated styles don’t appear on the storefront Diagnosis: Browser caching, CSS specificity issues, or conflicting styles Fix: Use browser developer tools to inspect elements and verify which styles are actually applied. Check for !important declarations that might override your changes.

JavaScript Errors

Symptom: Interactive features stop working Diagnosis: Console errors indicate script problems Fix: Open browser developer tools and check the Console tab for error messages. Common issues include missing jQuery references or conflicts with app scripts.

For complex issues that require expert knowledge, consider working with a Shopify development agency that specializes in theme customization.

Integrating Theme Kit with Your Development Tools

• Theme Kit works alongside your existing development tools to create a powerful workflow.
• Code Editors: Use VS Code, Sublime Text, or your preferred editor. Install Shopify-specific syntax highlighting extensions for better Liquid support.
• Version Control: Initialize Git in your theme directory immediately after downloading. Create a .gitignore file to exclude config.yml (which contains passwords) and other sensitive files.
• Task Runners: Combine Theme Kit with Gulp, Webpack, or other build tools to automate tasks like CSS compilation, JavaScript bundling, and image optimization.
• Live Reload: Use browser extensions like LiveReload along with Theme Kit’s watch command to automatically refresh your browser when files change.

These integrations turn Theme Kit from a simple sync tool into part of a comprehensive development environment, similar to what you’d have for modern web development projects.

Security Considerations for Theme Kit

Working with Theme Kit involves authentication credentials that need proper protection.

• Never commit config.yml to public repositories. Your config file contains Theme Access passwords that provide full access to your theme files. Add config.yml to your .gitignore file immediately.
• Use environment-specific passwords. Generate separate Theme Access passwords for development, staging, and production environments. This limits exposure if one password is compromised.
• Rotate passwords regularly. Periodically generate new Theme Access passwords and update your config files, especially when team members leave or change roles.
• Limit Theme Access permissions. When creating Theme Access passwords, only grant the minimum necessary permissions for the task at hand.
• Keep Theme Kit updated. Run theme update periodically to get security patches and bug fixes.

These security practices protect your store and customer data while maintaining the convenience of local development.

Key Takeaways

• Install Shopify Theme Kit using platform-specific package managers (Homebrew, Chocolatey, or curl) for streamlined setup and updates.
• Generate secure Theme Access passwords through Shopify Admin and configure environments in config.yml for multi-stage development workflows.
• Use the watch command during active development to sync local changes automatically, reducing deployment friction.
• Choose between Theme Kit and Shopify CLI based on project requirements—Theme Kit excels for legacy themes and established workflows.
• Implement version control, testing protocols, and security best practices to maintain professional development standards.

Conclusion

Learning how to install Shopify Theme Kit opens up professional-grade theme development capabilities for your store. The installation process is straightforward across all major platforms, and once configured, Theme Kit becomes an essential part of your development workflow.

Whether you’re customizing an existing theme or building from scratch, Theme Kit gives you the local development environment you need to work efficiently. Combined with version control and proper testing procedures, it enables you to deliver high-quality theme customizations with confidence.

Ready to take your Shopify theme development to the next level? Our team of Shopify experts can help you implement Theme Kit in your workflow and build custom themes that drive results.

Frequently Asked Questions

Can I Use Theme Kit with Shopify’s Free Themes?

Yes, Theme Kit works with both free and paid themes. Download any theme from the Shopify Theme Store, then use Theme Kit to customize it locally.

What’s the Difference Between Theme Kit and Shopify CLI?

Shopify CLI is the newer, recommended tool for Online Store 2.0 themes with additional features like a development server. Theme Kit is better for legacy themes and simpler workflows.

How Do I Update Theme Kit to the Latest Version?

Run theme update from your command line. The update command checks for the latest version and installs it automatically.

Can Multiple Developers Use Theme Kit on the Same Store?

Yes, multiple developers can work simultaneously if each has their own Theme Access password and works on separate themes or uses version control to coordinate changes.

Does Theme Kit Work with Shopify Plus Stores?

Absolutely. Theme Kit works identically for Shopify Plus stores as it does for standard Shopify stores. Shopify Plus merchants often use Theme Kit for advanced customization projects.

How Do I Prevent Theme Kit from Uploading Certain Files?

Create a .themekitignore file in your theme directory and list files or patterns to exclude. This works similarly to .gitignore files.

What Should I Do If Theme Kit Commands Are Slow?

Slow uploads often result from large asset files or poor internet connection. Optimize images before adding them to your theme, and ensure you have a stable connection.

Can I Customize My Own Theme with Theme Kit?

Yes, if you’re familiar with HTML, CSS, JavaScript, and Liquid (Shopify’s templating language), you can fully customize themes using Theme Kit. However, significant modifications require solid coding knowledge.

Is Theme Kit Free to Use?

Yes, Theme Kit is completely free and open-source. It’s maintained by Shopify and available to all merchants regardless of plan level.

Where Can I Find the Theme Kit Documentation?

Visit the official Theme Kit repository on GitHub or Shopify’s developer documentation at shopify.dev for comprehensive guides, command references, and troubleshooting resources.