Shopify Theme Check: How to Target Specific File Paths and Sections Liquid Files

Shopify Theme Check cannot accept a single file path as a positional argument. Running shopify theme check sections/hero.liquid will not lint just that file. The tool always validates the entire theme tree, but several supported techniques let you narrow what gets checked, what exits with an error, and what appears in your output. Here is every method that works, including changes introduced in Theme Check 2.x.

Key takeaways

• shopify theme check sections/hero.liquid is invalid syntax and exits with an error in Theme Check 2.x.
• --path scopes the run to a subdirectory, not a single file.
• JSON output (-o json) piped through jq is the only reliable way to filter results to one specific file.
• .theme-check.yml can ignore entire glob patterns, silencing noise from third-party or generated files.
• Inline {% # theme-check-disable CheckName %} comments suppress specific rules inside any Liquid file.
• Since CLI 4.0 (May 2026), Theme Check needs Node 22.12+ and the tool self-upgrades through your package manager.

Why there is no single-file argument

Theme Check is a whole-theme linter, not a file-by-file syntax checker. Many of its rules are cross-file by design: MissingSnippet checks whether a {% render %} call resolves to a real file elsewhere in the theme, and UnusedAssign needs to see every template that might consume a variable. Running it against one file in isolation would produce false positives on exactly those checks.

Because of that design, Shopify's official CLI docs confirm that Theme Check is meant to analyze the full theme tree. There is no --file or --only flag in the current CLI.

Method 1: --path to scope a subdirectory

The closest supported approximation of single-file linting is --path. It tells Theme Check where the theme root lives, not which file to check. But you can combine it with a creative directory structure during CI to get close:

# Lint the whole theme from the current working directory (default)
shopify theme check

# Lint a theme that lives inside a subdirectory
shopify theme check --path ./my-theme

If your sections folder is the only part of the repo that has changed in a given PR, you can point --path at a temporary copy that contains only the modified files. This is overkill for most teams, but it is useful when a monorepo contains multiple themes.

What --path does NOT do: it does not accept a single file like sections/hero.liquid as its value. Pass a directory, not a file path.

Method 2: JSON output piped to jq for per-file filtering

This is the most practical method for targeting a specific sections/*.liquid file in a CI pipeline. Theme Check's -o json flag emits a machine-readable flat array keyed by file path. Pipe that through jq to extract only the entry you care about:

# Run the full check, output JSON, then filter to one file
shopify theme check -o json \
  | jq '.[] | select(.path == "sections/hero.liquid")'

You can also assert a non-zero exit code yourself based on the filtered result:

ERRORS=$(shopify theme check -o json \
  | jq '[.[] | select(.path == "sections/hero.liquid") | .offenses[] | select(.severity == "error")] | length')

if [ "$ERRORS" -gt 0 ]; then
  echo "hero.liquid has $ERRORS error(s)"
  exit 1
fi

This pattern gives you the equivalent of per-file gating in your GitHub Actions or GitLab CI job, without needing a flag that does not exist.

Method 3: .theme-check.yml ignore patterns

If the goal is to silence a specific file or folder rather than target it, .theme-check.yml supports glob-based ignore lists per check. You can also ignore whole directories from all checks using the top-level ignore key:

# .theme-check.yml
TemplateLength:
  enabled: true
  ignore:
    - sections/legacy-*
    - snippets/vendor-*

UnusedAssign:
  enabled: true
  ignore:
    - snippets/replo-*

Generate a starter config with:

shopify theme check --init

This is especially useful when you have generated or third-party files (like Replo snippets) that contain intentionally split Liquid that would otherwise trigger LiquidHTMLParsingError on theme dev.

Method 4: Inline suppression comments inside sections Liquid

For one-off rules inside a specific section file, Liquid inline comments let you disable and re-enable any named check around a block of code:

{%- comment -%} Suppress false positive from vendor render pattern {%- endcomment -%}
{% # theme-check-disable UnusedAssign %}
{%- assign hero_context = section.settings.context -%}
{% # theme-check-enable UnusedAssign %}

You can also suppress a check for the entire file by placing the disable comment on the first line:

{% # theme-check-disable SpaceInsideBraces %}
{%assign x = 1%}

This approach is visible in code review (it shows up as a one-line diff) and does not affect any other file in the theme.

Method 5: VS Code onlySingleFileChecks for local development

If your goal is fast feedback in your editor while you are actively editing a section file, the Shopify Liquid VS Code extension has a setting that limits Theme Check to only the open file:

// .vscode/settings.json
{
  "themeCheck.onlySingleFileChecks": true
}

With this on, cross-file checks (like MissingSnippet) are skipped and only single-file rules run on the active tab. The official repo describes it as "great for performance if [you] can ignore checks that span multiple files during development." Run the full shopify theme check in CI to catch the cross-file issues.

Comparison: every method side by side

CLI 4.0 requirements you must not overlook (May 2026)

Since CLI 4.0 shipped in May 2026, two requirements changed that affect every CI pipeline running Theme Check:

• Node 22.12+ is required. Older Node versions will fail silently or produce unexpected output.
• The tool self-upgrades through your package manager and skips auto-upgrading inside CI by design. Pin your version in package.json or your CI image explicitly.

Also worth knowing: --category and --exclude-category were removed in Theme Check 2.x (January 2024). If you find older tutorials showing those flags, they no longer work. Use -C theme-check:all to run every available check explicitly.

CI gate pattern: the right way to run Theme Check in a pipeline

Here is the idiomatic pipeline sequence recommended by Shopify's own documentation:

# 1. Gate on errors (and warnings, which most teams ignore by default)
shopify theme check --fail-level warning

# 2. Push to an unpublished development theme for preview
shopify theme push --unpublished --json

# 3. Promote only after manual review
shopify theme publish --theme <ID> --force

Two common mistakes to avoid:

• The default --fail-level is error, meaning warnings accumulate silently and your CI job still exits 0. Pass --fail-level warning to block on them.
• --strict on theme push also blocks the push unless Theme Check passes, which gives you a second safety net at deploy time.

For per-PR preview themes, shopify theme push --development-context "pr-482" ties a development theme to a stable identifier like a PR number.

Putting it together: the practical workflow for sections Liquid

Here is the sequence most teams end up on after going through the above:

1. Editor: enable onlySingleFileChecks in VS Code for fast, in-file feedback while writing section Liquid.
2. Pre-commit hook: run shopify theme check --fail-level error against the whole theme before a commit goes up.
3. CI pull request gate: run shopify theme check -o json | jq to extract and assert on only the changed section files.
4. CI deploy gate: run shopify theme push --strict so that even if someone bypasses step 3, a push with errors is blocked.
5. Config: maintain a .theme-check.yml with targeted ignore globs for any generated or vendor snippets to prevent false positives from stopping real work.

Need help wiring this into a real pipeline? The Shopify theme developer services page has context on how I set this up for client projects, and Shopify speed optimization covers the performance checks that Theme Check flags most often.