Shopify Product Taxonomy → CSV

A small, dependency-free tool that scrapes the Shopify Product Taxonomy and writes it to CSV, organized by the category tree — Level 1 vertical → subcategories → attribute → value — with the descriptions supplied by the source.

Release mirrored: https://shopify.github.io/product-taxonomy/releases/2026-05/

How it works (and why it isn't slow)

The public taxonomy pages are heavy because the browser renders the entire taxonomy client-side. Rather than scrape rendered HTML, this tool reads the same data from the machine-readable source files the site is generated from, and joins them:

• categories.json — the category tree (26 "Level 1" verticals, nested up to 8 levels deep) and, on each category, the attributes that apply to it (with a category-specific name and description).
• attributes.json — every attribute and its list of allowed values.

https://raw.githubusercontent.com/Shopify/product-taxonomy/v2026-05/dist/en/categories.json
https://raw.githubusercontent.com/Shopify/product-taxonomy/v2026-05/dist/en/attributes.json

The --release 2026-05 flag resolves to the git tag v2026-05, which is taxonomy version 2026-05 — the release you linked.

Why a join is required (the important part)

The attributes page alone cannot tell you which category an attribute belongs to — that link only exists in categories.json. So the tool walks the category tree and, for each category, emits its attributes; the attribute values are looked up from attributes.json.

Worked example (verified against the data): the attribute “3D glasses fit design” appears in exactly one place in the tree — Electronics › Video › Video Accessories › 3D Glasses — so it lands in the CSV as:

Category	Level 2	Level 3	Level 4	…	Attribute	Value	Description
Electronics	Video	Video Accessories	3D Glasses		3D glasses fit design	Clip-on	Indicates how the glasses are worn or attached…

Extended attributes

Some categories reference extended attributes — category-specific display names for a shared base attribute (e.g. “Liner features” and “Diaper features” are both the base attribute “Absorbent hygiene product features”). They carry the same base id, so the tool joins on attribute id (not handle) to pull values. This is verified: all extended attributes resolve by id and expose the base attribute's full value set. The category-specific name is what you'll see in the Attribute column.

Output columns

Default (--grain value):

Column	Meaning	Example
Category	Level 1 vertical	Electronics
Level 2 … Level 8	deeper category tiers (blank when the branch is shallower)	Video, Video Accessories, 3D Glasses, …
Attribute	attribute name as shown for that category	3D glasses fit design
Value	one attribute value	Clip-on
Description	the attribute's description, from the source	Indicates how the glasses are worn…

Add --ids to append traceability columns: CategoryID, CategoryFullName, Extended, AttributeHandle, AttributeID, ValueHandle, ValueID.

The CSV is written as UTF‑8 with a BOM (utf-8-sig) so it opens cleanly in Excel on Windows.

Grain (row count) — and the Excel limit

Grain	Rows (2026-05)	Notes
--grain value (default)	2,340,186	One row per category → attribute → value. Fully granular. Exceeds Excel's 1,048,576-row limit — see below.
--grain attribute	92,695	One row per category → attribute (no Value column). Opens in Excel directly. Good overview.

Because the value grain is ~2.34M rows, a single CSV won't fully open in Excel. Three ways to handle it:

1. --split-by-vertical — writes one CSV per Level 1 vertical into a folder. Every vertical is under the Excel limit (largest is Sporting Goods at ~397K rows), so each file opens directly in Excel. This is the recommended way to work in Excel.
2. --grain attribute — the 92,695-row overview opens as a single sheet.
3. Open the full file with pandas or Excel Power Query / Get Data (no row limit on import).

Requirements

• Python 3.8+ — the only requirement. No pip install; standard library only (urllib, json, csv, zipfile).
• Check with: python --version (or py --version on Windows).
• No Python yet? https://www.python.org/downloads/ — on Windows, tick “Add python.exe to PATH.”

Running it on Windows

1. Double-click run.bat — finds Python automatically (python, then the py launcher), runs the default export, and keeps the window open.

2. From PowerShell or Command Prompt in this folder:

REM Excel-friendly per-vertical files (recommended):
python shopify_taxonomy_to_csv.py --split-by-vertical --outdir by_vertical

REM Single-sheet overview (no values):
python shopify_taxonomy_to_csv.py --grain attribute --out overview.csv

REM Full granular single file (needs pandas/Power Query to open fully):
python shopify_taxonomy_to_csv.py --out full.csv

If python isn't recognized, use py instead (the Windows launcher).

3. Git Bash / WSL: use the macOS/Linux instructions below.

Running it on macOS / Linux

chmod +x run.sh                 # first time only
./run.sh --split-by-vertical --outdir by_vertical
# or directly:
python3 shopify_taxonomy_to_csv.py --grain attribute --out overview.csv

All options

--release 2026-05        Release (default 2026-05). Use 'main' for the unstable head.
--grain value|attribute  value = per category/attribute/value (default); attribute = per category/attribute.
--ids                    Append id/handle traceability columns.
--out FILE               Output path (single-file mode). Default: shopify_taxonomy.csv
--split-by-vertical      Write one CSV per Level 1 vertical (each under Excel's row limit).
--outdir DIR             Folder for --split-by-vertical. Default: shopify_taxonomy_by_vertical
--categories FILE        Local categories.json (offline mode; requires --attributes too).
--attributes FILE        Local attributes.json (offline mode; requires --categories too).

Offline / air-gapped use

Download both files on a connected machine:

https://raw.githubusercontent.com/Shopify/product-taxonomy/v2026-05/dist/en/categories.json
https://raw.githubusercontent.com/Shopify/product-taxonomy/v2026-05/dist/en/attributes.json

then:

python shopify_taxonomy_to_csv.py --categories categories.json --attributes attributes.json --split-by-vertical

Files in this folder

• shopify_taxonomy_to_csv.py — the tool (cross-platform, standard library only)
• run.bat — Windows double-click / CLI wrapper
• run.sh — macOS / Linux / Git Bash wrapper
• shopify_taxonomy_categories_attributes.csv — pre-generated attribute-grain overview (92,695 rows; opens in Excel)
• shopify_taxonomy_by_vertical.zip — pre-generated value-grain export, split into 26 per-vertical CSVs (2,340,186 rows total; each file opens in Excel)