How to Add Umami Analytics to a WordPress Site

Updated: August 2026

If you want privacy-focused website analytics on WordPress, you can add Umami Analytics by installing its tracking script in your site's <head> section. The basic process is: create your website in Umami, copy its tracking code, add that code to WordPress, publish the change, and then verify that pageviews appear in your Umami dashboard.

The easiest approach for most WordPress users is to use a header-insertion or code-snippet plugin such as WPCode. Developers can alternatively add the script through a child theme or another WordPress-supported code integration.

This guide explains both approaches in detail. If you are new to Umami itself, consider reading our complete guide to self-hosting Umami, our self-hosted vs managed Umami comparison, or our Umami vs Google Analytics article first.

Table of contents

  1. What Is Umami Analytics?
  2. What You Need Before Starting
  3. Step 1: Create Your Website in Umami
  4. Step 2: Find Your Umami Tracking Code
  5. Step 3: Add Umami to WordPress With WPCode
  6. Step 4: Add Umami Directly to WordPress Code
  7. Step 5: Verify That Umami Is Working
  8. Step 6: Clear WordPress Caches
  9. Step 7: Troubleshoot Missing Analytics Data
  10. Step 8: Track WordPress Events
  11. Step 9: Create Conversion Goals
  12. Step 10: Enable Performance Monitoring
  13. Using Google Tag Manager With WordPress
  14. Best Practices for Adding Umami to WordPress
  15. Frequently Asked Questions
  16. Conclusion

What Is Umami Analytics?

Umami is an open-source, privacy-first web analytics platform designed as an alternative to traditional analytics tools. According to the official documentation, Umami focuses on anonymous analytics and does not use cookies or cross-site tracking. It can provide metrics such as pageviews, visitors, bounce rate, session duration, referrers, devices, browsers, operating systems, and countries.

Umami can be self-hosted or used through Umami Engine for Cloud, so the installation process can vary depending on where your Umami instance is running. For WordPress, the important part is the same: your website needs the Umami tracker script and the correct website ID.

What You Need Before Starting

Before adding Umami to WordPress, make sure you have:

  • A working WordPress website.
  • Access to the WordPress administrator dashboard.
  • An Umami account or a working self-hosted Umami instance.
  • A website configured inside Umami.
  • The Umami tracking code for that website.
  • Permission to add code to your WordPress site's <head> section.

If you use a caching or optimization plugin, you should also know how to clear its cache after changing your site's tracking code.

Step 1: Create Your Website in Umami

First, log in to your Umami dashboard. You need to create or configure the website you want to measure. The exact interface can vary between Umami versions and hosting options, but the objective is to have your WordPress domain represented as a website in Umami.

Once the website has been created, Umami provides the tracking code associated with it. The official Umami documentation says to open the website's Edit area and locate the Tracking code section.

Your tracking code will look broadly similar to this:

<script
  defer
  src="https://your-umami.example.com/script.js"
  data-website-id="your-website-id"
></script>

Do not copy the example above as-is. Your src and data-website-id values need to come from your own Umami installation. If you're using Umami Engine for Cloud, the script source is set for you. If you're self-hosting, it normally points to your own Umami instance.

Step 2: Find Your Umami Tracking Code

In your Umami dashboard:

  1. Open the website you want to track.
  2. Open its editing/settings area.
  3. Find the Tracking code section.
  4. Copy the complete script.
  5. Keep the code unchanged unless you intentionally want to configure additional tracker options.

Umami's documentation specifically instructs users to copy the tracking code and insert it into the <head> section of their website. After installation, visiting the website should allow data to begin appearing in the Umami dashboard.

The most important value in the code is the data-website-id. This identifies which Umami website should receive the analytics data.

Step 3: Add Umami to WordPress With WPCode

For most WordPress site owners, a header/code-snippet plugin is the simplest method. One option is WPCode, which is available in the WordPress plugin directory and supports inserting scripts into the site header without directly editing theme files.

Install WPCode

From your WordPress dashboard:

  1. Go to Plugins → Add New Plugin.
  2. Search for WPCode.
  3. Install the plugin.
  4. Activate it.

WordPress.org currently lists WPCode as a plugin for inserting header and footer scripts and other custom snippets.

Add the Umami script

After activating the plugin:

  1. Open the WPCode interface.
  2. Choose the option for adding a header/footer script or custom snippet.
  3. Create a new snippet if necessary.
  4. Give it a descriptive name such as Umami Analytics.
  5. Paste your complete Umami tracking code into the appropriate header area.
  6. Make sure the snippet is enabled.
  7. Save or publish the snippet.

The objective is for the Umami <script> element to appear on the front end of your WordPress website.

Why use WPCode?

Using a dedicated snippet plugin avoids modifying your theme's files directly. This is useful when you don't want to maintain custom tracking code inside a theme, and allows you to change themes later without losing your tracking integration.

Deploy Umami in minutes now

Step 4: Add Umami Directly to WordPress Code

