Clean a Hugo Module Without Losing Dependency Intent

hugo mod tidy strips unused entries out of go.mod and go.sum so your module's dependency list matches what the site actually uses. The examples match the installed Hugo v0.123.7 package. Allow about ten minutes, plus time to review the diff, a shell, a Hugo site that uses modules, and permission to edit its files.

1. Move to the Hugo project root

Run the command from the directory containing the site's go.mod. Swap in the real path; don't run it from a parent directory and assume Hugo will find the right site on its own.

$ cd /path/to/my-hugo-site
$ pwd
/path/to/my-hugo-site
$ test -f go.mod && echo 'go.mod found'

You should see the project directory followed by go.mod found. Hugo module projects normally also carry a site configuration file such as hugo.yaml, hugo.toml or hugo.json. The module configuration imports components, themes or other Hugo modules, and Go records their versions and checksums in go.mod and go.sum.

2. Inspect the pending change

Check the repository state and read the module files before letting anything get rewritten.

$ git status --short -- go.mod go.sum
$ sed -n '1,200p' go.mod
$ if test -f go.sum; then sed -n '1,80p' go.sum; else echo 'go.sum is not present'; fi

An empty status result means those two tracked files have no uncommitted changes. If they're already modified, stop and either commit that work or save it elsewhere first: tidy combines with the current files, so an unnoticed earlier edit makes the resulting diff much harder to read.

3. Run hugo mod tidy

Run the subcommand without extra flags:

$ hugo mod tidy

The installed manpage describes this as removing unused entries in go.mod and go.sum. It may need to inspect the module graph and download metadata, so network access and a working Go toolchain can both be required. A quiet run is normal, but silence is not a promise that nothing changed.

Confirm the version if you're recording a build or troubleshooting result:

$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2

Your build date or vendor suffix will differ on another machine. Hugo's current documentation lists the same basic command, but newer releases can expose extra flags, so use the help output from the binary you're actually running rather than a copied option list.

4. Review exactly what changed

Check the diff immediately after tidy runs:

$ git diff -- go.mod go.sum
$ git status --short -- go.mod go.sum

Ordinary tidy output should be limited to dependency declarations and checksum lines. Read the removed entries rather than approving the diff by line count: a module that looks unused to Go may still be required by a Hugo module import, a theme, a replacement, or a configuration path your normal build exercises.

Run a site build as a separate check. It reads the module graph and exercises the imports that actually matter:

$ hugo --quiet
$ echo "$?"
0

That 0 is the expected status for a successful build. The build can write generated files to the project's configured destination, so check your normal workflow before running this inside a working tree you care about.

5. Recover if tidy removed a required entry

Don't manually add a checksum back in because a build failed. Capture the error first and identify which module or import is actually missing. If the tidy diff is the only change and the files were committed beforehand, restore just those two files:

$ git restore -- go.mod go.sum
$ git status --short -- go.mod go.sum

After recovery, check the Hugo module configuration and the module's own documentation. Add or correct the actual import first, then run hugo mod tidy again and review the new diff. Tidy cleans the graph; it does not infer an undocumented dependency from an intention written only in a comment or a deployment script.

6. Know which flags change the context

The installed command accepts --source (or -s) for the filesystem path Hugo reads from, --config for a configuration file, --configDir for the configuration directory, --contentDir for the content directory, --cacheDir for the cache, --theme (or -t) for themes, and --baseURL (or -b) for the site's root URL. These select the site context; none of them turn tidy into an upgrade command.

For a project whose root isn't the current directory, make the path explicit and review the same files:

$ hugo mod tidy --source /path/to/my-hugo-site
$ git -C /path/to/my-hugo-site diff -- go.mod go.sum

Use the exact path to the intended project. A common trap is pointing --source at a content directory instead of the module root. If Hugo says it can't find configuration or module files, stop and fix the path rather than creating new files in the wrong place.