{"id":24509,"library":"readthedocs-sphinx-search","title":"readthedocs-sphinx-search","description":"A Sphinx extension that adds autocomplete search-as-you-type functionality to documentation hosted on Read the Docs. Currently at version 0.3.2, updated infrequently. Requires Sphinx and works out of the box with Read the Docs hosting.","status":"active","version":"0.3.2","language":"python","source_language":"en","source_url":"https://github.com/readthedocs/readthedocs-sphinx-search","tags":["sphinx","search","readthedocs","autocomplete","documentation"],"install":[{"cmd":"pip install readthedocs-sphinx-search","lang":"bash","label":"Standard install"}],"dependencies":[{"reason":"Required to build documentation.","package":"sphinx","optional":false}],"imports":[],"quickstart":{"code":"extensions = [\n    'readthedocs_sphinx_search',\n]\n\n# Optional: configure search endpoint if not on Read the Docs\n# rtds_search_endpoint = 'https://your-project.readthedocs.io/api/v2/search/'","lang":"python","description":"Add 'readthedocs_sphinx_search' to the extensions list in your conf.py. No further configuration is required for projects hosted on Read the Docs."},"warnings":[{"fix":"Ensure your project is built and hosted on Read the Docs, or implement a custom search backend.","message":"This extension only works when your docs are hosted on Read the Docs. It does not work on other hosting platforms (e.g., GitHub Pages, Netlify) because it relies on Read the Docs' search API.","severity":"gotcha","affected_versions":"all"},{"fix":"Override the theme's search template or manually include the required CSS/JS assets.","message":"If using a custom theme, the search UI may not appear or may look broken. The extension adds a search bar that expects default Sphinx theme styles.","severity":"gotcha","affected_versions":"all"},{"fix":"Consider using the built-in search support from Read the Docs Addons or monitor for updates.","message":"The library has not seen updates since 2021. Future Sphinx versions may break compatibility.","severity":"deprecated","affected_versions":">=0.3.2"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use 'readthedocs_sphinx_search' (underscore) in extensions list.","cause":"The package is named with hyphens on PyPI but must be imported as a single underscore name.","error":"ImportError: cannot import name 'readthedocs_sphinx_search'"},{"fix":"Run 'pip install readthedocs-sphinx-search' and ensure your Sphinx build uses the same Python environment.","cause":"The package may not be installed or the virtual environment is not activated.","error":"sphinx.errors.ExtensionError: Could not import extension readthedocs_sphinx_search (exception: No module named 'readthedocs_sphinx_search')"},{"fix":"Build and deploy the docs on Read the Docs. For local testing, set the environment variable 'READTHEDOCS' to 'True' or configure 'rtds_search_endpoint'.","cause":"The extension requires the Read the Docs domain to work. Offline builds will not show the search bar.","error":"Search bar not appearing on the documentation site"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}