Developers who prefer not to install another plugin can integrate Umami through their WordPress theme code. WordPress provides the wp_head action for printing scripts and other data inside the front-end <head> section.

A typical approach is to add the Umami script through a child theme rather than modifying the parent theme directly. For example:

function mysite_add_umami_tracking() {
    ?>
    <script
      defer
      src="https://your-umami.example.com/script.js"
      data-website-id="YOUR-WEBSITE-ID"
    ></script>
    <?php
}
add_action('wp_head', 'mysite_add_umami_tracking');

Replace:

  • https://your-umami.example.com/script.js with the script URL from your Umami installation.
  • YOUR-WEBSITE-ID with the website ID provided by Umami.

Important: avoid editing a parent theme directly

If you add custom PHP to a theme's functions.php file, a future theme update can overwrite your changes. A child theme or dedicated code-snippet system is generally a better place for custom code. Also make sure your theme correctly calls wp_head(), which WordPress documents as the function that fires the wp_head action for outputting scripts and other data in the document head.

Step 5: Verify That Umami Is Working

After adding the tracking code, don't assume the installation is complete. Test it.

Test 1: Open your website

Open your WordPress website in a browser and visit several pages rather than only the homepage. For example:

  • Open the homepage.
  • Open a blog post.
  • Open another page.
  • Navigate between several pages.

Umami's tracker automatically collects pageviews by default.

Test 2: Check the Umami dashboard

Return to Umami and open the website dashboard. You should eventually see activity associated with your visit. Umami's documentation states that after installing the tracking code, visiting the website should result in data appearing in the dashboard.

Test 3: Inspect the page source

You can also inspect your WordPress page. In your browser:

  1. Open the website.
  2. Right-click and choose View Page Source or use your browser's developer tools.
  3. Search for data-website-id.
  4. Confirm that your Umami script is present.

If the script is not present, the WordPress integration has not inserted it correctly.

Step 6: Clear WordPress Caches

If you installed Umami but don't immediately see data, caching may be responsible. WordPress websites commonly use several layers of caching:

  • WordPress caching plugins
  • Hosting-level caching
  • CDN caching
  • Browser caching
  • Page optimization systems

After adding the Umami script:

  1. Save your changes.
  2. Clear your WordPress cache.
  3. Clear your hosting/CDN cache if applicable.
  4. Open the site in a private/incognito browser window.
  5. Visit several pages.
  6. Check Umami again.

Do not repeatedly reinstall the tracking code simply because the dashboard does not update immediately.

Step 7: Troubleshoot Missing Analytics Data

If Umami isn't showing visits, open your browser's developer tools. Umami recommends checking the browser's Network tab to determine whether requests are reaching the Umami instance and whether the tracking script is loading without errors.

Check the script URL

Confirm that the src in your script points to the correct Umami tracker. For example:

<script
  defer
  src="https://your-umami.example.com/script.js"
  data-website-id="YOUR-WEBSITE-ID"
></script>

A wrong script URL will prevent the tracker from loading.

Check the website ID

Make sure the data-website-id belongs to the website you created in Umami. A typo in this value can prevent data from appearing under the expected website.

Check for duplicate tracking codes

Search your site's source for multiple Umami scripts. Installing the tracker through WPCode while also adding it through your theme, another plugin, or Google Tag Manager can result in duplicate installations. Keep one primary installation unless you have a specific reason to use multiple configurations.

Check ad blockers

Browser extensions and privacy tools can block analytics scripts. Umami's documentation specifically notes that ad blockers can prevent the tracking script from loading. For troubleshooting, test the site in a clean browser profile or with extensions temporarily disabled.

Step 8: Track WordPress Events

Basic Umami installation gives you pageview analytics, but you can go further by tracking important interactions. Umami supports event tracking through HTML data-* attributes or JavaScript. For a complete walkthrough of the event-tracking fundamentals, including how to name events, attach properties, and test your setup, see our guide to setting up event tracking in Umami.

For example, you could track a button click with:

<a
  href="/contact/"
  data-umami-event="contact-click"
>
  Contact Us
</a>

When the visitor clicks the link, Umami can record the event.

You can also attach additional event data:

<button
  data-umami-event="pricing-click"
  data-umami-event-plan="pro"
>
  View Pro Plan
</button>

Umami supports event data for adding additional context to tracked events.

Useful WordPress events to consider

Depending on your site, you might track:

  • Contact form submissions
  • Pricing-page clicks
  • Newsletter signups
  • CTA clicks
  • Downloads
  • Outbound links
  • Product interactions
  • Account registrations
  • Checkout actions

Only track information that is appropriate for your analytics requirements and privacy obligations. If you need help understanding which analytics events are privacy-friendly, read our GDPR compliance guide.

Step 9: Create Conversion Goals

Once you have meaningful events, you can use them to measure conversions. For example, suppose your WordPress site has a newsletter signup button. You could track an event called newsletter-signup.

Umami's conversion-goal documentation describes goals based on either page views or triggered events. A page-view conversion might be /pricing, and an event-based conversion might be newsletter-signup.

