I upgraded a Hugo site to Tailwind v4 last week, ran hugo server, and got nothing. Not an error, not a crash — just completely unstyled HTML sitting there like the CSS file had never been written. I checked the network tab, the file was loading fine, it just had none of my classes in it. Spent a good hour assuming I’d broken something in my markup before I figured out the actual problem: Tailwind v4 and Hugo aren’t incompatible, they just stopped agreeing on how configuration even works.
Why the Silence Happens #
Tailwind v4 dropped tailwind.config.js entirely. Configuration now lives inside the CSS file itself — @import "tailwindcss";, @theme blocks, @source directives — all CSS-native, processed through Lightning CSS instead of the old PostCSS pipeline. Hugo, meanwhile, runs its own virtual asset mount layer through resources.Get, and if your relative paths don’t resolve exactly where the Tailwind CLI expects them during that pass, you don’t get an error — you get silence. No styles, no complaint, just a build that technically succeeded and did nothing.
The other half of the problem is content detection. Tailwind v4 scans for class usage automatically, but it can only scan what it can see. If it’s not pointed at wherever Hugo is actually rendering your classes, your shortcodes and templates stay invisible to it no matter how correct your syntax is.
Step 1: Install the Real CLI #
As of Hugo 0.161.0, the old standalone Tailwind binary isn’t supported anymore — css.TailwindCSS talks to the official CLI directly. Get it installed:
npm install --save-dev tailwindcss @tailwindcss/cliStep 2: Fix the CSS Entry File #
No more @tailwind base; / @tailwind components; / @tailwind utilities; — that syntax is gone in v4. Your entry file needs the new CSS-first format:
@import "tailwindcss";
@import "./components/buttons.css";
@import "./components/cards.css";
@theme {
--font-sans: "Inter", system-ui, sans-serif;
--color-brand-dark: #09090b;
}
@source "hugo_stats.json";That last line is where most guides go wrong, and it’s not a small miss — pointing @source at ../../layouts or ../../content doesn’t actually work, because Tailwind isn’t scanning your source templates directly in this pipeline. It’s reading the compiled class list Hugo generates after a build, which lives in hugo_stats.json. Point @source there instead, and the scanner finds every class your templates actually rendered, not just what’s sitting in your layout files pre-render.
One real gotcha worth keeping in mind on relative paths: ./ resolves relative to the file it’s written in. If your CSS lives in assets/css/main.css, then ./components/buttons.css has to physically sit at assets/css/components/buttons.css. Let Hugo’s pipe processing move that hierarchy around on you and the import just breaks.
Step 3: Wire Up the Partial #
{{ $css := resources.Get "css/main.css" }}
{{ if $css }}
{{ $opts := dict "minify" (not hugo.IsDevelopment) }}
{{ $styles := $css | css.TailwindCSS $opts | fingerprint }}
<link rel="stylesheet" href="{{ $styles.RelPermalink }}" integrity="{{ $styles.Data.Integrity }}" crossorigin="anonymous">
{{ end }}Nothing exotic here. css.TailwindCSS is the native Hugo function, no PostCSS glue needed.
Step 4: Configure hugo.toml Correctly #
This is the part most guides get wrong. Getting hugo_stats.json to trigger a rebuild when your templates change requires a module mount, not just a cachebuster rule on its own — the file has to be explicitly watched, or edits to your templates won’t invalidate the CSS cache and you’ll be staring at stale styles wondering why your new class isn’t showing up:
[[module.mounts]]
source = "assets"
target = "assets"
[[module.mounts]]
source = "hugo_stats.json"
target = "assets/notwatching/hugo_stats.json"
disableWatch = true
[build]
[build.buildStats]
enable = true
[[build.cachebusters]]
source = 'assets/notwatching/hugo_stats\.json'
target = 'css'
[[build.cachebusters]]
source = '(postcss|tailwind)\.config\.js'
target = 'css'That buildStats.enable = true block is the current config key — older write-ups still reference writeStats = true, which was the setting before Hugo restructured this under build.buildStats. If you’re on an older Hugo version that one still works, but on anything recent you want buildStats.enable.
The .gitignore trap is real and worth repeating: Tailwind respects .gitignore. If hugo_stats.json is ignored in your repo, Tailwind silently skips it in production builds, and you get missing utility classes with zero indication why. Either track the file or make sure your @source directive is explicitly pulling it in regardless.
Step 5: Security Config, and a Recent Warning #
Hugo’s security policy restricts which external executables it’s allowed to run, and depending on your version, Tailwind might not be on that list by default — you’ll get an “access denied, not whitelisted in policy” error the first time it tries to invoke the CLI. Fix is explicit:
[security.exec]
allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^git$', '^node$', '^postcss$', '^tailwindcss$']
[security.node.permissions]
allowRead = ['.', 'assets', 'node_modules']Here’s the part worth actually paying attention to if you’re setting this up right now: Hugo versions 0.162.0 through 0.164.x shipped with tailwindcss included by default in the Node permission list that grants --allow-child-process, and because Tailwind’s config loading can execute arbitrary code at startup, that combination opened a real remote-code-execution path — tracked as CVE-2026-75926. It’s patched as of Hugo 0.165.0, which pulled tailwindcss out of that default list entirely. If you’re not already on 0.165.0 or later, update first — don’t just copy the security block above and assume you’re covered, the vulnerable versions had the dangerous default already baked in before you touch your config at all.
The whole mess — the silent builds, the invisible classes, the config errors — comes down to the same root cause every time: Tailwind v4 and Hugo each moved to their own new way of describing “where’s the config, where’s the content,” and neither one updated to match the other automatically. Match the paths by hand, point @source at the stats file instead of your raw layouts, mount hugo_stats.json so it’s actually watched, and the pipeline stops going quiet on you.