use-modules.md (4216B)
1 ---
2 title: Use Hugo Modules
3 linktitle: Use Hugo Modules
4 description: How to use Hugo Modules to build and manage your site.
5 date: 2019-07-24
6 categories: [hugo modules]
7 keywords: [install, themes, source, organization, directories,usage,modules]
8 menu:
9 docs:
10 parent: "modules"
11 weight: 20
12 weight: 20
13 sections_weight: 20
14 draft: false
15 aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
16 toc: true
17 ---
18
19 ## Prerequisite
20
21 {{< gomodules-info >}}
22
23
24
25 ## Initialize a New Module
26
27 Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.:
28
29 ```bash
30 hugo mod init github.com/gohugoio/myShortcodes
31 ```
32
33 Also see the [CLI Doc](/commands/hugo_mod_init/).
34
35 ## Use a Module for a Theme
36 The easiest way to use a Module for a theme is to import it in the config.
37
38 1. Initialize the hugo module system: `hugo mod init github.com/<your_user>/<your_project>`
39 2. Import the theme:
40
41 {{< code-toggle file="config" >}}
42 [module]
43 [[module.imports]]
44 path = "github.com/spf13/hyde"
45 {{< /code-toggle >}}
46
47 ## Update Modules
48
49 Modules will be downloaded and added when you add them as imports to your configuration, see [Module Imports](/hugo-modules/configuration/#module-config-imports).
50
51 To update or manage versions, you can use `hugo mod get`.
52
53 Some examples:
54
55 ### Update All Modules
56
57 ```bash
58 hugo mod get -u
59 ```
60
61 ### Update All Modules Recursively
62
63 {{< new-in "0.65.0" >}}
64
65 ```bash
66 hugo mod get -u ./...
67 ```
68
69 ### Update One Module
70
71 ```bash
72 hugo mod get -u github.com/gohugoio/myShortcodes
73 ```
74 ### Get a Specific Version
75
76 ```bash
77 hugo mod get github.com/gohugoio/myShortcodes@v1.0.7
78 ```
79
80 Also see the [CLI Doc](/commands/hugo_mod_get/).
81
82 ## Make and test changes in a module
83
84 One way to do local development of a module imported in a project is to add a replace directive to a local directory with the source in `go.mod`:
85
86 ```bash
87 replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials
88 ```
89
90 If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list.
91
92 Note that since v.0.77.0 you can use modules config [`replacements`](https://gohugo.io/hugo-modules/configuration/#module-config-top-level) option. {{< new-in "0.77.0" >}}
93
94 ## Print Dependency Graph
95
96
97 Use `hugo mod graph` from the relevant module directory and it will print the dependency graph, including vendoring, module replacement or disabled status.
98
99 E.g.:
100
101 ```
102 hugo mod graph
103
104 github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
105 github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
106 github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
107 github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
108 DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
109 github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
110 github.com/bep/my-modular-site in-themesdir
111
112 ```
113
114 Also see the [CLI Doc](/commands/hugo_mod_graph/).
115
116 ## Vendor Your Modules
117
118 `hugo mod vendor` will write all the module dependencies to a `_vendor` folder, which will then be used for all subsequent builds.
119
120 Note that:
121
122 * You can run `hugo mod vendor` on any level in the module tree.
123 * Vendoring will not store modules stored in your `themes` folder.
124 * Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the [Glob](https://github.com/gobwas/glob) pattern given. Note that before Hugo 0.75 this flag was named `--ignoreVendor` and was a "all or nothing". {{< new-in "0.75.0" >}}
125
126 Also see the [CLI Doc](/commands/hugo_mod_vendor/).
127
128
129 ## Tidy go.mod, go.sum
130
131 Run `hugo mod tidy` to remove unused entries in `go.mod` and `go.sum`.
132
133 Also see the [CLI Doc](/commands/hugo_mod_clean/).
134
135 ## Clean Module Cache
136
137 Run `hugo mod clean` to delete the entire modules cache.
138
139 Note that you can also configure the `modules` cache with a `maxAge`, see [File Caches](/getting-started/configuration/#configure-file-caches).
140
141
142
143 Also see the [CLI Doc](/commands/hugo_mod_clean/).