Sphinx-copybutton¶
Sphinx-copybutton does one thing: add little “copy” button to the right of your code blocks. That’s it! It is a lightweight wrapper around the excellent (and also lightweight) Javascript library ClipboardJS <https://clipboardjs.com/>.
Here’s an example

And here’s a code block, note the copy button to the right!
copy me!
By default, sphinx-copybutton
will remove Python prompts from
each line that begins with them. For example, try copying the text
below:
>>> a = 2
>>> print(a)
The text that sphinx-copybutton
uses can be configured as well. See
Customize the text that is removed during copying for more information.
If the code block overlaps to the right of the text area, you can just click the button to get the whole thing.
123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789123456789
Usage¶
In your conf.py
configuration file, add sphinx_copybutton
to your
extensions list. E.g.:
extensions = [
...
'sphinx_copybutton'
...
]
When you build your site, your code blocks should now have little copy buttons to their right. Clicking the button will copy the code inside!
Customization¶
Sphinx-copybutton was designed to work with the default Sphinx theme, Alabaster. If you use a theme that doesn’t play nicely with sphinx-copybutton’s CSS, you can always add your own CSS rules!
Customize the CSS¶
To customize the display of the copy button, you can add your own CSS files
that overwrite the CSS in the
sphinx-copybutton CSS rules.
Just add these files to _static
in your documentation folder, and it should
overwrite sphinx-copybutton’s behavior.
Customize the text that is removed during copying¶
By default, sphinx-copybutton
will remove Python prompts (“>>> “)
from the beginning of each line. To change the text that is reomved (or to remove
no text at all), add the following configuration to your conf.py
file:
copybutton_skip_text
Note that this text will only be removed from lines that begin with the text.
Use a different copy button image¶
To use a different image for your copy buttons, the easiest thing to do is to add a small bit of javascript to your Sphinx build that points the image to something new. Follow these steps:
Create a new javascript file in your site’s static folder (e.g., _static/js/custom.js). In it, put the following code:
const updateCopyButtonImages = () => { const copybuttonimages = document.querySelectorAll('a.copybtn img') copybuttonimages.forEach((img, index) => { img.setAttribute('src', 'path-to-new-image.svg') }) } runWhenDOMLoaded(updateCopyButtonImages)
Add this javascript file to your conf.py configuration like so:
def setup(app): app.add_javascript('js/custom.js');
This will replace the copybutton images each time the page loads!
If you know of a better way to do this with sphinx, please don’t hesitate to recommend something!
Development¶
If you’d like to develop or make contributions for sphinx-copybutton, fork the repository here:
https://github.com/choldgraf/sphinx-copybutton
pull to your computer and install locally with pip
:
pip install -e /path/to/sphinx_copybutton
Pull requests and Issues are absolutely welcome!