Clean a Hugo Module Without Losing Dependency Intent

You will finish with a tidier Hugo module whose go.mod and go.sum contain only dependency data needed by the site. The examples match the installed Hugo v0.123.7 package. Allow about ten minutes, plus time to review the diff. You need a shell, a Hugo site that uses modules, and permission to edit that site's files.

1. Move to the Hugo project root

Run the command from the directory containing the site's go.mod. Replace the placeholder with the real path; do not run it from a parent directory and assume Hugo will find the intended site.

$ 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 have a site configuration file such as hugo.yaml, hugo.toml or hugo.json. The module configuration imports components, themes or other Hugo modules; 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 allowing anything to be 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 are already modified, stop and either commit that work or save it elsewhere first. Tidy combines with the current files, so an unnoticed earlier edit can make its diff difficult to review.

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. The command may need to inspect the module graph and download metadata, so network access and a usable Go toolchain may be required. A successful run can be quiet. Silence is not a promise that no file changed.

For the installed binary, confirm the version if you are 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 can differ on another machine. Hugo's current documentation also lists the same basic command, but newer releases can expose additional flags. Use the help output from the binary you are actually running, not a copied option list.

4. Review exactly what changed

Inspect the diff immediately after tidy:

$ 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 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 that your normal build exercises.

Run a site build as a separate verification step. It reads the module graph and exercises the imports that matter to the site:

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

The 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 Hugo workflow before running it in a working tree. If your site has a project-specific build command, use that as well.

5. Recover if tidy removed a required entry

Do not manually add a checksum because a build failed. First capture the error and identify which module or import is missing. If the tidy diff is the only change and the files were committed beforehand, restore just those files:

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

The second command should print nothing. On a project without Git, copy your saved backups back into place instead. If other edits existed before tidy, do not use the Git command until you have preserved them. A broad reset could discard unrelated work.

After recovery, check the Hugo module configuration and the module's 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 from which Hugo reads files, --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 flags select the site context; they do not turn tidy into an upgrade command.

For a project whose root is not the current directory, make the path explicit and then 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 reports that it cannot find configuration or module files, stop and correct the path rather than creating new files in the wrong directory.