Question
Hugo extended vs standard binary: which edition should CI standardize on for Sass and WebP?
Ira Indigo
0 reputation · 04 Apr 2025, 07:41 UTC
86.8K views
Loading…
0 reputation · 04 Apr 2025, 07:41 UTC
Our Hugo site is growing, and we keep hitting the same fork in the road: some features only work with the extended binary. SCSS compilation through Hugo Pipes (resources.ToCSS) requires the embedded Sass transpiler that ships only in the extended edition, and WebP encoding in the image pipeline is documented as extended-only as well (standard builds can decode WebP but not produce it).
The awkward part is that this is a hard build dependency, not a graceful degradation: a template calling a Sass- or WebP-dependent function under the standard binary fails the build outright. Meanwhile, our install sources differ — some developers get Hugo via a package manager, CI uses a Docker image, and deploy previews use yet another channel — and these channels do not all default to the same edition. We can detect the edition with hugo version output or hugo.IsExtended in templates, but detection is not a policy.
We want one consistent rule across local development, CI, and preview builds, without pinning to an edition that silently limits which themes or features we can adopt later.
Is there a documented downside (size, licensing, platform availability) to simply standardizing every environment on the extended binary? If we instead pin the standard binary, what is the most reliable way to make Sass/WebP usage fail early and loudly in CI rather than at deploy time? Does the edition requirement vary meaningfully across recent Hugo versions in a way we should encode in our version pinning?
32275 reputation · 04 Apr 2025, 11:24 UTC
Standardize every environment — local, CI, preview — on the Hugo Extended binary. Both Sass/SCSS compilation via resources.ToCSS and WebP encoding in the image pipeline are hard requirements that only the Extended edition satisfies. The Standard binary will fail the build outright when templates call those functions.
sass
hugohugo formula installs Extended by default), Chocolatey, Scoop, and most Linux package managers provide Extended for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, and windows/amd64. The only gap is some distro default repositories (e.g., older Debian/Ubuntu) that may ship only Standard or an outdated Extended — avoid those by pulling from the official releases or a maintained third-party tap.Add a guarded step that aborts before the build runs:
# CI script (bash example)
if ! hugo version | grep -q extended; then
echo "ERROR: Hugo Standard detected. This project requires Extended for Sass/WebP."
exit 1
fiAlternatively, place a sentinel partial that runs {{ if not hugo.IsExtended }}{{ errorf "Extended binary required" }}{{ end }} in baseof.html so the build fails with a clear message during template execution.
Since Hugo 0.78.0 (October 2021), the Extended edition has consistently used Dart Sass (libsass was removed). No recent version has changed the edition requirement for Sass or WebP encoding. Pin a specific Extended version (e.g., v0.128.0) in your CI Dockerfile or install script; the edition suffix is stable across patch releases.
hugo version — output must contain +extended (e.g., hugo v0.128.0+extended linux/amd64).test.scss and confirm hugo produces CSS without error.{{ $img := resources.Get "test.jpg" | images.Filter "webp" }} in a template; build should emit a .webp file.resources.ToCSS or WebP filters. If neither is used today, Standard is sufficient — but future theme changes may reintroduce the dependency silently.apt install hugo on Ubuntu 22.04 installs Standard; snap install hugo installs Extended. Document the exact install command per platform.Use comments to ask for clarification. Post a solution as an answer.
32,275 reputation · 04 Apr 2025, 19:33 UTC
One clarification on pinning Standard: a hugo.IsExtended guard can pass CI while still shipping a degraded site if templates conditionally skip Sass or WebP when the capability is absent. Instead, add a minimal fixture site that actually invokes resources.ToCSS on a real .scss file and performs the WebP-producing image operation your theme uses. Run that fixture before the main build and require success.
This separates edition detection from pipeline verification. The extended/standard split itself is stable across Hugo versions, but Sass syntax support and image-format behavior can change with the underlying transpiler or libvips. Pin the exact Hugo version, then test your actual stylesheets and images rather than inferring capability from semver.