pypistats

https://pypi.org/project/pypistats/
Admin
pypistats is a Python 3.6+ interface to the PyPI Stats API that provides command-line access to PyPI...
Tokens:7,831
Snippets:78
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install pypistats with NumPy and pandas extras

Source: https://pypi.org/project/pypistats/1.13.0

Install the pypistats library with optional dependencies for NumPy and pandas integration. Can install one or both extras.

```bash
pip install --upgrade "pypistats[numpy]"
pip install --upgrade "pypistats[pandas]"
pip install --upgrade "pypistats[numpy,pandas]"
```

--------------------------------

### Install pypistats from source

Source: https://pypi.org/project/pypistats/1.13.0

Installs the pypistats package from its source code repository.

```bash
git clone https://github.com/hugovk/pypistats
cd pypistats
python3 -m pip install .

```

--------------------------------

### Install pypistats from PyPI

Source: https://pypi.org/project/pypistats/1.13.0

Installs or upgrades the pypistats package using pip.

```bash
python3 -m pip install --upgrade pypistats

```

--------------------------------

### Get recent downloads for a package

Source: https://pypi.org/project/pypistats/1.13.0

Retrieve aggregate download counts for the last day, month, and week for a specified package. The output is formatted as a table.

```bash
$ pypistats recent pillow
┌───────────┬─────────────┬────────────┐
│  last_day │  last_month │  last_week │
├───────────┼─────────────┼────────────┤
│ 5,537,706 │ 225,816,599 │ 58,094,476 │
└───────────┴─────────────┴────────────┘


```

--------------------------------

### Get Python minor version downloads for last month

Source: https://pypi.org/project/pypistats/1.13.0

Query download statistics broken down by Python minor version for the previous month. The output includes category, percentage, and download counts.

```bash
$ pypistats python_minor pillow --last-month
┌──────────┬─────────┬─────────────┐
│ category │ percent │   downloads │
├──────────┼─────────┼─────────────┤
│ 3.12     │  29.56% │  70,503,800 │
│ 3.11     │  20.43% │  48,711,283 │
│ 3.10     │  14.74% │  35,149,431 │
│ 3.13     │  10.35% │  24,680,814 │
│ 3.9      │   8.24% │  19,640,729 │
│ 3.7      │   5.27% │  12,565,151 │
│ 3.8      │   3.45% │   8,231,134 │
│ null     │   3.24% │   7,734,467 │
│ 3.14     │   2.17% │   5,170,747 │
│ 3.6      │   1.85% │   4,406,662 │
│ 2.7      │   0.70% │   1,658,402 │
│ 3.5      │   0.01% │      19,506 │
│ 3.15     │   0.00% │       5,946 │
│ 3.4      │   0.00% │         866 │
│ 3.3      │   0.00% │          20 │
│ 3.2      │   0.00% │           1 │
│ Total    │         │ 238,478,959 │
└──────────┴─────────┴─────────────┘

Date range: 2025-12-01 - 2025-12-31


```

--------------------------------

### Return data as a NumPy array

Source: https://pypi.org/project/pypistats/1.13.0

Fetch download statistics and return them directly as a NumPy ndarray for further numerical processing. Requires the 'numpy' extra to be installed.

```python
import pypistats
numpy_array = pypistats.overall("pyvista", total="daily", format="numpy")
print(type(numpy_array))
# <class 'numpy.ndarray'>
print(numpy_array)
```

--------------------------------

### Fetch OS-specific download statistics

Source: https://pypi.org/project/pypistats/1.13.0

Get download statistics filtered by operating system (e.g., darwin, linux). Supports different output formats.

```python
print(pypistats.system("pillow"))
print(pypistats.system("pillow", os="darwin", format="markdown"))
print(pypistats.system("pillow", os="linux", format="rst"))
print(pypistats.system("pillow", os="darwin", format="html"))
pprint(pypistats.system("pillow", os="linux", format="json"))
```

--------------------------------

### Return data as a pandas DataFrame

Source: https://pypi.org/project/pypistats/1.13.0

Retrieve download statistics and return them as a pandas DataFrame. This is useful for data manipulation and analysis. Requires the 'pandas' extra to be installed.

```python
import pypistats
pandas_dataframe = pypistats.overall("pyvista", total="daily", format="pandas")
print(type(pandas_dataframe))
# <class 'pandas.core.frame.DataFrame'>
print(pandas_dataframe)
```

--------------------------------

### Fetch recent download statistics

Source: https://pypi.org/project/pypistats/1.13.0

