Hugo Favicon Setup: Add a Custom Icon to Any Hugo Site

Your Hugo site builds cleanly, yet its browser tab still shows a generic page icon. That usually means the icon file sits outside Hugo’s published asset path or the generated HTML never references it. A reliable Hugo favicon setup separates assets from templates: static/ publishes the files, while a layout partial adds the browser-facing <link> elements.

Prerequisites

You need an existing Hugo site, a square logo or icon, and access to its layouts. If your master file is PNG or SVG, use Mzu favicondl to prepare an ICO fallback, and keep the original artwork at its highest available resolution.

• An existing Hugo project
• A square SVG and ICO icon
• Access to your project’s and theme’s layouts

Add a Hugo favicon in four steps

1. Create the published files. Convert your artwork to favicon.svg and favicon.ico, then place both in Hugo’s root-level static/ directory:

   static/
     favicon.svg
     favicon.ico

   Files in static/ are copied as-is, so Hugo publishes them at the site root.
2. Create a reusable partial. Add layouts/partials/head/favicon.html with:

   <link rel='icon' href='{{ "favicon.ico" | relURL }}' sizes='any'>
   <link rel='icon' href='{{ "favicon.svg" | relURL }}' type='image/svg+xml'>

   The HTML specification defines the icon link relation. We use relURL so the generated path follows Hugo’s base path instead of assuming the site lives at the domain root.

3. Render the partial in <head>. Search your project and active theme for the layout containing the document head. Add this line immediately before its closing head tag:

   <head>
     ...
     {{ partial "head/favicon.html" . }}
   </head>

   If the file belongs to a theme, copy it into your project’s equivalent layouts/ path first; otherwise, a theme update can overwrite the edit. If the theme already calls a favicon partial, edit that partial instead of adding a second one.

4. Build, preview, and inspect. Run:

   hugo
   hugo server

   Open the local site and inspect the page head in browser developer tools. Confirm that the generated icon URLs return 200, and check that public/favicon.svg and public/favicon.ico exist after the production build. For a wider comparison of framework patterns, see the static site generator favicon guide.

Common pitfalls

• Placing the icon only in assets/. That directory is for Hugo-managed resources. Put unchanged public files in static/, or process them through Hugo’s resource pipeline.
• Hard-coding /favicon.svg. This breaks sites deployed under a subpath. Build the URL with relURL.
• Editing only a theme file. Theme upgrades may replace it. Keep the override in your project whenever possible.
• Expecting an immediate refresh. Browsers can cache icon URLs. Follow the favicon troubleshooting checklist if the live page still uses the old icon.

Confirm the final result

Your Hugo favicon is ready when the generated head contains both link elements, every referenced file returns successfully, and the browser tab shows the intended mark. Keep the source artwork separate from the generated files so future updates remain predictable.