Clear Hugo's Module Cache Without Touching Your Project

hugo mod clean wipes Hugo's cached module files without laying a finger on your actual project. You will clear the current project's cache, target just matching module paths, and know when you have reached for the --all option that empties every project's cache at once. The installed command is Hugo 0.123.7, from the Ubuntu package on this machine.

Allow about ten minutes. You need Hugo installed and a Hugo project, or at least its directory and configuration. The normal commands are unprivileged; use sudo only if the cache directory belongs to another account, and fix ownership rather than making a habit of running Hugo as root.

1. Confirm the installed command

Run this from any directory before trusting a flag from a different Hugo release:

$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2
$ hugo mod clean --help
Delete the Hugo Module cache for the current project.

This is a subcommand of hugo; there is no separate hugo-mod-clean executable. The local manual gives the syntax as hugo mod clean [flags] [args].

2. Start with the current project's cache

Change into the project whose cached modules you want gone. The command uses the current project context, so the directory matters:

$ cd /path/to/my-hugo-site
$ hugo mod clean
$ printf 'exit status: %s\n' "$?"
exit status: 0

Swap in the directory containing your Hugo configuration, such as hugo.yaml, hugo.json or hugo.toml. A zero exit status means it completed; there is normally no other success report, so the exit status is the main thing to check.

This clears the Module cache tied to the current project. It does not remove your content, layouts, themes, configuration or repository history. It may force the next build to download module data again, so do not schedule it right before a build that has to work offline.

3. Target a cache directory explicitly when paths are unclear

Use --cacheDir when the project uses a non-default cache location, or you want the command unambiguous inside a script:

$ hugo mod clean \
    --cacheDir /path/to/hugo-cache
$ printf 'exit status: %s\n' "$?"
exit status: 0

The path is a filesystem path, not a URL. Check it exists before deleting anything:

$ test -d /path/to/hugo-cache && printf 'cache directory exists\n'
cache directory exists
$ hugo mod clean --cacheDir /path/to/hugo-cache

If you are unsure which cache directory Hugo actually uses, inspect your project and wrapper scripts first. Never substitute a broad directory such as /, /home or a shared build root just because the command happens to accept a path.

4. Clean only matching modules

When one dependency looks suspect, use --pattern instead of wiping every cached module for the project:

$ cd /path/to/my-hugo-site
$ hugo mod clean --pattern '*example*'
$ printf 'exit status: %s\n' "$?"
exit status: 0

Swap *example* for a pattern matching the module path you want removed, and quote it so the shell does not expand those asterisks against files in your current directory. Without --pattern, the manual says every module path for the current project is selected. A pattern narrows the selection; it does not update, tidy or verify the dependency.

In a script, make the selected value visible before running the command:

$ MODULE_PATTERN='*github.com/example/*'
$ printf 'cleaning module pattern: %s\n' "$MODULE_PATTERN"
cleaning module pattern: *github.com/example/*
$ hugo mod clean --pattern "$MODULE_PATTERN"

If the pattern matches nothing, do not treat a quiet successful exit as proof a particular module was present, or removed. Follow up with whatever build or module command exposed the problem in the first place.

5. Know what --all changes

The broad form:

$ hugo mod clean --all
$ printf 'exit status: %s\n' "$?"
exit status: 0

--all cleans the entire Hugo module cache, not just this project's slice of it. Hugo's own module documentation describes it as cleaning the cache for all projects. Use it when you have a deliberate reason to reset shared cached module state, such as investigating a cache-wide problem or clawing back disk space.

6. Verify the result with the operation that matters

Do not rely on silence in the terminal as your only test. Run the next safe operation for your project, such as a build:

$ cd /path/to/my-hugo-site
$ hugo
Start building sites ...
                   | EN
-------------------+----
Pages            | 1
Total            | 1

The build summary varies with the site and Hugo version, so treat it as illustrative. What matters is a zero exit status and the expected generated output. If the build fails while resolving a module, check network access, the module version in your configuration, and any _vendor directory: cleaning never repaired dependency metadata, changed versions, or conjured a missing module out of nowhere.

For a cache-only investigation, note the cache directory and pattern you used, then rerun the failing command with --verbose or --debug if its help output lists those global flags. They add diagnostics; they do not widen or narrow what gets deleted.