{"id":15359151,"url":"https://github.com/hugovk/pypistats","last_synced_at":"2025-12-29T12:39:25.008Z","repository":{"id":33173382,"uuid":"149862343","full_name":"hugovk/pypistats","owner":"hugovk","description":"Command-line interface to PyPI Stats API to get download stats for Python packages","archived":false,"fork":false,"pushed_at":"2025-05-02T10:31:56.000Z","size":938,"stargazers_count":212,"open_issues_count":3,"forks_count":29,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-02T11:28:18.842Z","etag":null,"topics":["api","cli","command-line","command-line-tool","downloads","hacktoberfest","pypi","python","python3","statistics","stats"],"latest_commit_sha":null,"homepage":"https://pypistats.org/api/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hugovk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-09-22T09:19:12.000Z","updated_at":"2025-05-02T10:51:46.000Z","dependencies_parsed_at":"2023-02-19T10:16:04.250Z","dependency_job_id":"a0d4c936-51c6-486a-a06f-a34d92b48090","html_url":"https://github.com/hugovk/pypistats","commit_stats":{"total_commits":724,"total_committers":13,"mean_commits":55.69230769230769,"dds":0.3646408839779005,"last_synced_commit":"4493e70a2903306095901612492279d4ccd07a27"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugovk%2Fpypistats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugovk%2Fpypistats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugovk%2Fpypistats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hugovk%2Fpypistats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hugovk","download_url":"https://codeload.github.com/hugovk/pypistats/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319715,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cli","command-line","command-line-tool","downloads","hacktoberfest","pypi","python","python3","statistics","stats"],"created_at":"2024-10-01T12:43:57.227Z","updated_at":"2025-12-29T12:39:24.998Z","avatar_url":"https://github.com/hugovk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pypistats\n\n[![PyPI version](https://img.shields.io/pypi/v/pypistats.svg?logo=pypi\u0026logoColor=FFE873)](https://pypi.org/project/pypistats/)\n[![Supported Python versions](https://img.shields.io/pypi/pyversions/pypistats.svg?logo=python\u0026logoColor=FFE873)](https://pypi.org/project/pypistats/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/pypistats.svg)](https://pypistats.org/packages/pypistats)\n[![Azure Pipelines status](https://dev.azure.com/hugovk/hugovk/_apis/build/status/hugovk.pypistats?branchName=main)](https://dev.azure.com/hugovk/hugovk/_build?definitionId=1)\n[![GitHub Actions status](https://github.com/hugovk/pypistats/workflows/Test/badge.svg)](https://github.com/hugovk/pypistats/actions)\n[![Codecov](https://codecov.io/gh/hugovk/pypistats/branch/main/graph/badge.svg)](https://codecov.io/gh/hugovk/pypistats)\n[![Licence](https://img.shields.io/github/license/hugovk/pypistats.svg)](LICENSE.txt)\n[![DOI](https://zenodo.org/badge/149862343.svg)](https://zenodo.org/badge/latestdoi/149862343)\n[![Code style: Black](https://img.shields.io/badge/code%20style-Black-000000.svg)](https://github.com/psf/black)\n\nPython interface to [PyPI Stats API](https://pypistats.org/api) to get aggregate\ndownload statistics on Python packages on the Python Package Index without having to\nexecute queries directly against Google BigQuery.\n\nData is available for the [last 180 days](https://pypistats.org/about#data). (For longer\ntime periods, [pypinfo](https://github.com/ofek/pypinfo) can help, you'll need an API\nkey and get free quota.)\n\n## Installation\n\n### From PyPI\n\n```bash\npython3 -m pip install --upgrade pypistats\n```\n\n### From source\n\n```bash\ngit clone https://github.com/hugovk/pypistats\ncd pypistats\npython3 -m pip install .\n```\n\n## Example command-line use\n\nRun `pypistats` with a subcommand (corresponding to\n[PyPI Stats endpoints](https://pypistats.org/api/#endpoints)), then options for that\nsubcommand.\n\nTop-level help:\n\n\u003c!-- [[[cog\nfrom scripts.run_command import run\nrun(\"pypistats --help\")\n]]] --\u003e\n\n```console\n$ pypistats --help\nusage: pypistats [-h] [-V] {recent,overall,python_major,python_minor,system} ...\n\npositional arguments:\n  {recent,overall,python_major,python_minor,system}\n\noptions:\n  -h, --help            show this help message and exit\n  -V, --version         show program's version number and exit\n```\n\n\u003c!-- [[[end]]] --\u003e\n\nHelp for a subcommand:\n\n\u003c!-- [[[cog run(\"pypistats recent --help\") ]]] --\u003e\n\n```console\n$ pypistats recent --help\nusage: pypistats recent [-h] [-p {day,week,month}]\n                        [-f {html,json,pretty,md,markdown,rst,tsv}] [-j] [-v]\n                        package\n\nRetrieve the aggregate download quantities for the last 1/7/30 days,\nexcluding downloads from mirrors\n\npositional arguments:\n  package               package name, or dir to check pyproject.toml/setup.cfg (default: .)\n\noptions:\n  -h, --help            show this help message and exit\n  -p, --period {day,week,month}\n  -f, --format {html,json,pretty,md,markdown,rst,tsv}\n                        The format of output (default: pretty)\n  -j, --json            Shortcut for \"-f json\" (default: False)\n  -v, --verbose         Print debug messages to stderr (default: False)\n```\n\n\u003c!-- [[[end]]] --\u003e\n\nGet recent downloads:\n\n\u003c!-- [[[cog run(\"pypistats recent pillow\") ]]] --\u003e\n\n```console\n$ pypistats recent pillow\n┌───────────┬─────────────┬────────────┐\n│  last_day │  last_month │  last_week │\n├───────────┼─────────────┼────────────┤\n│ 7,099,431 │ 184,980,272 │ 43,134,813 │\n└───────────┴─────────────┴────────────┘\n```\n\n\u003c!-- [[[end]]] --\u003e\n\nHelp for another subcommand:\n\n\u003c!-- [[[cog run(\"pypistats python_minor --help\") ]]] --\u003e\n\n```console\n$ pypistats python_minor --help\nusage: pypistats python_minor [-h] [-V VERSION]\n                              [-f {html,json,pretty,md,markdown,rst,tsv}] [-j]\n                              [-sd yyyy-mm[-dd]|name] [-ed yyyy-mm[-dd]|name]\n                              [-m yyyy-mm|name] [-l] [-t] [-d] [--monthly]\n                              [-c {yes,no,auto}] [-v]\n                              package\n\nRetrieve the aggregate daily download time series by Python minor version number\n\npositional arguments:\n  package               package name, or dir to check pyproject.toml/setup.cfg (default: .)\n\noptions:\n  -h, --help            show this help message and exit\n  -V, --version VERSION\n                        eg. 2.7 or 3.6 (default: None)\n  -f, --format {html,json,pretty,md,markdown,rst,tsv}\n                        The format of output (default: pretty)\n  -j, --json            Shortcut for \"-f json\" (default: False)\n  -sd, --start-date yyyy-mm[-dd]|name\n                        Start date (default: None)\n  -ed, --end-date yyyy-mm[-dd]|name\n                        End date (default: None)\n  -m, --month yyyy-mm|name\n                        Shortcut for -sd \u0026 -ed for a single month (default: None)\n  -l, --last-month      Shortcut for -sd \u0026 -ed for last month (default: False)\n  -t, --this-month      Shortcut for -sd for this month (default: False)\n  -d, --daily           Show daily downloads (default: False)\n  --monthly             Show monthly downloads (default: False)\n  -c, --color {yes,no,auto}\n                        Color terminal output (default: auto)\n  -v, --verbose         Print debug messages to stderr (default: False)\n```\n\n\u003c!-- [[[end]]] --\u003e\n\nGet version downloads:\n\n\u003c!-- [[[cog run(\"pypistats python_minor pillow --last-month\") ]]] --\u003e\n\n```console\n$ pypistats python_minor pillow --last-month\n┌──────────┬─────────┬─────────────┐\n│ category │ percent │   downloads │\n├──────────┼─────────┼─────────────┤\n│ 3.11     │  21.79% │  39,303,874 │\n│ 3.12     │  18.85% │  34,005,926 │\n│ 3.10     │  16.91% │  30,503,181 │\n│ 3.9      │  12.22% │  22,039,674 │\n│ 3.7      │   9.35% │  16,857,870 │\n│ 3.13     │   8.24% │  14,866,029 │\n│ 3.8      │   5.47% │   9,860,598 │\n│ null     │   4.99% │   9,003,488 │\n│ 3.6      │   1.86% │   3,360,527 │\n│ 2.7      │   0.30% │     550,163 │\n│ 3.14     │   0.01% │      19,461 │\n│ 3.5      │   0.01% │      17,119 │\n│ 3.4      │   0.00% │         579 │\n│ 3.15     │   0.00% │         398 │\n│ 2.6      │   0.00% │          20 │\n│ 3.3      │   0.00% │          19 │\n│ 3.1      │   0.00% │           1 │\n│ Total    │         │ 180,388,927 │\n└──────────┴─────────┴─────────────┘\n\nDate range: 2025-07-01 - 2025-07-31\n```\n\n\u003c!-- [[[end]]] --\u003e\n\nYou can format in Markdown, ready for pasting in GitHub issues and PRs:\n\n\u003c!-- [[[cog run(\"pypistats python_minor pillow --last-month --format md\", with_console=False) ]]] --\u003e\n\n| category | percent |   downloads |\n| :------- | ------: | ----------: |\n| 3.11     |  21.79% |  39,303,874 |\n| 3.12     |  18.85% |  34,005,926 |\n| 3.10     |  16.91% |  30,503,181 |\n| 3.9      |  12.22% |  22,039,674 |\n| 3.7      |   9.35% |  16,857,870 |\n| 3.13     |   8.24% |  14,866,029 |\n| 3.8      |   5.47% |   9,860,598 |\n| null     |   4.99% |   9,003,488 |\n| 3.6      |   1.86% |   3,360,527 |\n| 2.7      |   0.30% |     550,163 |\n| 3.14     |   0.01% |      19,461 |\n| 3.5      |   0.01% |      17,119 |\n| 3.4      |   0.00% |         579 |\n| 3.15     |   0.00% |         398 |\n| 2.6      |   0.00% |          20 |\n| 3.3      |   0.00% |          19 |\n| 3.1      |   0.00% |           1 |\n| Total    |         | 180,388,927 |\n\nDate range: 2025-07-01 - 2025-07-31\n\n\u003c!-- [[[end]]] --\u003e\n\nThese are equivalent (in May 2019):\n\n```sh\npypistats python_major pip --last-month\npypistats python_major pip --month april\npypistats python_major pip --month apr\npypistats python_major pip --month 2019-04\n```\n\nAnd:\n\n```sh\npypistats python_major pip --start-date december --end-date january\npypistats python_major pip --start-date dec      --end-date jan\npypistats python_major pip --start-date 2018-12  --end-date 2019-01\n```\n\nAlternatively, use a local path as the package to look up the name from `pyproject.toml`\nor `setup.cfg`:\n\n\u003c!-- [[[cog run(\"pypistats recent .\") ]]] --\u003e\n\n```console\n$ pypistats recent .\n┌──────────┬────────────┬───────────┐\n│ last_day │ last_month │ last_week │\n├──────────┼────────────┼───────────┤\n│    1,557 │     75,440 │     8,864 │\n└──────────┴────────────┴───────────┘\n```\n\n\u003c!-- [[[end]]] --\u003e\n\n\u003c!-- [[[cog run(\"pypistats recent ../Pillow\") ]]] --\u003e\n\n```console\n$ pypistats recent ../Pillow\n┌───────────┬─────────────┬────────────┐\n│  last_day │  last_month │  last_week │\n├───────────┼─────────────┼────────────┤\n│ 7,099,431 │ 184,980,272 │ 43,134,813 │\n└───────────┴─────────────┴────────────┘\n```\n\n\u003c!-- [[[end]]] --\u003e\n\n## Example programmatic use\n\nReturn values are from the JSON responses documented in the API:\nhttps://pypistats.org/api/\n\n```python\nimport pypistats\nfrom pprint import pprint\n\n# Call the API\nprint(pypistats.recent(\"pillow\"))\nprint(pypistats.recent(\"pillow\", \"day\", format=\"markdown\"))\nprint(pypistats.recent(\"pillow\", \"week\", format=\"rst\"))\nprint(pypistats.recent(\"pillow\", \"month\", format=\"html\"))\npprint(pypistats.recent(\"pillow\", \"week\", format=\"json\"))\nprint(pypistats.recent(\"pillow\", \"day\"))\n\nprint(pypistats.overall(\"pillow\"))\nprint(pypistats.overall(\"pillow\", mirrors=True, format=\"markdown\"))\nprint(pypistats.overall(\"pillow\", mirrors=False, format=\"rst\"))\nprint(pypistats.overall(\"pillow\", mirrors=True, format=\"html\"))\npprint(pypistats.overall(\"pillow\", mirrors=False, format=\"json\"))\n\nprint(pypistats.python_major(\"pillow\"))\nprint(pypistats.python_major(\"pillow\", version=2, format=\"markdown\"))\nprint(pypistats.python_major(\"pillow\", version=3, format=\"rst\"))\nprint(pypistats.python_major(\"pillow\", version=\"2\", format=\"html\"))\npprint(pypistats.python_major(\"pillow\", version=\"3\", format=\"json\"))\n\nprint(pypistats.python_minor(\"pillow\"))\nprint(pypistats.python_minor(\"pillow\", version=2.7, format=\"markdown\"))\nprint(pypistats.python_minor(\"pillow\", version=\"2.7\", format=\"rst\"))\nprint(pypistats.python_minor(\"pillow\", version=3.7, format=\"html\"))\npprint(pypistats.python_minor(\"pillow\", version=\"3.7\", format=\"json\"))\n\nprint(pypistats.system(\"pillow\"))\nprint(pypistats.system(\"pillow\", os=\"darwin\", format=\"markdown\"))\nprint(pypistats.system(\"pillow\", os=\"linux\", format=\"rst\"))\nprint(pypistats.system(\"pillow\", os=\"darwin\", format=\"html\"))\npprint(pypistats.system(\"pillow\", os=\"linux\", format=\"json\"))\n```\n\n### NumPy and pandas\n\nTo use with either NumPy or pandas, make sure they are first installed, or:\n\n```bash\npip install --upgrade \"pypistats[numpy]\"\npip install --upgrade \"pypistats[pandas]\"\npip install --upgrade \"pypistats[numpy,pandas]\"\n```\n\nReturn data in a NumPy array for further processing:\n\n```python\nimport pypistats\nnumpy_array = pypistats.overall(\"pyvista\", total=\"daily\", format=\"numpy\")\nprint(type(numpy_array))\n# \u003cclass 'numpy.ndarray'\u003e\nprint(numpy_array)\n#[['with_mirrors' '2025-04-09' '1.40%' 40033]\n# ['without_mirrors' '2025-04-09' '1.39%' 39906]\n# ['with_mirrors' '2025-04-07' '1.36%' 39014]\n# ...\n# ['with_mirrors' '2025-01-18' '0.17%' 4827]\n# ['without_mirrors' '2025-01-18' '0.17%' 4795]\n# ['Total' None None 2869617]]\n```\n\nOr in a pandas DataFrame:\n\n```python\nimport pypistats\npandas_dataframe = pypistats.overall(\"pyvista\", total=\"daily\", format=\"pandas\")\nprint(type(pandas_dataframe))\n# \u003cclass 'pandas.core.frame.DataFrame'\u003e\nprint(pandas_dataframe)\n#             category        date percent  downloads\n# 0       with_mirrors  2025-04-09   1.40%      40033\n# 1    without_mirrors  2025-04-09   1.39%      39906\n# 2       with_mirrors  2025-04-07   1.36%      39014\n# 3    without_mirrors  2025-04-07   1.35%      38837\n# 4       with_mirrors  2025-04-06   1.08%      30988\n# ..               ...         ...     ...        ...\n# 358     with_mirrors  2024-12-28   0.17%       5011\n# 359  without_mirrors  2024-12-28   0.17%       4987\n# 360     with_mirrors  2025-01-18   0.17%       4827\n# 361  without_mirrors  2025-01-18   0.17%       4795\n# 362            Total        None    None    2869617\n#\n# [363 rows x 4 columns]\n```\n\nFor example, create charts with pandas:\n\n```python\n# Show overall downloads over time, excluding mirrors\nimport pypistats\ndata = pypistats.overall(\"pillow\", total=\"daily\", format=\"pandas\")\ndata = data.groupby(\"category\").get_group(\"without_mirrors\").sort_values(\"date\")\n\nchart = data.plot(x=\"date\", y=\"downloads\", figsize=(10, 2))\nchart.figure.show()\nchart.figure.savefig(\"overall.png\")  # alternatively\n```\n\n![overall.png](example/overall.png)\n\n```python\n# Show Python 3 downloads over time\nimport pypistats\ndata = pypistats.python_major(\"pillow\", total=\"daily\", format=\"pandas\")\ndata = data.groupby(\"category\").get_group(3).sort_values(\"date\")\n\nchart = data.plot(x=\"date\", y=\"downloads\", figsize=(10, 2))\nchart.figure.show()\nchart.figure.savefig(\"python3.png\")  # alternatively\n```\n\n![python3.png](example/python3.png)\n\n## See also\n\nRelated projects\n\n- https://github.com/ofek/pypinfo\n- https://github.com/scivision/pypistats-plots\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhugovk%2Fpypistats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhugovk%2Fpypistats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhugovk%2Fpypistats/lists"}