Call the API to get recent download statistics for a package. Supports different timeframes (day, week, month) and output formats (markdown, rst, html, json).

```python
import pypistats
from pprint import pprint

# Call the API
print(pypistats.recent("pillow"))
print(pypistats.recent("pillow", "day", format="markdown"))
print(pypistats.recent("pillow", "week", format="rst"))
print(pypistats.recent("pillow", "month", format="html"))
pprint(pypistats.recent("pillow", "week", format="json"))
print(pypistats.recent("pillow", "day"))
```

--------------------------------

### Fetch Python major version download statistics

Source: https://pypi.org/project/pypistats/1.13.0

Get download statistics segmented by Python major version (e.g., 2 or 3). Accepts version as integer or string and supports multiple output formats.

```python
print(pypistats.python_major("pillow"))
print(pypistats.python_major("pillow", version=2, format="markdown"))
print(pypistats.python_major("pillow", version=3, format="rst"))
print(pypistats.python_major("pillow", version="2", format="html"))
pprint(pypistats.python_major("pillow", version="3", format="json"))
```

--------------------------------

### Show pypistats top-level help

Source: https://pypi.org/project/pypistats/1.13.0

Use the --help flag to display all available commands and options for the pypistats CLI.

```bash
$ pypistats --help
usage: pypistats [-h] [-V] {recent,overall,python_major,python_minor,system} ...

positional arguments:
  {recent,overall,python_major,python_minor,system}

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit


```

--------------------------------

### Query Recent Downloads for Local Package

Source: https://pypi.org/project/pypistats

Use a local path to specify the package. The tool will infer the package name from pyproject.toml or setup.cfg.

```bash
$ pypistats recent .
┌──────────┬────────────┬───────────┐
│ last_day │ last_month │ last_week │
├──────────┼────────────┼───────────┤
│    1,852 │     51,264 │    15,494 │
└──────────┴────────────┴───────────┘
```

--------------------------------

### Show pypistats recent subcommand help

Source: https://pypi.org/project/pypistats/1.13.0

Use the --help flag with a specific subcommand like 'recent' to see its available options and arguments.

```bash
$ pypistats recent --help
usage: pypistats recent [-h] [-p {day,week,month}]
                        [-f {html,json,pretty,md,markdown,rst,tsv}] [-j] [-v]
                        [package]

Retrieve the aggregate download quantities for the last 1/7/30 days, excluding
downloads from mirrors

positional arguments:
  package               package name, or dir to check pyproject.toml/setup.cfg
                        (default: .)

options:
  -h, --help            show this help message and exit
  -p, --period {day,week,month}
  -f, --format {html,json,pretty,md,markdown,rst,tsv}
                        The format of output (default: pretty)
  -j, --json            Shortcut for "-f json" (default: False)
  -v, --verbose         Print debug messages to stderr (default: False)


```

--------------------------------

### Show pypistats python_minor subcommand help

Source: https://pypi.org/project/pypistats/1.13.0

View the help message for the 'python_minor' subcommand to understand its specific options for querying Python version download data.

```bash
$ pypistats python_minor --help
usage: pypistats python_minor [-h] [-V VERSION]
                              [-f {html,json,pretty,md,markdown,rst,tsv}] [-j] 
                              [-sd yyyy-mm[-dd]|name] [-ed yyyy-mm[-dd]|name] 
                              [-m yyyy-mm|name] [-l] [-t] [-d] [--monthly] [-s SORT] 
                              [-c {yes,no,auto}] [-v] 
                              [package]

Retrieve the aggregate daily download time series by Python minor version number

positional arguments:
  package               package name, or dir to check pyproject.toml/setup.cfg
                        (default: .)

options:
  -h, --help            show this help message and exit
  -V, --version VERSION
                        eg. 2.7 or 3.6 (default: None)
  -f, --format {html,json,pretty,md,markdown,rst,tsv}
                        The format of output (default: pretty)
  -j, --json            Shortcut for "-f json" (default: False)
  -sd, --start-date yyyy-mm[-dd]|name
                        Start date (default: None)
  -ed, --end-date yyyy-mm[-dd]|name
                        End date (default: None)
  -m, --month yyyy-mm|name
                        Shortcut for -sd & -ed for a single month (default: None)
  -l, --last-month      Shortcut for -sd & -ed for last month (default: False)
  -t, --this-month      Shortcut for -sd for this month (default: False)
  -d, --daily           Show daily downloads (default: False)
  --monthly             Show monthly downloads (default: False)
  -s, --sort SORT       Column to sort by (for example: downloads, date, category)
                        (default: downloads)
  -c, --color {yes,no,auto}
                        Color terminal output (default: auto)
  -v, --verbose         Print debug messages to stderr (default: False)


```

