Update Hugo Module Dependencies Without Losing the Graph

hugo mod get pulls in a new module, bumps one version, or updates everything at once, and each of those has a different blast radius. The examples use Hugo 0.123.7, the installed version on this machine. Allow about fifteen minutes for a small project, plus download time for the module cache.

You need a Hugo project, a writable working tree, Git, and Go at whatever version your Hugo setup requires. Run these commands as the project owner. hugo mod get changes project dependency files, so skip sudo: it can leave go.mod and go.sum owned by root and hide the change from the environment that actually needs it.

1. Start from a recoverable project state

Change into the Hugo project and check its module files before resolving anything:

$ cd /path/to/my-hugo-site
$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2
$ git status --short
$ ls -l go.mod go.sum 2>/dev/null

The version line is host-specific beyond the installed Hugo release itself. An empty git status is a useful checkpoint: it makes whatever this operation changes easy to spot. If the project is not already a Go module, initialise it with your normal module workflow first; Hugo's documentation covers hugo mod init for that step.

2. Add one module at the latest permitted version

Pass the module path as an argument, the form the installed command documents:

$ hugo mod get github.com/gohugoio/testshortcodes

Hugo resolves the dependency in the current project and updates the module files as needed. Exact output depends on the module graph and the network cache, so treat the changed files and exit status as the reliable result; a successful exit status is zero.

Review the change straight away:

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

Keep the diff if it is the change you wanted. If it is not, and the files were clean before you started, restore just the unwanted files from version control:

$ git restore -- go.mod go.sum

3. Request an exact module version

Append an @ version to the module path when reproducibility matters:

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

The version has to be one the module actually provides. Hugo hands version selection off to the Go module machinery, so a missing tag, an unavailable revision or an incompatible dependency can all produce a non-zero exit status. Do not swap a failed version request for an arbitrary newer tag; check the module's release information and your project's compatibility needs first.

Verify what actually got selected rather than guessing from the command line:

$ grep 'github.com/gohugoio/testshortcodes' go.mod go.sum
$ git diff --check
$ git diff -- go.mod go.sum

A go.mod entry describes the selected requirement. A matching checksum in go.sum records downloaded module content. Exact lines vary between projects, and an indirect requirement can be added or changed as part of the graph.

4. Update direct dependencies only

With no module argument, hugo mod get installs the latest possible versions for direct module dependencies:

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

For a recursive update across the project's module packages, use the documented ./... argument:

$ hugo mod get ./...

The recursive form can pick up more than the one dependency you had in mind. Read the full diff before committing it, and keep the command without -u when your aim is just the direct dependency set the project already describes.

5. Update indirect dependencies deliberately

Add -u when you actually intend to update dependencies beyond the direct requirements:

$ hugo mod get -u
$ git diff --stat -- go.mod go.sum
$ git diff -- go.mod go.sum

For a recursive update of every module dependency:

$ hugo mod get -u ./...

This is a much broader change than adding one module. It can expose incompatibilities in themes, mounts or templates, and it can make a later rollback less obvious once several files have moved at once. Run your normal build or test command after reviewing the diff. If the build fails, save the error, then restore the exact dependency changes only once you have confirmed no other work got mixed into those files.

6. Understand which source Hugo resolves first

Hugo starts by resolving the components declared in the site configuration. Its documented order runs: a _vendor directory, unless the matching vendor path is ignored, then Go Modules, then a folder inside the themes directory. Which means an apparently successful module update might not touch the files Hugo actually uses, if a vendored component takes precedence.

Inspect the project before diagnosing a version problem:

$ find . -maxdepth 2 -type d \( -name _vendor -o -name themes \) -print
$ grep -nE 'module|imports|mounts|vendor' go.mod hugo.yaml hugo.toml hugo.json 2>/dev/null

The configuration filename and module declarations vary. Do not delete _vendor or reach for --ignoreVendorPaths as a first troubleshooting move: vendoring is a project policy decision, and it can affect builds for every contributor.

7. Verify the finished dependency change

Run the project's normal validation command, then check the working tree holds only what you expect:

$ hugo --source /path/to/my-hugo-site --destination /tmp/hugo-check build
$ git status --short
$ git diff --check

The destination above is a disposable example; pick a safe temporary directory, never a production document root. A build exit status of zero shows this Hugo invocation can resolve and render the project. It does not prove every page or deployment integration is correct, so keep the project's own tests and preview checks in the workflow.

If dependency resolution fails, keep the error output and check Git, Go, network access, the module path, and the project's module configuration. A failed command can still have changed a module file before it reported the later error, so use git diff -- go.mod go.sum to check that case before deciding whether to keep or restore anything.