# OWID's CO2 dataset is a CSV plus a trail back to every source > The owid/co2-data repository holds one CSV, one codebook and a README that traces every indicator back to its source dataset and to the exact processing code in the OWID ETL repository. The interesting part for anyone using the numbers is the changelog, which records unit changes and source swaps that silently break old analyses. **owid/co2-data** — Data on CO2 and greenhouse gas emissions by Our World in Data - Repository: https://github.com/owid/co2-data - Website: https://ourworldindata.org/co2-and-other-greenhouse-gas-emissions - Stars: 774 · Forks: 300 - Language: Unknown - License: not declared - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/owid-co2-data ## Four files in the repository, and the real work is elsewhere The owid/co2-data repository is one of the smallest in this catalogue, and its size is the point. The top-level entries are a .gitignore, the README, an `owid-co2-codebook.csv` and an `owid-co2-data.csv`. There is no code, no pipeline, no build script. The repository is the published artefact and the documentation of how it was produced. The description says it plainly. The complete CO2 and Greenhouse Gas Emissions dataset is a collection of key metrics maintained by Our World in Data, updated regularly, and including data on CO2 emissions in annual, per capita, cumulative and consumption-based forms, other greenhouse gases, energy mix, and other relevant metrics. The outputs are three formats of the same thing, downloadable from the OWID public data host: ``` https://owid-public.owid.io/data/co2/owid-co2-data.csv https://owid-public.owid.io/data/co2/owid-co2-data.xlsx https://owid-public.owid.io/data/co2/owid-co2-data.json ``` The structural difference between them is documented. The CSV and XLSX files follow a format of 1 row per location and year, so the table is wide, one row per country per year with every indicator as a column. The JSON version is split by country, with an array of yearly records inside each country, so it is the same information shaped for a document store rather than for a dataframe. That distinction matters if you are loading this into a tool. The CSV is a denormalised wide table that most analysis tools want; the JSON is nested per country, which is friendlier for a web application that renders one country at a time. ## The codebook is what makes the CSV usable A wide emissions CSV with no documentation is a trap, and the codebook is the answer to it. A full codebook is made available at owid-co2-codebook.csv, with a description and source for each indicator in the dataset. It is also included as an additional sheet in the XLSX file, which is a practical detail: if you download the spreadsheet you get the documentation in the same file. This is the part of the project that most affects whether you can trust what you compute. Any indicator in the emissions family has a reasonable chance of having a unit that changed at some point, and a description that tells you what the column actually contains, and which upstream source it came from, is what lets you notice when a value means something different than it did last year. The changelog shows why that matters concretely. The most recent entry, dated 2026-06-01, records two changes. The dataset was updated to use the latest EIA's International Energy Data. And the units of the carbon intensity of energy indicators were changed from kilograms to grams of CO2 per kilowatt-hour. That second change is exactly the kind of thing that silently breaks an analysis. A dashboard computing emissions per unit of energy would show numbers a thousand times larger after the update, with no error and no missing values, because the column is still populated and still plausible. Nothing in the CSV would tell you. The changelog does. ## Every indicator traces back to a dated processing script The source data section of the README is where this project is unusual, and it is the reason to trust the numbers. The dataset is built upon a number of datasets and processing steps, and for each one, the README links the source data and then the code at every stage. The pattern is consistent: an ingestion step in a snapshots directory, a basic processing step in a meadow directory, and a further processing step in a garden directory, all inside the OWID ETL repository, with a date in the path. The Global Carbon Budget from the Global Carbon Project is the anchor, dated 2025-11-13. National contributions to climate change from Jones et al., dated 2025-12-04, and hosted on Zenodo. The Statistical Review of World Energy from the Energy Institute, dated 2025-06-27. International energy data from the US Energy Information Administration, dated 2026-05-05, and it is a dvc-tracked zip file. The Maddison Project Database from the University of Groningen GGDC, dated 2024-04-26, by Bolt and van Zanden. The dates are the point. A snapshot dated 2025-11-13 means the pipeline will reproduce the same numbers from the same inputs, and the number itself tells you when the underlying source was last refreshed. Then there are the derived indicators, which is where most of the analysis lives. To construct indicators per capita, per GDP, and per unit energy, the README lists Regions from OWID, Population from OWID based on a number of different sources, Income groups from the World Bank, the Maddison Project Database for GDP, the Energy Institute statistical review, the EIA international energy data, and a processing step for primary energy consumption that combines the EI statistical review with the EIA international energy data. So a per-capita figure is a global carbon budget number divided by an OWID population figure for a country in a region that OWID defines, and every one of those four steps is a link in the README. ## The changelog reads as a history of the data, not just the code The changelog is the most revealing part of the documentation, because it records the times when the meaning of a column changed. The 2024-11-21 entry is the important one. The dataset and codebook were updated to use the latest version of the Global Carbon Budget for 2024 and Jones et al. for 2024, version 2024.2. And from that point, methane, nitrous oxide, and total greenhouse gas emissions data come from Jones et al. instead of Climate Watch, to provide a wider data coverage. That is a source swap for three of the most used indicators in the dataset. A chart of methane emissions built on Climate Watch and one built on Jones et al. are not the same series, and the difference is invisible in the data itself. The 2023-12-05 entry records a change that would break a join. In the Global Carbon Budget for 2023, International transport was replaced by International aviation and International shipping, and some overseas territories have no data in that version. The 2023-12-28 entry is a good example of a change that is not a change. It updated the primary energy consumption, and the parenthetical is explicit: to update metadata, nothing has changed in the data. That is a maintainer telling you that a row in the changelog does not necessarily mean the numbers moved. Other entries cover the 2025-11-13 update to the Global Carbon Budget for 2025, the 2025-12-04 update of greenhouse gases using the latest data from Jones et al. from 2025, the 2024-06-20 update of data from the Statistical Review of World Energy and the Maddison Project Database, the 2024-04-10 update to Jones et al. for 2024, and the 2023-12-28 enhancement of the codebook with improved descriptions, added units and updated sources. The final push to the repository was on 2026-06-02, which lines up with the 2026-06-01 changelog entry. There are no GitHub releases, so the changelog and the downloadable files are the versioning mechanism, and there is no tag to pin. ## Where this sits against the raw sources and the OWID grapher The comparison worth making is with using the upstream datasets directly, and with using the OWID charting platform instead of the CSV. Going to the source, which for the carbon budget means globalcarbonbudgetdata.org and for the energy statistics means the Energy Institute and the EIA, gives you the original publication. You also lose the per-capita and per-GDP indicators, you have to do the region and population joins yourself, and you have to track each source's own update schedule. The value of the OWID dataset is that those joins and the derived indicators are already done and documented, in a single wide table with a codebook. The main cost of that convenience is the one the changelog keeps making visible. A consolidated dataset has to pick a source when two are available, and when it switches, the series changes. If you need the Climate Watch methane series specifically, this dataset after November 2024 is not giving it to you. The same distinction applies to a charting tool built on top of this data. A chart answers one question; the CSV holds the full table for a question you have not thought of yet. What the repository does not offer is a local pipeline. The processing code is in the owid/etl repository, and at least one ingestion step is a dvc-tracked file, so reproducing the dataset locally means running that pipeline rather than running anything here. The codebook is also worth reading as a description of the indicators rather than of the pipeline, since it covers what each column is and where it came from but not how to rebuild it. ## Conclusion Adopt the OWID CO2 dataset if you need country-level emissions, per capita and cumulative figures, greenhouse gas data and energy mix in one tidy table with a codebook attached, since the CSV and XLSX are 1 row per location and year and need no reshaping. Skip it if you need sub-national granularity or live data, since most metrics are published annually, or if your pipeline cannot handle a source swap, because the changelog shows the underlying datasets being replaced over time. Verify first that you re-download on each use rather than caching a CSV, that your analysis re-reads the codebook for units, and that you check the changelog for changes to the indicators you actually use. ## FAQ ### How do I download the OWID CO2 and greenhouse gas dataset? Three formats are published on the OWID public data host, as CSV, XLSX and JSON. The CSV and XLSX follow a format of 1 row per location and year, and the JSON version is split by country with an array of yearly records. The codebook is included as an additional sheet in the XLSX file. ### What is in the owid-co2-codebook.csv file? It is a full codebook with a description and source for each indicator in the dataset, and it is also included as an additional sheet in the XLSX download. The 2023-12-28 changelog entry records an enhancement to it with improved descriptions, added units and updated sources. ### How do I trace an indicator back to its source? The README links the source data and then the ingestion, basic processing and further processing code for each source dataset, with a date in each path inside the OWID ETL repository. Derived indicators such as per capita, per GDP and per unit energy each have their own processing code linked. ## Sources - [Issues](https://github.com/owid/co2-data/issues) - [owid/co2-data on GitHub](https://github.com/owid/co2-data) - [Project website](https://ourworldindata.org/co2-and-other-greenhouse-gas-emissions) - [README](https://github.com/owid/co2-data/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/owid-co2-data