Shopify Theme Check Specific Files and Sections with the CLI

To run Shopify Theme Check on specific files or sections, you have three options: pass a path argument directly to the CLI, use inline Liquid comments to disable checks for targeted blocks of code, or configure an ignore pattern in your .theme-check.yml file. There is no single --only flag that restricts output to one file, but combining these three approaches gives you precise, surgical control over what gets linted and what gets skipped.

Key takeaways

• shopify theme check ./sections/hero.liquid scopes the run to a specific file path.
• Inline {% # theme-check-disable %} comments suppress checks for a named block of Liquid code.
• .theme-check.yml lets you ignore whole glob patterns (e.g., snippets/icon-*) permanently.
• The --config flag overrides your config file on the fly, useful in CI pipelines.
• The legacy Shopify/theme-check Ruby gem was archived in July 2024; the current linter lives inside Shopify CLI via the @shopify/cli and @shopify/theme packages.

Why targeted linting matters (and where the confusion comes from)

Running shopify theme check against a large theme with hundreds of Liquid files produces a wall of warnings. Most developers want to lint just the file they are working on, or suppress a noisy check for one section without disabling it everywhere. The CLI documentation answers this, but it is scattered across three separate pages, which is why this question keeps coming up.

The good news: the tooling is genuinely flexible. Once you know which lever to pull for which use case, the workflow is fast.

Method 1: Pass a file path as a positional argument

The most direct approach. Instead of running Theme Check against the whole theme root, append the relative path of the file (or directory) you want to check:

shopify theme check sections/custom-hero.liquid
shopify theme check snippets/product-card.liquid
shopify theme check sections/

This tells the linter to analyze only that file or folder. One important caveat: whole-theme checks are partially suppressed when you scope to a single file. Checks that require cross-file awareness, such as UnusedSnippet or TranslationKeyExists, are disabled in single-file mode because they need to read the full theme to produce a meaningful result.

For strictly file-level errors (Liquid syntax, deprecated filters, undefined objects, missing {% endschema %} tags), single-file scoping works perfectly.

Method 2: Suppress checks inline with Liquid comments

When you want to keep a broad shopify theme check run but silence a specific check for one section of code, use Theme Check's built-in comment directives:

{% # theme-check-disable UnusedAssign %}
{% assign debug_mode = true %}
{% # theme-check-enable UnusedAssign %}

To disable all checks for a block:

{% # theme-check-disable %}
  {# ...legacy code you haven't migrated yet... #}
{% # theme-check-enable %}

This approach is the right choice when you are iterating on a complex custom section, inheriting a messy theme codebase, or adding Theme Check to a project that has a large backlog of pre-existing issues you are not ready to fix in one pass. The comments are scoped tightly: nothing outside those delimiters is affected.

Method 3: Configure ignore patterns in .theme-check.yml

For paths you want to permanently exclude, the .theme-check.yml config file is the right tool. You can generate a starter file with:

shopify theme check --init

Then edit the file to add ignore globs under specific checks or globally:

TemplateLength:
  enabled: true
  max_length: 400
  ignore:
    - sections/legacy-homepage.liquid
    - snippets/icon-*

You can also set per-check severity levels (error, warning, info) so that certain issues fail a CI run while others are reported as informational only. By default, Theme Check returns exit code 1 when at least one issue with severity error is detected. Use --fail-level to adjust this threshold for your pipeline:

shopify theme check --fail-level suggestion

Method 4: Override config on the fly with --config

If you maintain multiple check profiles (one strict, one permissive), the --config flag lets you swap between them without editing any file:

shopify theme check --config theme-check:recommended
shopify theme check --config theme-check:all

These built-in presets cover the most common scenarios. theme-check:recommended is the default for most theme submissions; theme-check:all enables every available check and is useful for a thorough audit before publishing to the Shopify Theme Store.

What changed in 2024: theme-check repo archived

If you have older bookmarks or tutorials referencing the standalone Shopify/theme-check Ruby gem, note that this repository was archived as read-only in July 2024. All active development moved into the Shopify/theme-tools monorepo, and the linter is now distributed through @shopify/cli and @shopify/theme npm packages.

To install or update:

# macOS
brew upgrade shopify-cli

# npm (global)
npm install -g @shopify/cli @shopify/theme

Starting with Shopify CLI 4.0, the CLI upgrades itself automatically using whichever package manager you installed it with, so in most cases you are already on the latest version.

The VS Code extension (Shopify Liquid) also bundles Theme Check and exposes a themeCheck.onlySingleFileChecks setting. When set to true, the extension checks only the file currently open, disabling whole-theme checks for performance. This mirrors the CLI's single-file path behavior and is worth enabling on large themes where full-theme linting on every save slows down the editor.

Putting it together: a practical workflow for section development

Here is the pattern that works well when building or debugging a custom Liquid section:

1. Start a dev server: shopify theme dev --store your-store.myshopify.com
2. Edit your section: make changes to sections/your-section.liquid
3. Lint just that file: shopify theme check sections/your-section.liquid
4. Suppress noisy checks inline for any pre-existing issues you are not fixing today.
5. Run a full check (shopify theme check) before opening a pull request or pushing to production.
6. Gate CI on errors only using --fail-level error so warnings do not block deploys.

This approach keeps your inner feedback loop fast while still catching real errors before they reach customers.

Keeping your storefront code clean is one layer of the operations stack. The other layer is knowing, every single day, which products are about to run out and cost you real sales. If you manage inventory across dozens or hundreds of SKUs, Stockcast: Inventory Forecast surfaces stockout predictions ranked by urgency with transparent, explainable math behind every recommendation, so reorder decisions are never a gut-feel guess.

Try Stockcast: Inventory Forecast on the Shopify App Store

FAQ

Can I run shopify theme check on a single Liquid section file? Yes. Pass the file path as a positional argument: shopify theme check sections/your-section.liquid. Note that whole-theme checks (such as unused snippet detection) are disabled when scoping to a single file, since they require reading the full theme to work correctly.

How do I disable a specific Theme Check rule for one block of code without turning it off everywhere? Use inline Liquid comment directives: {% # theme-check-disable CheckName %} before the block and {% # theme-check-enable CheckName %} after it. This suppresses only that named check within the delimited block and leaves the rest of the file and theme fully linted.

What happened to the standalone theme-check gem/CLI in 2024? Shopify archived the Shopify/theme-check Ruby gem repository in July 2024 and moved all active development into the Shopify/theme-tools monorepo. Theme Check is now distributed as part of @shopify/cli and runs via shopify theme check. If you are on an older setup, upgrade with brew upgrade shopify-cli or npm install -g @shopify/cli @shopify/theme.