--------------------------------

### Query Recent Downloads for Package by Path

Source: https://pypi.org/project/pypistats

Specify a relative path to a package directory to retrieve its recent download statistics.

```bash
$ pypistats recent ../Pillow
┌───────────┬─────────────┬────────────┐
│  last_day │  last_month │  last_week │
├───────────┼─────────────┼────────────┤
│ 5,537,706 │ 225,816,599 │ 58,094,476 │
└───────────┴─────────────┴────────────┘
```

--------------------------------

### Use Local Path for Package Name

Source: https://pypi.org/project/pypistats/1.13.0

Look up package name from pyproject.toml or setup.cfg when providing a local path.

```bash
$ pypistats recent .
┌──────────┬────────────┬───────────┐
│ last_day │ last_month │ last_week │
├──────────┼────────────┼───────────┤
│    1,852 │     51,264 │    15,494 │
└──────────┴────────────┴───────────┘
```

```bash
$ pypistats recent ../Pillow
┌───────────┬─────────────┬────────────┐
│  last_day │  last_month │  last_week │
├───────────┼─────────────┼────────────┤
│ 5,537,706 │ 225,816,599 │ 58,094,476 │
└───────────┴─────────────┴────────────┘
```

--------------------------------

### Equivalent commands for last month's Python major version downloads

Source: https://pypi.org/project/pypistats/1.13.0

Demonstrates alternative ways to specify the 'last month' period for fetching Python major version download statistics.

```bash
pypistats python_major pip --last-month
```

```bash
pypistats python_major pip --month april
```

--------------------------------

### Create overall downloads chart with pandas

Source: https://pypi.org/project/pypistats/1.13.0

Generate a plot of overall download trends over time, excluding mirror traffic, using pandas for data handling and plotting. Saves the chart to 'overall.png'.

```python
# Show overall downloads over time, excluding mirrors
import pypistats
data = pypistats.overall("pillow", total="daily", format="pandas")
data = data.groupby("category").get_group("without_mirrors").sort_values("date")

chart = data.plot(x="date", y="downloads", figsize=(10, 2))
chart.figure.show()
chart.figure.savefig("overall.png")  # alternatively
```

--------------------------------

### Fetch overall download statistics

Source: https://pypi.org/project/pypistats/1.13.0

Retrieve overall download statistics for a package, with an option to include or exclude mirror traffic. Supports various output formats.

```python
print(pypistats.overall("pillow"))
print(pypistats.overall("pillow", mirrors=True, format="markdown"))
print(pypistats.overall("pillow", mirrors=False, format="rst"))
print(pypistats.overall("pillow", mirrors=True, format="html"))
pprint(pypistats.overall("pillow", mirrors=False, format="json"))
```

--------------------------------

### Create Python 3 downloads chart with pandas

Source: https://pypi.org/project/pypistats/1.13.0

Visualize Python 3 download trends over time using pandas. The plot is generated from data fetched by pypistats and saved to 'python3.png'.

```python
# Show Python 3 downloads over time
import pypistats
data = pypistats.python_major("pillow", total="daily", format="pandas")
data = data.groupby("category").get_group(3).sort_values("date")

chart = data.plot(x="date", y="downloads", figsize=(10, 2))
chart.figure.show()
chart.figure.savefig("python3.png")  # alternatively
```

--------------------------------

### Sort by Date with Daily/Monthly Data

Source: https://pypi.org/project/pypistats/1.13.0

Sort statistics chronologically using `--sort date` with `--daily` or `--monthly` flags. Specify version for detailed breakdown.

