Registry /
observability / sphinxcontrib-googleanalytics
Install & Compatibility
Where this runs
tested against v0.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.1s · import 0.000s · 93MB
94MB installed
● package 94MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinxcontrib.googleanalytics
✓ # In conf.py, add to extensions list:
extensions = ['sphinxcontrib.googleanalytics']
✗ import 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.
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'
Debug
Known issues
deprecatedThe `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.fixRemove `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`.
affects: sphinx_rtd_theme >= 3.0.0
gotchaGoogle Analytics (and thus this extension) may not inherently be compliant with GDPR without additional infrastructure to manage user consent.fixConsult 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.
affects: All versions
gotchaEnsure you use the correct Google Analytics ID format for your property: `G-XXXXXXXXX` for Google Analytics 4 (GA4) or `UA-XXXXXXXXX` for Universal Analytics.fixVerify your Google Analytics property type and use the corresponding tracking ID format in your `conf.py` file.
affects: All versions
Upgrade
Version history
0.5latest on PyPI · released May 26, 2025
Audit
Dependencies
SphinxrequiredThis is a Sphinx extension and requires Sphinx to function. Specific Python version requirements are inherited from the Sphinx version in use.