This lets you move beyond the question of "How many people visited my website?" and start answering "Which pages and interactions lead to valuable actions?"

Step 10: Enable Performance Monitoring

If your Umami version supports performance monitoring, you can configure the tracker to collect real-user performance metrics. Umami documents data-performance="true" for collecting Core Web Vitals and other performance signals.

Your tracking code can therefore include an additional attribute:

<script
  defer
  src="https://your-umami.example.com/script.js"
  data-website-id="YOUR-WEBSITE-ID"
  data-performance="true"
></script>

This is optional. If you enable it, use the exact tracker configuration supported by the version of Umami you are running.

Using Google Tag Manager With WordPress

If your WordPress website already uses Google Tag Manager, you can install Umami through GTM instead of placing the tracking code directly in WordPress.

There is an important detail: Umami's custom data-* attributes need to survive the installation process. Umami's documentation recommends creating the script element dynamically with a Custom HTML tag because Google Tag Manager strips custom data-* attributes from ordinary script tags.

The general process is:

  1. Open Google Tag Manager.
  2. Go to Tags.
  3. Create a new tag.
  4. Select Custom HTML.
  5. Add the Umami script-generation code using your own script URL and website ID.
  6. Set the trigger to All Pages.
  7. Save the tag.
  8. Submit and publish the GTM container.
  9. Visit your WordPress website.
  10. Check the Umami dashboard.

Use the current installation code from the official Umami documentation rather than copying an older third-party example, as the recommended approach can change between Umami versions.

Best Practices for Adding Umami to WordPress

  • Use one primary installation method. Choose a header/code plugin, a child theme integration, or Google Tag Manager. Don't install the same tracker through multiple systems unless you understand the consequences.
  • Keep your website ID correct. The website ID appears in the client-side tracking code, so the important thing is to ensure it is correct rather than trying to hide it.
  • Copy the official tracking code. Copy the tracker from your website's Umami dashboard. This reduces the risk of using outdated syntax.
  • Test after WordPress changes. Recheck tracking after changing themes, migrating the website, changing domains, changing the Umami instance, modifying a caching/CDN configuration, or changing tracking plugins.
  • Consider domain restrictions. Umami supports tracker configuration options such as data-domains, which can restrict where the tracker operates. This is useful when you have staging and production environments. For example: data-domains="example.com,www.example.com".
  • Review privacy and consent requirements. Umami is designed for privacy. But your legal obligations depend on your jurisdiction, website, audience, configuration, and other technologies you use. See GDPR compliance for web analytics for more.
Get fully managed Umami in minutes

Frequently Asked Questions

Can I add Umami Analytics to WordPress without editing my theme? Yes. A header/code-snippet plugin such as WPCode can add the Umami tracking script without requiring direct theme-file editing.

Where should the Umami tracking code go in WordPress? Umami's documentation instructs you to place the tracking code in the website's <head> section.

Do I need a WordPress plugin for Umami? No. A plugin is not technically required. Developers can integrate the script through WordPress code, including the wp_head hook.

Why isn't my Umami dashboard showing visitors? Check that the tracking script is present, the script URL is correct, and the data-website-id matches your Umami website. Then inspect your browser's Network tab for tracking requests. Also check caching and ad-blocking extensions.

Does Umami automatically track pageviews? Yes. The tracker automatically collects pageviews by default.

Can Umami track button clicks on WordPress? Yes. Umami supports event tracking through data-umami-event attributes and JavaScript.

Can I use Umami with Google Tag Manager? Yes. Umami provides a Google Tag Manager installation method using a Custom HTML tag.

Can Umami track Core Web Vitals? Yes, supported Umami versions can collect Core Web Vitals and other real-user performance metrics when performance tracking is enabled.

Should I install Umami through a plugin or manually? For beginners, a header/code-snippet plugin is generally easier to manage. Developers who already maintain a child theme or custom WordPress code may prefer a direct integration.

Get fully managed Umami in minutes

Conclusion

Adding Umami Analytics to a WordPress site is primarily about placing the correct Umami tracking script in the site's <head> section.

The simplest workflow is:

  1. Create your WordPress website in Umami.
  2. Open its Tracking code section.
  3. Copy the complete script.
  4. Add it to WordPress using a header/code-snippet plugin such as WPCode.
  5. Save and activate the code.
  6. Clear relevant caches.
  7. Visit your website.
  8. Check the Umami dashboard.
  9. Use browser developer tools if data does not appear.
  10. Add event tracking and conversion goals when you need deeper insights.

Umami's official documentation confirms that the tracker is designed to be installed in the site's <head> and automatically collects pageviews. For a basic WordPress site, you do not need a complicated analytics integration. Get the correct tracking code in place and verify it is firing; then build additional tracking only when you have a clear, worthwhile measurement goal.

If you would rather not run additional infrastructure, UmamiEngine offers managed Umami hosting designed for sites like WordPress, or you can sign up now and be tracking in minutes.

Deploy managed Umami in minutes