Unused CSS Finder - Command Line Version

How it works

This script finds that dead weight. It works in three steps:

1. Crawl. Starting from the address you give it, it follows internal links and reads each page, recording every class, every id and every stylesheet and script the page uses.
2. Read the CSS. It downloads each stylesheet (including @imported ones and inline <style> blocks) and splits it into individual selectors.
3. Compare. A selector is reported as unused when it needs a class or id that appears nowhere on the site, in any script, or in your safelist.

What you get

Options

Only the address is required. Everything else has a sensible default. Options can be written --name=value or --name value.

Settings file

For a site you scan regularly, keep the settings in a JSON file. Use the option names without the leading dashes:

{
  "url": "https://example.com/",
  "max-pages": 2000,
  "delay": 250,
  "exclude": ["/blog/", "/forum/*"],
  "safelist": ["btn-*", "modal", "re:^col-(sm|md|lg)-\\d+$"],
  "safelist-id": ["cookie-banner"],
  "source": ["/var/www/example"],
  "source-exclude": ["/tests/", ".min.js"],
  "purge": true
}

Then run php unused_css.php --config=unused-css.json.

Exit codes

0 means the run completed. 1 means it could not start or finish (bad option, unreachable site, no pages readable). Warnings about an incomplete crawl do not change the exit code, so check the report.

Checking your source files

A crawler can only see pages a visitor can reach. Members areas, logged-in dashboards, checkout steps and error screens are out of its reach. If you have the website's files, point the tool at the folder with --source. It reads your templates and scripts directly, so those areas are covered.

# Source files only
php unused_css.php --source=/var/www/example

# Only some file types, and skip tests and minified scripts
php unused_css.php --source=/var/www/example --source-ext=php,html,js --source-exclude=/tests/ --source-exclude=.min.js

# Crawl the live site and read the files too
php unused_css.php https://example.com/ --source=/var/www/example

On Windows write the folder as --source="C:\wamp64\www\example".

How source files are read

• Every word counts as use. The tool does not understand PHP, Twig or JavaScript. It collects every word in each file, so class="members-only", classList.add('is-open') and echo 'btn-' . $type all keep their classes. A prefix such as 'btn-' keeps every class that begins with it, as it does for scripts on a crawl.
• Default file types: html, htm, xhtml, php, phtml, inc, twig, tpl, js, mjs, jsx, ts, tsx, vue, svelte, erb, ejs, hbs, handlebars, njk, liquid, asp, aspx, cshtml, jsp and md. Use --source-ext to choose your own. Stylesheets are never read as source.
• Skipped folders: node_modules, vendor, bower_components, .git, .svn, .hg, .idea and .vscode. Third-party code in them would otherwise make almost every class look used. Binary files and files over 20 MB are skipped, and the report says how many.
• Only linked stylesheets are checked. A .css file is checked when a source file mentions it, for example in a <link href="css/main.css?v=3">, an @import, or a script or wp_enqueue_style call. Files imported by a checked stylesheet are followed too. Spare, old or backup stylesheets that nothing refers to are left out, and the report lists them so you can see which ones they are. Use --include-unlinked-css to check them anyway. If no source file mentions a stylesheet at all (for example a name built from variables), every .css file is checked, with a warning.
• Reading the report. The report lists how many source files were read and which stylesheets were not checked (unlinkedCss in report.json). pagesRead is 0 when no site was crawled.

Tips

• For a site that has a build step (Sass, a bundler), point --source at the folder with your templates and crawl the built site for its CSS, rather than checking the source .css files.
• Stylesheets are matched by path ending, so css/main.css in your source matches main.css anywhere in the folder tree. A web address such as a CDN link is never matched to a local file.
• Without a crawl, @import lines are followed when the file is inside the source folder. Web addresses in an @import are skipped.
• Classes added only by a server script outside the folders you gave are not seen. Add all the folders that hold your markup, with more than one --source if needed.

Safelisting

A safelist tells the tool “keep this, even if you cannot see it being used.” You need one when classes appear only at certain moments or are built in ways a crawler cannot read.

Pattern syntax

--safelist and --safelist-id match the whole name. --exclude matches anywhere in the URL, so --exclude=/blog/ skips every address containing /blog/.