```bash
$ pypistats python_minor pillow --daily --last-month --sort date --version 3.14
┌──────────┬────────────┬─────────┬───────────┐
│ category │    date    │ percent │ downloads │
├──────────┼────────────┼─────────┼───────────┤
│ 3.14     │ 2025-12-01 │   3.49% │   180,367 │
│ 3.14     │ 2025-12-02 │   4.08% │   210,894 │
│ 3.14     │ 2025-12-03 │   4.69% │   242,353 │
│ 3.14     │ 2025-12-04 │   3.98% │   205,681 │
│ 3.14     │ 2025-12-05 │   3.48% │   180,197 │
│ 3.14     │ 2025-12-06 │   2.50% │   129,155 │
│ 3.14     │ 2025-12-07 │   2.70% │   139,725 │
│ 3.14     │ 2025-12-08 │   4.19% │   216,851 │
│ 3.14     │ 2025-12-09 │   4.05% │   209,185 │
│ 3.14     │ 2025-12-10 │   4.20% │   217,293 │
│ 3.14     │ 2025-12-11 │   3.86% │   199,779 │
│ 3.14     │ 2025-12-12 │   3.20% │   165,700 │
│ 3.14     │ 2025-12-13 │   2.06% │   106,376 │
│ 3.14     │ 2025-12-14 │   2.40% │   124,187 │
│ 3.14     │ 2025-12-15 │   4.21% │   217,575 │
│ 3.14     │ 2025-12-16 │   3.91% │   202,199 │
│ 3.14     │ 2025-12-17 │   3.99% │   206,452 │
│ 3.14     │ 2025-12-18 │   3.80% │   196,669 │
│ 3.14     │ 2025-12-19 │   3.30% │   170,654 │
│ 3.14     │ 2025-12-20 │   2.17% │   112,086 │
│ 3.14     │ 2025-12-21 │   2.06% │   106,316 │
│ 3.14     │ 2025-12-22 │   3.01% │   155,770 │
│ 3.14     │ 2025-12-23 │   3.38% │   174,706 │
│ 3.14     │ 2025-12-24 │   2.57% │   132,813 │
│ 3.14     │ 2025-12-25 │   2.34% │   121,021 │
│ 3.14     │ 2025-12-26 │   2.23% │   115,560 │
│ 3.14     │ 2025-12-27 │   1.86% │    96,206 │
│ 3.14     │ 2025-12-28 │   2.06% │   106,483 │
│ 3.14     │ 2025-12-29 │   2.73% │   141,272 │
│ 3.14     │ 2025-12-30 │   4.09% │   211,290 │
│ 3.14     │ 2025-12-31 │   3.40% │   175,932 │
│ Total    │            │         │ 5,170,747 │
└──────────┴────────────┴─────────┴───────────┘

Date range: 2025-12-01 - 2025-12-31
```

--------------------------------

### Fetch Python minor version download statistics

Source: https://pypi.org/project/pypistats/1.13.0

Retrieve download statistics broken down by Python minor version (e.g., 2.7 or 3.7). Supports various output formats.

```python
print(pypistats.python_minor("pillow"))
print(pypistats.python_minor("pillow", version=2.7, format="markdown"))
print(pypistats.python_minor("pillow", version="2.7", format="rst"))
print(pypistats.python_minor("pillow", version=3.7, format="html"))
pprint(pypistats.python_minor("pillow", version="3.7", format="json"))
```

--------------------------------

### Specify Month for Statistics

Source: https://pypi.org/project/pypistats/1.13.0

Fetch statistics for a specific month using shorthand or full date format.

```bash
pypistats python_major pip --month apr
```

```bash
pypistats python_major pip --month 2019-04
```

--------------------------------

### Format Python minor version downloads as Markdown

Source: https://pypi.org/project/pypistats/1.13.0

Display Python minor version download statistics in Markdown table format, suitable for direct use in documentation or issue trackers.

```markdown
category | percent | downloads  
---|---|---  
3.12 | 29.56% | 70,503,800  
3.11 | 20.43% | 48,711,283  
3.10 | 14.74% | 35,149,431  
3.13 | 10.35% | 24,680,814  
3.9 | 8.24% | 19,640,729  
3.7 | 5.27% | 12,565,151  
3.8 | 3.45% | 8,231,134  
null | 3.24% | 7,734,467  
3.14 | 2.17% | 5,170,747  
3.6 | 1.85% | 4,406,662  
2.7 | 0.70% | 1,658,402  
3.5 | 0.01% | 19,506  
3.15 | 0.00% | 5,946  
3.4 | 0.00% | 866  
3.3 | 0.00% | 20  
3.2 | 0.00% | 1  
Total |  | 238,478,959  
Date range: 2025-12-01 - 2025-12-31

```

--------------------------------

### Specify Date Range for Statistics

Source: https://pypi.org/project/pypistats/1.13.0

Retrieve statistics within a custom date range using shorthand or full date formats.

```bash
pypistats python_major pip --start-date december --end-date january
```

```bash
pypistats python_major pip --start-date dec      --end-date jan
```

```bash
pypistats python_major pip --start-date 2018-12  --end-date 2019-01
```
Tokens:
Raw