Migrate to Shopify CLI 3.x
In October 2022, support for themes was added to Shopify CLI 3.x. Shopify CLI 3.x provides a streamlined authentication and store management experience.
On this page, you can learn about the differences between Shopify CLI 2.x and 3.x, and how to update your theme development environment.
Getting startedAnchor link to section titled "Getting started"
Refer to the following tutorials for details about creating or working on a Shopify theme using Shopify CLI:
Workflow changesAnchor link to section titled "Workflow changes"
Some changes were made to theme workflows to reduce the number of commands that need to be entered, simplify the command structure, and create a more consistent experience when developing across themes, apps, and custom storefronts.
|Authentication||Authenticate with Shopify CLI using
||You don't need to log in explicitly. If you aren't logged in, then you're prompted to log in when you run a command that requires authentication.|
|View the organization you're currently logged into using
||No longer supported|
|Store selection||Select a store using
|Switch between stores using
|General||Preview your theme in a store using
||Command is renamed to
|Populate stores using
||No longer supported|
|Specify the directory that you want to use using the
||Specify the directory that you want to use using the
Migrate to Shopify CLI 3.xAnchor link to section titled "Migrate to Shopify CLI 3.x"
Follow the steps below to migrate your theme development environment to Shopify CLI 3.x.
macOS and HomebrewAnchor link to section titled "macOS and Homebrew"
If you use Homebrew to manage your Shopify CLI installation on macOS, then you don't need to uninstall the previous version of Shopify CLI to migrate. Instead, you can upgrade to Shopify CLI 3.x directly.
In addition to the requirements for Shopify CLI 2.x, Shopify CLI 3.x requires Node.js 14.17.0 or higher. Homebrew installs Node.js for you when you upgrade to the latest version of Shopify CLI.
Step 1: Install new requirementsAnchor link to section titled "Step 1: Install new requirements"
In addition to the requirements for Shopify CLI 2.x, Shopify CLI 3.x requires Node.js 14.17.0 or higher. If you use macOS, then Homebrew will install Node.js for you when you upgrade to the latest version of Shopify CLI.
For a complete list of requirements, refer to Install Shopify CLI.
Step 2: Uninstall Shopify CLI 2.xAnchor link to section titled "Step 2: Uninstall Shopify CLI 2.x"
Consider uninstalling the previous version of Shopify CLI. Uninstalling the previous version avoids any collisions between the two versions.
If you want to keep both versions of Shopify CLI installed, then refer to Using both Shopify CLI 2.x and 3.x to learn how to work with both versions in the same environment.
Shopify CLI can be removed from your system using the same package manager that you used to install it:
If you’re using a legacy version of Shopify CLI (lower than
0.9.0), then you need to uninstall it manually.
Step 3: Install Shopify CLI 3.xAnchor link to section titled "Step 3: Install Shopify CLI 3.x"
Shopify CLI is managed as a set of Node.js packages:
You can install these packages using Homebrew on macOS, or by installing the packages globally on Windows or Linux.
You can install Shopify CLI on macOS using Homebrew.
You need to add Shopify's third-party repositories to Homebrew using
brew tap before you can install Shopify CLI.
Windows and LinuxAnchor link to section titled "Windows and Linux"
To install Shopify CLI for themes, install the
@shopify/theme Node.js packages globally using the command line.
Step 4: Verify the installationAnchor link to section titled "Step 4: Verify the installation"
To verify that Shopify CLI is installed properly, run the following command:
The command returns a version number.
Using both Shopify CLI 2.x and 3.xAnchor link to section titled "Using both Shopify CLI 2.x and 3.x"
If you need to continue using Shopify CLI 2.x and 3.x on the same machine, then consider the following strategies:
If you're using macOS and Homebrew, then you need to reinstall Shopify CLI 2.x with the new brew formula:
After Shopify CLI 2.x is reinstalled, you can run Shopify CLI 3.x commands using the
shopify program name, and run Shopify CLI 2.x commands using the
shopify2 program name. For example:
npm-based installationsAnchor link to section titled "npm-based installations"
If you have both versions of Shopify CLI installed, then the two versions might conflict because they both use the same program name (
Whichever version is listed first in your
PATH will run. You can update your path to change the default CLI, or temporarily uninstall one version to avoid confusion.