On most terminals, put patterns containing *, (, | or $ in quotes so the shell does not change them.

When to safelist

• Classes added by clicks or timers in another way than plain strings, for example el.className = prefix + name.
• Classes that only exist in situations the crawler cannot reach: error messages, logged-in screens, seasonal banners, A/B variants.
• Classes used by third-party widgets that inject their own markup.

Reading the report

The easiest way to read the results is the report viewer: drop your report.json onto it for a sorted, searchable summary, with an option to hide stylesheets that have nothing to remove. Everything stays in your browser. The plain-text version, report.txt, looks like this (trimmed):

Unused CSS report for https://example.com/
============================================================
Generated 2026-10-14T00:12:41+00:00 by unused_css.php 1.1.2
Pages read: 214

WARNINGS
  - 3 page(s) could not be read (errors, timeouts or blocked requests).
    Classes used only on those pages may be wrongly listed as unused.

https://example.com/css/site.css?v=14
  selectors: 1,204 | unused: 311 | size: 88,412 -> 61,980 bytes
  unused classes: .promo-old .legacy-nav .tab-3 ...
  unused ids: #old-banner

UNUSED CLASSES (96)
  .legacy-nav
  .promo-old
  ...

• Warnings come first. If the crawl was cut short or pages failed, treat the list as a set of candidates, not facts.
• selectors / unused. A selector is one entry in a comma list. .a, .b { } is two selectors; if only .b is unused, .a stays in the cleaned file.
• size before → after. Applies only to the cleaned copy that --purge writes.
• report.json lists every individual selector that would be removed, which is useful when checking a surprising result.

What is checked

What is not checked

These are the limits of the approach. Some make the tool flag classes that are really in use, and those are the ones to review before you delete anything. Others make it keep classes that are really unused, which is safe but means you may see smaller savings. The rest are things it simply does not analyse.

Things that can make a used class look unused

• JavaScript is not run. The tool reads the HTML the server sends. Content that scripts build in the browser, such as single-page apps (React, Vue, Angular), content loaded with fetch or AJAX, infinite scroll, or markup injected from a template, is invisible to it. For such sites the results are unreliable.
• Pages it cannot reach. Only links in the HTML are followed. It does not read your sitemap, log in, keep cookies, submit forms or use search. Orphan pages, member areas, checkout steps, search results and pages that exist only behind JavaScript menus are never seen. If you have the website's files, read them with --source to cover these areas.
• States that are not showing. Error messages, success banners, flash notices, cookie banners shown only once, seasonal promotions, A/B variants and per-language pages that are not linked are missing unless they happened to be in the HTML it fetched.
• Class names built in pieces. A prefix such as 'btn-' + type is detected. A suffix (type + '-btn') or a name assembled from several parts in the middle is not.
• Server-side only differences. If your server sends different HTML to crawlers than to browsers, or blocks the crawler partway, the tool sees only what it was given. Check the warnings for failed pages.
• Crawl limits. If --max-pages is reached, pages beyond it are not scanned. The report warns you when this happens.
• Other hosts. Subdomains other than www are treated as different sites and are not crawled. Third-party CSS and JavaScript are skipped unless you opt in.
• Size limits. Pages over 5 MB and stylesheets or scripts over 20 MB are skipped. Up to five redirects are followed.

Things that can make an unused class look used

• Words in scripts count. Every word in your JavaScript counts as use, so a class named header is kept if the word “header” appears in any script, even as a variable name. This is deliberate: it avoids deleting classes that scripts really do add.
• Prefix matching is broad. One string such as 'col-' in a script keeps every class starting with col-. Use --no-js-prefixes if this keeps too much.
• Source files. With --source, every word in your templates and scripts counts as use, comments and variable names included. See checking your source files.
• The default safelist. Classes such as active and is-* are kept even if nothing uses them. Use --no-default-safelist to turn this off.

What the CSS check does not do

• It does not match selectors against the page structure. A rule like .menu .item is kept if both classes appear anywhere on the site, even if no .item ever sits inside a .menu. Descendant, child and sibling relationships are not tested.
• Only classes and ids are examined. Tag selectors, attribute selectors ([type=text], [class^="icon-"]), pseudo-classes and pseudo-elements are not checked. A selector with no class or id in it is always kept.
• Arguments of :not(), :is(), :where() and :has() are ignored. A class used only inside one of those never causes a rule to be flagged.
• Native CSS nesting is not analysed. The outer rule is checked; rules nested inside its braces are kept untouched.
• Other unused CSS is left alone. It does not remove unused @keyframes, @font-face, @property, custom properties (--my-color) or declarations inside a rule.
• It does not check whether a rule has any effect. A rule that is always overridden by another still counts as used if its classes are on a page.
• Inline style="" attributes are not part of the comparison.

A safe workflow

1. Run it and read the warnings. If pages failed or the page limit was reached, fix that first (raise --max-pages, lower --concurrency, add --delay).
2. Scan the list for things you recognise. Anything you know is used goes on the safelist. Pay attention to modals, menus, forms, alerts and anything JavaScript touches.
3. Run again with your safelist. Repeat until the list holds only classes you are happy to lose.
4. Write the cleaned files with --purge. Put them on a test copy of the site, not the live one.
5. Click through the test site. Open menus, trigger errors, try forms and view it logged in and out, on a phone and a desktop. The crawler cannot do these things; you can.
6. Deploy, and keep the originals. Keep a backup of the old CSS so you can roll back quickly.

Troubleshooting

Responsible use

Only scan sites you own or have permission to test. Leave robots.txt checking on unless the site is yours, and pick a speed your server can handle. This script is released under the MIT License, so you are free to use, copy and modify it. The source code is on GitHub, where you can also report bugs and suggest improvements. It is provided as is, with no warranty. Always keep a backup of your CSS before you change anything.