Configure modules

Configure modules.

Hugo Modules are Go Modules

You need Go version 1.18 or later and Git to use Hugo Modules. For older sites hosted on Netlify, please ensure the GO_VERSION environment variable is set to 1.18 or higher.

Go Modules resources:

Top-level options

This is the default configuration:

module:
  noProxy: none
  noVendor: ''
  private: '*.*'
  proxy: direct
  vendorClosest: false
  workspace: 'off'

[module]
  noProxy = 'none'
  noVendor = ''
  private = '*.*'
  proxy = 'direct'
  vendorClosest = false
  workspace = 'off'

{
   "module": {
      "noProxy": "none",
      "noVendor": "",
      "private": "*.*",
      "proxy": "direct",
      "vendorClosest": false,
      "workspace": "off"
   }
}

auth

New in v0.144.0

(string) Configures GOAUTH when running the Go command for module operations. This is a semicolon-separated list of authentication commands for go-import and HTTPS module mirror interactions. This is useful for private repositories. See go help goauth for more information.

noProxy

(string) A comma-separated list of glob patterns matching paths that should not use the configured proxy server.

noVendor

(string) A glob pattern matching module paths to skip when vendoring.

private

(string) A comma-separated list of glob patterns matching paths that should be treated as private.

proxy

(string) The proxy server to use to download remote modules. Default is direct, which means git clone and similar.

replacements

(string) Primarily useful for local module development, a comma-separated list of mappings from module paths to directories. Paths may be absolute or relative to the themesDir.

module:
  replacements: github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path

[module]
  replacements = 'github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path'

{
   "module": {
      "replacements": "github.com/bep/my-theme -\u003e ../..,github.com/bep/shortcodes -\u003e /some/path"
   }
}

vendorClosest

(bool) Whether to pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined. Default is false.

workspace

(string) The Go workspace file to use, either as an absolute path or a path relative to the current working directory. Enabling this activates Go workspace mode and requires Go 1.18 or later. The default is off.

You may also use environment variables to set any of the above. For example:

export HUGO_MODULE_PROXY="https://proxy.example.org"
export HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."
export HUGO_MODULE_WORKSPACE="/my/hugo.work"

Hugo version

You can specify a required Hugo version for your module in the module section. Users will then receive a warning if their Hugo version is incompatible.

This is the default configuration:

module:
  hugoVersion:
    extended: false
    max: ''
    min: ''

[module]
  [module.hugoVersion]
    extended = false
    max = ''
    min = ''

{
   "module": {
      "hugoVersion": {
         "extended": false,
         "max": "",
         "min": ""
      }
   }
}

You can omit any of the settings above.

extended: (bool) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition.
max: (string) The maximum Hugo version supported, for example 0.153.0.
min: (string) The minimum Hugo version supported, for example 0.102.0.

Imports

module:
  imports:
  - disable: false
    ignoreConfig: false
    ignoreImports: false
    path: github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v
  - path: my-shortcodes

[module]
  [[module.imports]]
    disable = false
    ignoreConfig = false
    ignoreImports = false
    path = 'github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v'
  [[module.imports]]
    path = 'my-shortcodes'

{
   "module": {
      "imports": [
         {
            "disable": false,
            "ignoreConfig": false,
            "ignoreImports": false,
            "path": "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
         },
         {
            "path": "my-shortcodes"
         }
      ]
   }
}

disable: (bool) Whether to disable the module but keep version information in the go.* files. Default is false.
ignoreConfig: (bool) Whether to ignore module configuration files, for example, hugo.toml. This will also prevent loading of any transitive module dependencies. Default is false.
ignoreImports: (bool) Whether to ignore module imports. Default is false.
noMounts: (bool) Whether to disable directory mounting for this import. Default is false.
noVendor: (bool) Whether to disable vendoring for this import. This setting is restricted to the main project. Default is false.
path: (string) The module path, either a valid Go module path (e.g., github.com/gohugoio/myShortcodes) or the directory name if stored in the themesDir.
version: New in v0.150.0; If set to a version query, this import becomes a direct dependency, in contrast to dependencies managed by Go Modules. See this issue for more information.

Mounts

A mount is a configuration object that maps a file system path (source) to a component path (target) within Hugo’s unified file system.

If you define one or more mounts to map a file system path to a component path, do not use these legacy configuration settings: archetypeDir, assetDir, contentDir, dataDir, i18nDir, layoutDir, or staticDir.

Default mounts

Within a project, if you define a mount to map a file system path to a component path, the corresponding default mount for that component will be removed. This action essentially overwrites the standard, automatic mapping for that specific component with your custom one.

Within a module, if you define a mount to map a file system path to a component path, all of the default mounts will be removed. Defining a mount at the module level is a more sweeping change, causing all default mappings within that module to be discarded.

In either case, if you still need one of the default mounts, you must explicitly add it along with the new mount. Because custom mounts override defaults, any necessary default mappings must be re-added manually after you introduce your custom configuration.

These are the default mounts:

module:
  mounts:
  - disableWatch: false
    files: null
    sites:
      complements:
        languages: null
        roles: null
        versions: null
      matrix:
        languages: null
        roles: null
        versions: null
    source: content
    target: content
  - disableWatch: false
    files: null
    sites:
      complements:
        languages: null
        roles: null
        versions: null
      matrix:
        languages: null
        roles: null
        versions: null
    source: data
    target: data
  - disableWatch: false
    files: null
    sites:
      complements:
        languages: null
        roles: null
        versions: null
      matrix:
        languages: null
        roles: null
        versions: null
    source: layouts
    target: layouts
  - disableWatch: false
    files: null
    sites:
      complements:
        languages: null
        roles: null
        versions: null
      matrix:
        languages: null
        roles: null
        versions: null
    source: i18n
    target: i18n
  - disableWatch: false
    files: null
    sites:
      complements:
        languages: null
        roles: null
        versions: null
      matrix:
        languages: null
        roles: null
        versions: null
    source: archetypes
    target: archetypes
  - disableWatch: false
    files: null
    sites:
      complements:
        languages: null
        roles: null
        versions: null
      matrix:
        languages: null
        roles: null
        versions: null
    source: assets
    target: assets
  - disableWatch: false
    files: null
    sites:
      complements:
        languages: null
        roles: null
        versions: null
      matrix:
        languages: null
        roles: null
        versions: null
    source: static
    target: static

[module]
  [[module.mounts]]
    disableWatch = false
    source = 'content'
    target = 'content'
    [module.mounts.sites]
      [module.mounts.sites.complements]
      [module.mounts.sites.matrix]
  [[module.mounts]]
    disableWatch = false
    source = 'data'
    target = 'data'
    [module.mounts.sites]
      [module.mounts.sites.complements]
      [module.mounts.sites.matrix]
  [[module.mounts]]
    disableWatch = false
    source = 'layouts'
    target = 'layouts'
    [module.mounts.sites]
      [module.mounts.sites.complements]
      [module.mounts.sites.matrix]
  [[module.mounts]]
    disableWatch = false
    source = 'i18n'
    target = 'i18n'
    [module.mounts.sites]
      [module.mounts.sites.complements]
      [module.mounts.sites.matrix]
  [[module.mounts]]
    disableWatch = false
    source = 'archetypes'
    target = 'archetypes'
    [module.mounts.sites]
      [module.mounts.sites.complements]
      [module.mounts.sites.matrix]
  [[module.mounts]]
    disableWatch = false
    source = 'assets'
    target = 'assets'
    [module.mounts.sites]
      [module.mounts.sites.complements]
      [module.mounts.sites.matrix]
  [[module.mounts]]
    disableWatch = false
    source = 'static'
    target = 'static'
    [module.mounts.sites]
      [module.mounts.sites.complements]
      [module.mounts.sites.matrix]

{
   "module": {
      "mounts": [
         {
            "disableWatch": false,
            "files": null,
            "sites": {
               "complements": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               },
               "matrix": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               }
            },
            "source": "content",
            "target": "content"
         },
         {
            "disableWatch": false,
            "files": null,
            "sites": {
               "complements": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               },
               "matrix": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               }
            },
            "source": "data",
            "target": "data"
         },
         {
            "disableWatch": false,
            "files": null,
            "sites": {
               "complements": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               },
               "matrix": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               }
            },
            "source": "layouts",
            "target": "layouts"
         },
         {
            "disableWatch": false,
            "files": null,
            "sites": {
               "complements": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               },
               "matrix": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               }
            },
            "source": "i18n",
            "target": "i18n"
         },
         {
            "disableWatch": false,
            "files": null,
            "sites": {
               "complements": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               },
               "matrix": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               }
            },
            "source": "archetypes",
            "target": "archetypes"
         },
         {
            "disableWatch": false,
            "files": null,
            "sites": {
               "complements": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               },
               "matrix": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               }
            },
            "source": "assets",
            "target": "assets"
         },
         {
            "disableWatch": false,
            "files": null,
            "sites": {
               "complements": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               },
               "matrix": {
                  "languages": null,
                  "roles": null,
                  "versions": null
               }
            },
            "source": "static",
            "target": "static"
         }
      ]
   }
}

source: (string) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative.
target: (string) Where the mount will reside within Hugo’s unified file system. It must begin with one of Hugo’s component directories: archetypes, assets, content, data, i18n, layouts, or static. For example, content/blog.
disableWatch: New in v0.128.0; (bool) Whether to disable watching in watch mode for this mount. Default is false.
files: New in v0.153.0; (string or []string) A glob slice defining the files to include or exclude.
sites: New in v0.153.0; (map) A map to define sites matrix and sites complements for the mount. Relevant for content and layouts mounts, and static mounts when in multihost mode. For static and layouts, only the matrix keyword is supported.

Example

module:
  mounts:
  - excludeFiles: docs/*
    source: content
    target: content
  - source: node_modules
    target: assets
  - source: assets
    target: assets

[module]
  [[module.mounts]]
    excludeFiles = 'docs/*'
    source = 'content'
    target = 'content'
  [[module.mounts]]
    source = 'node_modules'
    target = 'assets'
  [[module.mounts]]
    source = 'assets'
    target = 'assets'

{
   "module": {
      "mounts": [
         {
            "excludeFiles": "docs/*",
            "source": "content",
            "target": "content"
         },
         {
            "source": "node_modules",
            "target": "assets"
         },
         {
            "source": "assets",
            "target": "assets"
         }
      ]
   }
}

Last updated: December 19, 2025 : content: Fix formatting (37bedd7d3)

Improve this page