TIL #125 – Images in docstrings

Images in docstrings

As it turns out, VS Code (and likely other editors, too) render docstrings as Markdown. That means you can add images to your docstrings using Markdown syntax and they will be rendered.

I used uv init --package myproj to initialise a project and this is what I put at the top of the file src/myproj/__init__.py as the module docstring:

"""
Hey there!

![](https://mathspp.com/user/themes/myquark/images/rodrigo_256.png)
"""

Then, I created another file and typed import myproj at the top of the file. When I hovered over the import line, the tooltip showed my face:

This works with GIFs and plain images, as long as you're pointing to a URL on the Internet. (It looks like it doesn't work with local files). It also works on other objects that can be documented with docstrings... For example, it also works with functions.

Here's a simple function I defined and documented inside src/myproj/__init__.py:

def two():
    """![](https://mathspp.com/blog/til/images-in-docstrings/_two.gif)"""
    return 2

When I used it in my other file and hovered over its name, I saw the GIF animation inside VS Code:

This is pretty hilarious but a reasonable use case might be to include diagrams for complex functions...

Try it yourself!

Give it a go yourself! Open an arbitrary Python file and paste this code in:

def two():
    """![](https://mathspp.com/blog/til/images-in-docstrings/_two.gif)"""
    return 2

print(two())

Hover over the two() in the last line and you should see the “TWO!” GIF playing.

Hats off to “MACE!!!” who indirectly showed me this on BlueSky.

Improve your Python 🐍 fluency and algorithm knowledge 🎯

Get ready for 12 intense days of problem-solving. The “Algorithm Mastery Bootcamp” starts December 1st and it will feature 24 programming challenges, live analysis sessions, a supportive community of like-minded problem-solvers, and more! Join now and become the Python expert others can rely on.

References

• User “MACE!!!” on BlueSky, https://bsky.app/profile/physicssux.bsky.social/post/3lt4rudnbyc2v [last accessed 06-07-2025];