Sphinx Google Analytics Extension

0.5 · active · verified Thu Apr 16

sphinxcontrib-googleanalytics is a Sphinx extension that enables tracking of generated HTML documentation files using the Google Analytics web service. The current version is 0.5, and it maintains an infrequent release cadence, with the latest release 0.5 published approximately 11 months ago and 0.4 released in January 2023.

Common errors

```
Extension error: Could not import extension sphinxcontrib.googleanalytics (exception: cannot import name 'ExtensionError')
```
cause This error typically indicates an incompatibility issue, possibly with an older or conflicting version of Sphinx or related dependencies.

fix Ensure your Sphinx installation is up-to-date and compatible with the `sphinxcontrib-googleanalytics` version. Consider creating a fresh virtual environment to isolate dependencies. Check GitHub issues for specific Sphinx version compatibility.
```
Google Analytics tracking is not working, but I have set `analytics_id` in `html_theme_options`.
```
cause If you are using a Sphinx theme like `sphinx_rtd_theme`, the `analytics_id` option within `html_theme_options` has been deprecated in favor of using the `sphinxcontrib-googleanalytics` extension directly.

fix Remove `analytics_id` from `html_theme_options`. Instead, add `sphinxcontrib.googleanalytics` to your `extensions` list in `conf.py` and set `googleanalytics_id = 'YOUR_GA_ID'` at the top level of your `conf.py`.
```
Google Analytics tracking works locally but not in my CI/CD (e.g., GitHub Actions, Read the Docs) build.
```
cause The `googleanalytics_id` might not be set or correctly passed to the build environment during CI/CD, or the extension might be conditionally enabled.

fix Ensure the `googleanalytics_id` variable is explicitly set in your `conf.py` or configured via an environment variable that is properly exposed in your CI/CD pipeline. Use `os.environ.get('GOOGLE_ANALYTICS_ID', '')` to retrieve the ID, and conditionally append `sphinxcontrib.googleanalytics` to `extensions` only if the ID is present, as shown in the quickstart.

Warnings

deprecated The `analytics_id` and `analytics_anonymize_ip` options in the `Read the Docs Sphinx Theme` are deprecated. Users of this theme should switch to using `sphinxcontrib-googleanalytics` for Google Analytics integration.
Fix: Remove `analytics_id` and `analytics_anonymize_ip` from `html_theme_options` in `conf.py`. Instead, add `sphinxcontrib.googleanalytics` to your `extensions` list and set `googleanalytics_id` directly in `conf.py`.
gotcha Google Analytics (and thus this extension) may not inherently be compliant with GDPR without additional infrastructure to manage user consent.
Fix: Consult legal advice regarding GDPR compliance for your specific use case. Consider alternative, privacy-focused analytics solutions if GDPR compliance is a strict requirement without custom implementation.
gotcha Ensure you use the correct Google Analytics ID format for your property: `G-XXXXXXXXX` for Google Analytics 4 (GA4) or `UA-XXXXXXXXX` for Universal Analytics.
Fix: Verify your Google Analytics property type and use the corresponding tracking ID format in your `conf.py` file.

Install

pip install sphinxcontrib-googleanalytics Install from PyPI

Imports

sphinxcontrib.googleanalytics
wrong:
```
import sphinxcontrib.googleanalytics
```
correct:
```
# In conf.py, add to extensions list:
extensions = ['sphinxcontrib.googleanalytics']
```
This is a Sphinx extension and is enabled by adding its module name to the 'extensions' list in Sphinx's conf.py, not by a direct Python import statement for runtime use.

Quickstart

To quickly integrate sphinxcontrib-googleanalytics, add `sphinxcontrib.googleanalytics` to your `extensions` list in `conf.py` and set the `googleanalytics_id` variable to your Google Analytics Tracking ID (e.g., `G-XXXXXXXXX` for GA4 or `UA-XXXXXXXXX` for Universal Analytics). It's common to conditionally enable this based on an environment variable for local builds vs. production deployments, preventing local tracking.

import os

# conf.py example

project = 'My Project'
copyright = '2026, My Team'
author = 'My Team'
release = '0.1'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    # Enable the Google Analytics extension
]

# Only enable Google Analytics if an ID is provided, useful for CI/CD environments
googleanalytics_id = os.environ.get('GOOGLE_ANALYTICS_ID', '')
if googleanalytics_id:
    extensions.append('sphinxcontrib.googleanalytics')
    # Optionally enable/disable tracking based on environment variable
    # googleanalytics_enabled = os.environ.get('GOOGLE_ANALYTICS_ENABLED', 'True').lower() == 'true'

view raw JSON →