Manage Hugo Module Dependencies Without Losing Track of Them

This guide takes a Hugo site from an ordinary project directory to a checked, inspectable Hugo Module setup. You will initialise the module, add a dependency, inspect the graph, tidy the Go metadata, verify the downloaded source and optionally vendor it locally. Allow 10 to 20 minutes for a small site, plus download time for any modules you add.

The examples target the installed Hugo 0.123.7, built on 17 March 2026. Run them from the directory containing your site's hugo.yaml, hugo.toml or hugo.json. These commands change project files or the module cache. Commit or copy your work before changing dependency versions.

Before you start

1. Check the tools and project directory.

$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2
$ command -v go
/usr/bin/go
$ command -v git
/usr/bin/git
$ pwd
/home/you/src/my-site

Your paths and Hugo build metadata will differ. The parent hugo mod command says that most operations need Go 1.12 or newer and a relevant version-control client, usually Git. You do not need those tools for a site that only uses modules inside themes, or for a project that already vendors its modules.

1. Initialise the project as a module

Initialisation creates the Go module metadata Hugo uses for dependency resolution. Give Hugo the real module path when the directory name does not make the path obvious:

$ hugo mod init example.com/acme/my-site
go: creating new go.mod: module example.com/acme/my-site

The path is an identifier, not a download command. Use the path where this project is published or consumed, such as your Git hosting path. Hugo can try to guess it when you omit the argument, but an explicit value avoids a later rename.

Inspect the result before doing anything else:

$ sed -n '1,40p' go.mod
module example.com/acme/my-site

go 1.XX

The Go directive is generated by the installed toolchain and may vary. If go.mod already exists, stop and read it rather than running initialisation casually. The command is for establishing a module, not for repairing an existing dependency file.

2. Add one dependency at a time

Use hugo mod get to resolve a module. This example uses Hugo's documented test module as a visible placeholder. Replace it with a real module that your site needs:

$ hugo mod get github.com/gohugoio/testshortcodes
go: added github.com/gohugoio/testshortcodes v0.3.0

The exact version and messages depend on the module's available releases. To request a particular version, append its version:

$ hugo mod get github.com/gohugoio/[email protected]

For repeatable work, prefer a reviewed version or tag over an unbounded update. hugo mod get updates the module files and downloads source into Hugo's cache. It does not make a module part of the site's visible output until your configuration mounts or uses its components.

Update direct dependencies deliberately. The following asks for the latest possible versions of direct dependencies, while ./... also processes module paths recursively:

$ hugo mod get -u
$ hugo mod get -u ./...

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

3. Inspect the dependency graph

Run the graph command from the module directory:

$ hugo mod graph
example.com/acme/my-site github.com/gohugoio/[email protected]

Each line describes a parent and dependency. The real graph may include indirect modules, replacement information, disabled modules and an in-themesdir entry. For a vendored dependency, the graph reports the version found in the vendor tree, which may not be the version written in go.mod.

If the graph fails, check that you ran it from the intended module tree and that the module path in the project configuration matches the files you inspected. Use the inherited --config, --configDir, --themesDir and --source options only when your site deliberately keeps those locations elsewhere.

4. Tidy and verify the downloaded source

Once the site builds with the intended components, remove unused entries from the Go metadata:

$ hugo mod tidy
$ git diff -- go.mod go.sum

Tidy can remove entries that looked useful but are no longer needed by the current module graph. Review its diff. It is a project-file change, so it does not need root privileges.

Then check that cached dependencies have not been modified since download:

$ hugo mod verify
all modules verified

Successful output can vary, but the command should exit with status 0. A verification failure means the local cached source does not match its recorded checksums. Investigate the cache and the machine before using the cleanup option. hugo mod verify --clean deletes the module cache entries for dependencies that fail verification; that is reversible by downloading them again, but it may require network access and should not be used as a substitute for understanding unexpected changes.

5. Vendor when you need a repository-local copy

Vendoring copies imported module dependencies into _vendor in the project. Hugo will prefer that directory when resolving components, so it gives builds a local copy that can be inspected and committed:

$ hugo mod vendor
$ find _vendor -maxdepth 2 -type f | head
$ git status --short

Do not edit files inside _vendor as a first choice. To override a vendored file, create the corresponding path in the project root, as documented by Hugo. Modules below themes are not vendored.

When local edits need to be seen instead of the vendored copy, the parent command's --ignoreVendorPaths option can ignore matching vendor paths. Use a narrow glob for a known module, not a blanket setting whose effect you have not tested.

6. Clean the cache only with a reason

hugo mod clean deletes the Hugo Module cache for the current project. It is useful when a cache is damaged or you need to force a fresh download, but it can make the next build slower and network-dependent:

$ hugo mod clean
$ hugo mod verify

The --pattern option narrows the cleanup to matching module paths. --all cleans the entire module cache, not just this project, so treat it as a maintenance action. Neither operation needs elevated privileges when the cache belongs to your user. Do not use sudo: changing ownership of the cache can create a second, harder-to-diagnose failure.

7. Run the final build

Resolve the site once more and build it to a disposable destination before committing dependency changes:

$ rm -rf /tmp/hugo-module-preview
$ hugo --destination /tmp/hugo-module-preview
Start building sites ...
                     | EN
---------------------+----
Pages                |  1
Total                |  1

The page counts and timing depend on the site. The disposable destination is safe to remove after inspection. If the build fails, read the first module or mount error, compare hugo mod graph with your configuration, and restore the last known-good dependency files before retrying.