Plotly datasets: the CSVs behind the charting examples

A flat pile of data files with a catalogue on top

The plotly/datasets repository is described as the datasets used in Plotly examples and documentation, and the README calls it the Plotly Sample Datasets. The homepage is plotly.github.io/datasets, the licence is MIT, and the primary language is listed as HTML, which reflects that the catalogue itself is a rendered page rather than a program.

The repository is essentially a data directory. The top level is a long list of CSV files with descriptive names, such as 2010_alcohol_consumption_by_country.csv, 2011_us_ag_exports.csv, 2014_world_gdp_with_codes.csv, auto-mpg.csv, all_stocks_5yr.csv, and more unusual ones like 2018_Central_Park_Squirrel_Census_-_Squirrel_Data_20250721.csv. There is also a set of subdirectories for tutorial files: Dash-Course, Dash-Curriculum, Dash-Examle-Index, Dash_Bio, App-Challenges, Blog, Images, MATLAB, ag-grid and api_docs, plus a CODE_OF_CONDUCT.md and the LICENSE file.

The design is deliberately dumb, and that is its virtue. A file is a file, reachable by a raw URL, with no API, no schema registry and no query language. If a chart example in the documentation references a dataset, the dataset is a path in this repository, and the example works offline once you have cloned it.

That also means there is no versioning scheme for the data itself, only for the repository, so pinning a commit is the only way to keep a chart reproducible.

How the catalogue table is meant to be read

The README is a table, and the columns are what make the collection usable rather than merely large. Each row has a dataset name, a Best for column, an Origin column, a link to a chart example, a link to the download, and a link to open the data in Plotly.

The Best for column is the search index. Values include Maps, Basic, Multiple Axes, Streaming, Alpha Shapes, Clustergram and Dumbbell Plots, which tells you at a glance which file suits which kind of chart. The map group is large: 2010 alcohol consumption by country, 2011 February AA flight paths, 2011 February US airport traffic, 2011 US agriculture exports, 2014 Apple stock, 2014 ebola, 2014 US cities population, 2014 US states population, 2014 world GDP, 2015 precipitation, 2015 Shooting Incidents and globe contours.

The chart example column names the language of the tutorial, and this is the second useful thing about the table. There are JavaScript examples for choropleth maps and scatter plots on maps, Python examples for lines on maps, bubble maps and HTML reports, R examples for choropleth maps, scattermapbox and dumbbell plots, and Excel examples for grouped bar charts, bubble charts, three y axes, dot plots, insets, text scatter charts, LaTeX typesetting, heatmaps, Pareto charts and multiple axis charts, plus a Dash Bio example for the clustergram.

So the catalogue is effectively an index of which tutorial uses which file, which is how you are meant to use it: pick the chart type you want, follow the example link, and the data is already wired up.

The origin column is honest about what it does not know

The Origin column is the most valuable and the most awkward part of the table, because it says Unknown for a large share of the rows.

Entries with a real provenance tend to be the ones added most recently or the ones with a defined public source. The 2024 retail sales as a percentage of annual total is marked as adapted from the US Census Bureau. The Likert Scale responses from the 2002 General Social Survey altruism questions are marked as adapted from the General Social Survey, 2002, with a link to the GSS data explorer. The Gapminder data is credited to Jenny Bryan with a link to her own gapminder repository, and the prostate cancer clustergram data is credited to the Gene Expression Omnibus with a link to the NCBI GEO site.

Everything else, which is most of it, is listed as Unknown.

That is a limitation rather than a bug, and it is worth taking seriously. For a chart in a slide, unknown origin is irrelevant. For a dataset that ends up in a blog post claiming to describe something, or in a paper, unknown origin is disqualifying, because you cannot check the numbers, the collection method or the definitions of the columns.

The GitHub download links go to the raw file, so the data is directly usable, but usability and provenance are different properties, and this repository is strong on the first and quiet about the second. The adapted-from entries also carry their own caveat, since adapted means the shape of the original data has been changed for the chart.

Fetching a file: raw paths and non-CSV formats

