Give your open-source project social proof with image shields

By Dan Bader — Get free updates of new posts here.

When developers decide if they’re going to use your open-source project they (often unconsciously) look at various signals to judge its quality. An important quality signal is social proof, that is, potential users want to know how many other developers use your project.

A good proxy for “how many other developers are using this” is a downloads per month number. Packaging directories like npm or PyPI provide these download stats publicly.

The download numbers reported there are likely a little inflated, for example, due to build bots installing the package.

But still, they’re a pretty good approximation.

More downloads indicate higher popularity which people often equate with more credibility.

(You see, this is open-source thing is really just like high-school :P).

Therefore, advertise the download numbers to increase the chances of someone trying out your project.

And by advertising I mean that the numbers should be clearly visible to anyone remotely interested in your library :-)

Image shields to the rescue

A quick and hassle-free way to share your downloads number with the world is by including a downloads image shield in your project’s README file.

You’ve probably seen these before. Here’s what I’m talking about:

What are image shields

Image shields are small auto-generated images provided by a service like img.shields.io. There’s no signup necessary and all configuration happens through the image URL.

For example, this is the URL for the image above:

https://img.shields.io/npm/dm/datadog-metrics.svg

The URL follows a scheme defined by the service. For downloads-per-month shields on img.shields.io you’d use this URL:

img.shields.io/<packaging service>/dm/<package name>.svg

For a Python package on PyPI you’d use something like img.shields.io/pypi/dm/schedule.svg, and for a NodeJS library on npm you’d use img.shields.io/npm/dm/datadog-metrics.svg.

There are many more examples on the img.shields.io home page.

Different styles

You also get to pick different styles for your image shields. For example there’s a nice flat theme that you can use by appending ?style=flat-square to the URL.

Here’s what an image shield looks like with the flat theme applied to it:

This article was filed under: developer-marketing.

Related Articles:

How to write a great README for your GitHub project – A great README file helps your project to stand out from the sea of open-source software on GitHub. In this article I go over the key elements every README for an open-source project should contain. It also includes a README.md template for use in your own projects.
What should I write about on my programming blog? – I’m answering a reader’s question on how to choose topics to write about on your programming website.
Generate and host your API documentation for free with open-source tools – How to generate documentation for a RESTful API as part of your continuous integration build and then automatically deploy it to a website. Includes a full example project on GitHub.
Python Code Review: Unplugged – Episode 3 – In this third episode of my video code review series I take a look at a reader’s web scraping project and start adding some unit tests to it.
3 Reasons why you need a programming blog – One of the best things I ever did for my dev career: A little story and three reasons why you should start a programming portfolio website right now.

Latest Articles:

Interfacing Python and C: The CFFI Module – How to use Python’s built-in CFFI module for interfacing Python with native libraries as an alternative to the “ctypes” approach.
Write More Pythonic Code by Applying the Things You Already Know – There’s a mistake I frequently make when I learn new things about Python… Here’s how you can avoid this pitfall and learn something about Python’s “enumerate()” function at the same time.
Working With File I/O in Python – Learn the basics of working with files in Python. How to read from files, how to write data to them, what file seeks are, and why files should be closed.
How to Reverse a String in Python – An overview of the three main ways to reverse a Python string: “slicing”, reverse iteration, and the classic in-place reversal algorithm. Also includes performance benchmarks.
Mastering Click: Writing Advanced Python Command-Line Apps – How to improve your existing Click Python CLIs with advanced features like sub-commands, user input, parameter types, contexts, and more.
Working with Random Numbers in Python – An overview for working with randomness in Python, using only functionality built into the standard library and CPython itself.

← Browse All Articles