Sphinx-copybutton¶
Sphinx-copybutton does one thing: add little “copy” button to the right of your code blocks. That’s it!
Here’s an example

And here’s a code block, note the copy button to the right!
copy me!
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.
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!