DEV Community

Cover image for PythonICO: Beautiful, Live PyPI Badges for Your Python Projects 🐍
Livrädo Sandoval
Livrädo Sandoval

Posted on

PythonICO: Beautiful, Live PyPI Badges for Your Python Projects 🐍

#python #opensource #pypi #devtools

If you maintain Python packages, you already know how important a clean and informative README is.

Badges help your project look professional at a glance — but most badge solutions are either limited, inflexible, or not designed specifically for PyPI.

That’s why I built PythonICO.

👉 PythonICO is an open-source service that generates beautiful, live SVG badges for PyPI packages, with multiple styles, real-time data, and a simple REST API.

🚀 What Is PythonICO?

PythonICO is a FastAPI-based badge generator that lets you display PyPI statistics directly in your README:

  • Package name
  • Latest version
  • Weekly downloads
  • License
  • Required Python version
  • Last update

All rendered as clean, customizable SVG badges, compatible with GitHub, GitLab, and any Markdown renderer.

✨ Key Features

  • 🎨 6 Badge Styles
    standard, compact, mini, shields, flat, flat-square

  • 📊 Custom Data Selection
    Choose exactly what to display — and in what order.

  • 🎨 Flexible Colors
    Named colors or custom hex values.

  • ⚡ High Performance
    Smart caching with configurable TTL.

  • 🚀 Async & Fast
    Built with FastAPI for maximum performance.

  • 🔌 REST API
    Fully programmatic access.

  • 🌐 Web Interface
    Interactive badge generator with live preview.

🧪 Example Badges

Shields Style (GitHub-Friendly) 

[![PyPI](https://pythonico.leapcell.app/pypi/requests.svg?style=shields&data=n,v,d)](https://pypi.org/project/requests/)
Enter fullscreen mode Exit fullscreen mode

Flat Style with Multiple Data Points 

[![PyPI](https://pythonico.leapcell.app/pypi/django.svg?style=flat&data=v,d&color=brightgreen)](https://pypi.org/project/django/)
Enter fullscreen mode Exit fullscreen mode

Standard Style (Detailed View) 

[![PyPI](https://pythonico.leapcell.app/pypi/numpy.svg)](https://pypi.org/project/numpy/)
Enter fullscreen mode Exit fullscreen mode

⚡ Quick Start

Just replace package-name with your PyPI package:

[![PyPI](https://pythonico.leapcell.app/pypi/package-name.svg)](https://pypi.org/project/package-name/)
Enter fullscreen mode Exit fullscreen mode

With Custom Parameters 

[![PyPI](https://pythonico.leapcell.app/pypi/package-name.svg?style=shields&data=n,v,d&color=blue)](https://pypi.org/project/package-name/)
Enter fullscreen mode Exit fullscreen mode

📖 Customization Options

Available Styles

Compact (20px height)

  • shields – shields.io inspired, ideal for GitHub
  • flat – modern rounded design
  • flat-square – flat design with square corners

Detailed Styles

  • standard – full information (default)
  • compact – condensed one-line format
  • mini – minimal badge with install command

Data Parameters

Use the data query parameter to control what’s displayed (order matters):

Parameter Alias Description
name n Package name
version v Latest version
downloads d Weekly downloads
license l License
python py Required Python
updated u Last update

Examples

# Single value
![PyPI](https://pythonico.leapcell.app/pypi/numpy.svg?style=shields&data=version)

# Multiple values
![PyPI](https://pythonico.leapcell.app/pypi/pandas.svg?style=flat&data=n,v,d)

# Custom order
![PyPI](https://pythonico.leapcell.app/pypi/scipy.svg?style=shields&data=d,v,u)
Enter fullscreen mode Exit fullscreen mode

🎨 Colors

Named colors

  • pypi (default)
  • brightgreen, green, yellowgreen, yellow
  • orange, red, blue, lightgrey

Custom hex colors

![PyPI](https://pythonico.leapcell.app/pypi/mypy.svg?style=flat&data=n,v&color=%23ff6b6b)
Enter fullscreen mode Exit fullscreen mode

🤝 Open Source & Contributions

PythonICO is GPL-3.0 licensed and open to contributions.

You can help by:

  • Adding new badge styles
  • Improving caching strategies
  • Extending the API
  • Writing tests or docs

👉 Repository: https://github.com/livrasand/PythonICO

🛣️ Roadmap

  • Animated badges
  • Dark mode support
  • PNG / WebP export
  • Redis-based distributed cache
  • Advanced metrics (stars, issues, contributors)
  • CDN integration
  • API rate limiting

🙏 Acknowledgments

  • Inspired by nodei.co
  • Badge styles influenced by shields.io
  • Data from PyPI JSON API and pypistats.org

PyPI is a registered trademark of the Python Software Foundation.
PythonICO is an independent service and is not affiliated with PyPI or PSF.

🔗 Links

If you care about clean READMEs, real-time data, and developer experience,
PythonICO is built for you.

Made with ❤️ and Python 🐍

Top comments (0)