# plausible-hugo: Hugo Module vs Theme Installation – Which Approach to Choose?

> Choose between Hugo module or theme installation for plausible-hugo. Understand local storage vs. cached dependencies to optimize your site setup for this Hugo analytics theme.

- Repository: [divinerites/plausible-hugo](https://github.com/divinerites/plausible-hugo)
- Tags: comparison
- Published: 2026-02-28

---

**Both installation methods ultimately load identical partial templates from `layouts/partials/`, but theme installation stores code locally under `themes/` while module installation caches versioned dependencies via Hugo's native module system.**

The `divinerites/plausible-hugo` repository distributes its Plausible Analytics integration as both a traditional Hugo theme component and a modern Hugo Module. When deciding between **plausible-hugo Hugo module vs theme installation**, understand that the underlying tracking logic—contained in [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html) and [`plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_check.html)—remains identical regardless of delivery method; only the dependency management and update workflows differ.

## Installing plausible-hugo as a Hugo Theme

Traditional theme installation copies the repository into your project's `themes/` directory. You declare it in your site's [`config.toml`](https://github.com/divinerites/plausible-hugo/blob/main/config.toml) using the `theme` array, which tells Hugo to include `themes/plausible-hugo` in the template lookup path.

### Configuration for Theme Install

Add the repository name to your `theme` array and configure the Plausible parameters:

```toml

# config.toml

theme = ["plausible-hugo"]

[params.plausible]
  enable = true
  domain = "example.com"

```

### Update Workflow for Theme Install

Updating requires manual intervention. You must pull the latest tag or commit into the `themes/plausible-hugo` directory, or re-clone the repository entirely. This approach offers no explicit version pinning—the installed version is whatever exists in that directory at build time.

## Installing plausible-hugo as a Hugo Module

Module installation leverages Hugo's native dependency management. Instead of committing code to your repository, Hugo downloads and caches the module in `$HOME/.cache/hugo/modules` based on the import declaration in your configuration.

### Configuration for Module Install

Declare the repository as a module import under the `[module]` section:

```toml

# config.toml

[module]
  [[module.imports]]
    path = "github.com/divinerites/plausible-hugo"

[params.plausible]
  enable = true
  domain = "example.com"

```

### Update Workflow for Module Install

Run `hugo mod get -u` or `hugo mod tidy` to automatically resolve the newest version. Hugo generates a `go.mod` file that pins the exact module version, enabling reproducible builds across environments. This method respects semantic versioning constraints defined in your module configuration.

## How Both Methods Execute the Same Code

Regardless of whether you choose **plausible-hugo theme installation** or the module approach, Hugo resolves the partial templates identically. The core logic lives in [`layouts/partials/plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_head.html), which internally calls [`layouts/partials/plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_check.html) to validate configuration parameters.

When rendering pages, your layout invokes:

```html
<head>
  {{ partial "plausible_head.html" . }}
</head>

```

The [`plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_check.html) partial (lines 1–28) validates your `[params.plausible]` settings and prints helpful console warnings if misconfigured. The [`theme.yaml`](https://github.com/divinerites/plausible-hugo/blob/main/theme.yaml) file declares the current version (1.22.0) and package metadata, which Hugo references for both theme and module resolution. The script injection logic—including support for self-hosted domains, Netlify proxying, and hash-based routing—functions identically regardless of how the code reaches your project.

## Summary

- Both **plausible-hugo Hugo module vs theme installation** methods load the same partials from `layouts/partials/`
- Theme installation stores code locally under `themes/` and requires manual updates via git pull or re-cloning
- Module installation caches code in `$HOME/.cache/hugo/modules/` and uses `go.mod` for reproducible version pinning
- Update theme installs by pulling the latest commits; update modules with `hugo mod get -u`
- Both methods support identical Plausible configuration via `[params.plausible]` and optional Netlify proxy settings

## Frequently Asked Questions

### Which installation method should I use for new projects?

Choose the module approach if you want automatic updates and version pinning via `go.mod`. Select theme installation if you prefer to keep the code inside your repository for easy customization or are working in an environment without Go toolchain support.

### Can I switch from theme installation to module installation later?

Yes. Remove the repository from your `themes/` directory, delete it from the `theme` array in [`config.toml`](https://github.com/divinerites/plausible-hugo/blob/main/config.toml), and add the module import under `[module]`. The partial templates ([`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html), [`plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_check.html)) function identically regardless of how Hugo discovers them.

### Does the installation method affect Plausible tracking features?

No. Features like self-hosted domains, Netlify proxying (`proxy_netlify`), hash-based routing, and outbound link tracking work identically in both installations. The [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html) partial builds the tracking script URL based solely on your `[params.plausible]` configuration, not on the discovery path.

### Where does Hugo cache the module version?

Hugo stores downloaded modules in your system's module cache, typically located at `$HOME/.cache/hugo/modules/`. Unlike theme installation, the source code does not appear in your project's `themes/` directory, keeping your repository clean while still allowing template resolution during builds.