{"id":4770,"library":"sphinx-prompt","title":"Sphinx Prompt","description":"Sphinx Prompt is a Sphinx directive that allows developers to add code blocks with unselectable prompts to their documentation. This ensures that readers can easily copy and paste commands without including the prompt characters. The library is actively maintained, with frequent minor releases, and is currently at version 1.10.2.","status":"active","version":"1.10.2","language":"en","source_language":"en","source_url":"https://github.com/sbrunner/sphinx-prompt","tags":["sphinx","documentation","prompt","code-blocks","rst"],"install":[{"cmd":"pip install sphinx-prompt","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Sphinx-prompt is a Sphinx extension and requires Sphinx to function.","package":"Sphinx","optional":false}],"imports":[{"note":"sphinx-prompt is enabled by adding 'sphinx_prompt' to the 'extensions' list in your Sphinx project's conf.py file. There is no direct Python import for the directive itself; it's used in reStructuredText.","symbol":"Extension Setup","correct":"# in conf.py\nextensions = [\n    'sphinx_prompt',\n    # ... other extensions\n]"}],"quickstart":{"code":"# conf.py\nextensions = [\n    'sphinx_prompt',\n]\n\n# my_document.rst\n\n.. prompt:: python\n\n   >>> import sys\n   >>> print(sys.version)\n   3.11.0 (main, ...)\n\n.. prompt:: bash $\n\n   $ ls -l\n   total 0\n   -rw-r--r-- 1 user group 0 Jan  1 10:00 myfile.txt\n","lang":"python","description":"After installing the library and adding 'sphinx_prompt' to your `conf.py` extensions, you can use the `.. prompt::` directive in your reStructuredText files. You can specify a language (e.g., `python`, `bash`, `powershell`) and a custom prompt. If no prompt is given for a shell language, a default is used (e.g., `$` for bash, `C:\\>` for batch, `PS C:\\>` for powershell)."},"warnings":[{"fix":"Ensure your Sphinx installation is compatible with `sphinx-prompt`. For `sphinx-prompt` 1.9.0+, consider upgrading Sphinx to version 8 or later. For older Sphinx versions, use an earlier `sphinx-prompt` release.","message":"Version 1.9.0 introduced compatibility with Sphinx 8, a major release of Sphinx. Users upgrading to `sphinx-prompt` 1.9.0 or later may encounter incompatibilities if their Sphinx project is built with an older Sphinx version (prior to Sphinx 8).","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"Upgrade your Python environment to 3.11 or newer if you wish to use `sphinx-prompt` 1.10.0 or later. Alternatively, pin your `sphinx-prompt` version to an earlier release compatible with your Python version (e.g., `<1.10.0` for Python < 3.11).","message":"The minimum required Python version for `sphinx-prompt` was updated to Python >= 3.11 in recent releases (specifically, 1.10.x). Earlier versions of `sphinx-prompt` (e.g., 1.8.0) supported Python 3.9.","severity":"breaking","affected_versions":">=1.10.0"},{"fix":"Instead of `.. prompt:: bash (venv) $`, use the `:prompts:` option: `.. prompt:: bash\n   :prompts: (venv) $`","message":"When using the `.. prompt::` directive, if your desired prompt string contains spaces (e.g., `(venv) $`), you cannot use positional arguments to specify it due to reStructuredText parsing limitations. The prompt will be incorrectly split.","severity":"gotcha","affected_versions":"*"},{"fix":"As a general rule, ensure `sphinx_prompt` is listed *before* other extensions that might preprocess or transform code block content in your `conf.py` file to ensure `sphinx-prompt`'s directive is processed first.","message":"If you are using `sphinx-prompt` alongside other Sphinx extensions that modify or interact with code blocks (e.g., `sphinx-substitution-extensions`), the order in which extensions are loaded in `conf.py` can be important. Incorrect ordering might lead to unexpected rendering or behavior.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}