Underscores in URLs: why hyphens separate words
Google reads blue-shoes as two words and blue_shoes as one. squirrel flags every crawled path containing an underscore.
What the hyphen convention is
A URL path has no built-in idea of words. Search engines infer them from separators, and Google’s URL structure guidance says to use hyphens rather than underscores, because a hyphen is read as a word break and an underscore is not.
blue-shoes is therefore two tokens and blue_shoes is one. That matters where the slug carries the terms a page should be found for. It is a small effect on its own, and the reason to prefer hyphens is that it costs nothing and is what every other site does.
What squirrel checks
The rule runs on every crawled page over the URL path only. It emits a single check named url-hyphens:
- Warn when the path contains an underscore. Message:
URL uses underscores (2) instead of hyphens, with the path as the value. Severity warning, weight 4. - Pass when the path contains a hyphen and no underscore. Message:
URL uses hyphens for word separation. - Info when the path contains neither. Message:
URL has no word separators.
The query string is not examined, so ?sort_by=price is not flagged. A path containing both characters is reported as an underscore finding.
How to fix it
https://example.com/blog/blue-running-shoes
Change the slug at the source, in the CMS field or the route definition, then 301-redirect the old path so links and rankings follow.
Renaming URLs is not free. A correct permanent redirect does not throw away ranking signals, but a migration still costs implementation time and usually produces a period of ranking movement. Fix the convention going forward and migrate old URLs only when you are changing them anyway.
| Rule ID | url/hyphens |
| Category | URL Structure |
| Scope | Per-page |
| Severity | warning |
| Weight | 4/10 |
Enable / disable
Disable this rule
[rules]
disable = ["url/hyphens"]Disable all URL Structure rules
[rules]
disable = ["url/*"]Enable only this rule
[rules]
enable = ["url/hyphens"]enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.
Related rules
- url/slug-convention: whether the site mixes separators rather than using one.
- url/lowercase: the other per-path convention check.
- url/slug-keywords: whether the slug says anything about the page.
- url/special-chars: characters that need encoding rather than replacing.
URL Structure findings ship in every audit next to the SEO, performance and agent experience rules. See Fix SEO issues with AI for how an agent works through a report.
References
Check your site
Run squirrel audit https://example.com and open the URL Structure section of the report. Every path containing an underscore is listed with its page. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.