pypi-winnow-downloads 0.1.2

Self-hosted PyPI download badge service that winnows CI traffic out of download counts.

pypi-winnow-downloads

Self-hosted PyPI download badge service that winnows CI traffic out of download counts. Produces shields.io-compatible endpoint badges filtered by BigQuery's details.ci flag and an interactive-installer allowlist (pip, uv, poetry, pdm, pipenv, pipx) — more honest than any existing alternative for small or young Python packages.

The pip*/uv/poetry/pdm badge above is served by this project itself — eating our own dogfood. The endpoint went live with milestone M3 deployment on 2026-04-24 and currently shows 0 until the first release lands on PyPI; after that the count climbs automatically.

What the badge actually counts

The hero badge — labelled pip*/uv/poetry/pdm (Nd) — counts downloads that meet all of these conditions over the configured rolling window:

• details.ci != True (BigQuery's CI-detection flag is not set)
• details.installer.name is one of the interactive Python packaging tools: pip, uv, poetry, pdm, pipenv, or pipx (the asterisk in pip* covers pip itself plus pipenv and pipx, which delegate to pip and inherit its installer telemetry pattern)

Excluded (the things that inflate other badges):

• Mirrors: bandersnatch, Nexus, devpi, Artifactory, z3c.pypimirror
• Browser fetches via the PyPI web UI (installer_name == "Browser")
• Generic HTTP UAs used by scrapers and scanners (requests, curl, etc.)
• Unknown installer (installer_name == "None") — uncategorised traffic that in practice is dominated by automated scanners

For context on how much these can dwarf real installs: at v1 deploy time, one of the seed packages had 2,771 "non-CI" downloads in 30 days under a naïve mirror-and-all-installers query, of which 1,325 (48%) was bandersnatch alone and only 14 came from pip + uv + poetry + pdm. The honest signal is the 14.

The filter is fail-closed: a future pypinfo emitting a new mainstream installer will be excluded until the allowlist in src/pypi_winnow_downloads/collector.py is updated explicitly. That's a feature for a project whose pitch is honesty.

Install

pip install pypi-winnow-downloads

The collector queries Google's public PyPI BigQuery dataset via pypinfo, so before the first run you'll need a Google Cloud service account JSON key. Pypinfo's installation guide walks the full setup (create a GCP project, enable the BigQuery API, generate the JSON key) and recommends the broad BigQuery User role; the narrower pair BigQuery Job User + BigQuery Data Viewer also works and is what config.example.yaml and the reference deploy document. Then point service.credential_file in your config at the resulting file.

Run with a YAML config — copy config.example.yaml and edit:

winnow-collect --config /path/to/config.yaml

To deploy as a daily systemd timer plus a Caddy HTTPS service serving the output directory, see deploy/README.md.

Status

Alpha. Self-hosted reference deployment running at pypi-badges.intfar.com, producing daily badges for four target packages (the three seed packages in config.example.yaml plus pypi-winnow-downloads itself for the dogfood badge). Expect rough edges and possible breaking changes in the 0.x series.

Acknowledgments

This project rests on three pieces of upstream work:

• pypinfo by Ofek Lev: the BigQuery query layer for the PyPI download dataset. pypi-winnow-downloads is essentially a filter and badge writer wrapped around pypinfo.
• shields.io renders the endpoint badges. The collector emits the JSON shape that shields.io's endpoint badge consumes, so badges inherit its caching, theming, and SVG rendering.
• The bigquery-public-data.pypi.file_downloads dataset, hosted by Google as a public BigQuery dataset and populated by the PyPI Linehaul pipeline, is the underlying data source. Without it, no installer-level breakdown of PyPI downloads would be possible.

Designed and built collaboratively with Claude Code (Anthropic) across planning, implementation, review, and QA. Significant subsystems (the pypinfo XDG_DATA_HOME isolation, the sys.executable-based pypinfo resolver, the installer-allowlist filter, the deploy/ examples) emerged through that planner / Dev / QA loop.

License

Licensed under the Apache License, Version 2.0.

© 2026 Chris Means.