There is no installation step. You clone the repository, or you fetch a single file over HTTPS, and you are done. The download links in the README point at the raw file path in the repository, for example the alcohol consumption file at 2010_alcohol_consumption_by_country.csv and the gapminder file at gapminderDataFiveYear.csv:

2010_alcohol_consumption_by_country.csv
gapminderDataFiveYear.csv

The filenames are the API. A dataset called 2014_world_gdp_with_codes.csv tells you the vintage and that country codes are included, and 2015_06_30_precipitation.csv tells you it is a single day of precipitation data. That is not much metadata, but it is enough to stop you loading the wrong file.

The collection is not only CSV. There are Parquet files, such as 2015_flights.parquet, JSON files including PK_subban_shots.json, BulletData.json and 3d-ribbon.json, and a .soft file for the clustergram data. Some files have spaces in their names, including Aids Data.csv, Antibiotics.csv and Canada Immigration.csv, which is a small annoyance for any script that assembles a path.

There are also files whose names start with a leading underscore character, such as _3d-line-plot.csv, and directories that hold whole tutorial projects rather than data. A repository that mixes flat data, tutorial code and images in one tree is easy to browse and awkward to depend on, and the practical advice is to copy the one file you need into your own project rather than vendoring the whole tree.

Open in Plotly and the old plot.ly links

Each row in the catalogue has an Open in Plotly column, which is a link to a chart studio plot where the data is already loaded, sometimes identified by a plot id and an owner name. The prostate cancer row points at the Dash Bio host for a clustergram, and the 2015 Shooting Incidents row points at chart-studio.plot.ly rather than the older plot.ly domain.

This column is the one to be careful with. The links are of two kinds, an example gallery link that demonstrates the chart type in a given language, and a live chart studio plot that contains the data in an editable form. Both are useful for seeing what a dataset looks like once plotted, and both are dependent on services outside the repository.

Some rows have N.A. in that column, and the absence is informative. The 2024 retail sales entry, the 2002 General Social Survey Likert responses, the NYC Uber rides entry and the prostate cancer clustergram all lack an open plot, which suggests they were added for specific documentation work rather than as gallery entries.

The point for an adopter is that the Open links are conveniences with an expiry date attached. The repository is the durable artefact, the chart studio links are not, and a tutorial that hard-codes one of those URLs will break at some point for reasons that have nothing to do with the data.

Maintenance: a data repository that changes when the docs do

The release history explains why this repository is unusual, and it is not a fault.

There are two tags, both from 2020: v0.0.1, described as adding the initial dash-sample-apps data, and dash-sample-apps, described as data for dash-sample-apps, both on 2020-08-14. The repository is not archived, and the last push was on 2026-05-04.

For a dataset repository, that release history is not a maintenance signal in the way it would be for a library. Data files do not need frequent releases, and a new file added for a documentation page does not warrant cutting a version. The relevant dates are the last push and the vintage of the individual files.

The vintages are the point. Most of the named datasets are from 2010 to 2016, with a few newer, such as the 2024 retail sales file and the squirrel census file whose name carries a 2025 date. A file called 2014_apple_stock.csv is a snapshot of the market as it was, and using it in a chart about current behaviour is a mistake that looks like a data problem and is really a vintage problem.

The MIT licence applies to the repository contents, which removes the licensing question for reuse. What the licence cannot do is tell you that the numbers are right, and for a large share of the catalogue nothing else in the repository will tell you that either.

Editorial conclusion

Use these datasets when you need a chart to work in the next ten minutes, particularly for a talk, a documentation page or a smoke test of a Plotly or Dash setup, because each file is already paired with a working example in a named language. Do not use them for analysis that has to be defensible, since a large share of the catalogue lists its origin as unknown and the files are years old. Before you rely on one, check the origin column, confirm the file matches the column names the tutorial expects, and pin the commit you used, since the repository's only releases date from 2020 and the last push was on 2026-05-04.

Frequently asked questions

Official sources

1. License: MIT
2. plotly/datasets on GitHub
3. Project website
4. README
5. Releases