OpenSea Drop Metadata CSV: Columns, Rules and a Free Maker

What the drop CSV is for

When you set up a drop in OpenSea Studio, you upload your final images and one metadata file. OpenSea says the metadata file “specifies which file maps to which token ID and contains the traits for each NFT” (OpenSea Help), and it takes that file as a CSV only: “OpenSea only supports .csv files for metadata uploads” (Drops FAQ).

A CSV is a plain spreadsheet file: one line per row, with commas between the cells.

The columns

The rules come from the README inside the example you get with “Download Example” on OpenSea’s help page. Our copy was downloaded on 18 September 2026.

The example file’s own header line reads:

tokenID,name,description,file_name,external_url,attributes[Eyes],attributes[Tier],attributes[Birthday]

The rules that trip people up

tokenIDs from 1, with no gaps

The README: “if you have 1000 items, you must have tokenIDs consecutive from 1 to 1000 without missing any numbers.” Your image files can be numbered from 0; the tokenID column still starts at 1.

file_name must match the image

Each row’s file_name must be the exact name of one uploaded image, extension included, such as 1.png.

One file extension throughout

The README: “All files should have the same extension (e.g. all of them should be .png).” Pick PNG or JPEG for the whole collection.

Text traits only

OpenSea’s help page: “Currently, only string traits are supported if you’re uploading your CSV using OpenSea Studio. Numeric traits aren’t supported.” A string is plain text.

A real file

This is the start of opensea_Metadata.csv from the Puff Editions starter kit, exactly as the studio writes it. NFT #2 has no hat (its Headwear was the None choice), so its last cell is empty:

tokenID,name,description,file_name,external_url,attributes[Background],attributes[Body],attributes[Expression],attributes[Headwear]
1,Puff Editions #1,An original collection. Created with Puffles Studio.,1.png,,Mist,Frost,Happy,Bucket
2,Puff Editions #2,An original collection. Created with Puffles Studio.,2.png,,Mist,Frost,Wink,

Add a 1 of 1 and the file gains an attributes[1 of 1] column, filled only on that artwork’s row:

tokenID,name,description,file_name,external_url,attributes[Background],attributes[Body],attributes[Expression],attributes[Headwear],attributes[1 of 1]
98,Puff Editions #98,An original collection. Created with Puffles Studio.,98.png,,,,,,The Original

Getting the file without converting by hand

Puffles Studio writes opensea_Metadata.csv into every export, from the same plan as the JSON files, so the two always agree:

• The columns come in OpenSea’s order, then one attributes[…] column per trait type, in the order the collection first uses them.
• tokenID always runs 1 to N, even when your files start at 0, so file 0.png is tokenID 1.
• file_name is each image’s own name, like 1.png.
• A None trait leaves an empty cell.
• Values are quoted only when they contain a comma, a quote or a line break, and lines end the same way as in OpenSea’s example file.
• external_url is left empty: the studio has no setting for it yet.

When you set your images folder address later, the updated metadata ZIP includes a fresh opensea_Metadata.csv too (how to set the address).

Limits to know

OpenSea’s drop upload takes “up to 15,000 files, either JPG, PNG, SVG, or GIF” (OpenSea Help). Puffles Studio makes up to 20,000 NFTs, so a collection of more than 15,000 is bigger than one drop upload takes. A 10,000-piece collection fits.

On file size, OpenSea’s pages disagree: the example’s README gives a 50 MB limit per file, while the Creator FAQ says 5 GB for drops.

What Puffles does not do

Puffles Studio doesn’t create the drop, deploy a contract or upload anything to OpenSea. It writes the file; you upload it with your images in OpenSea Studio. For the JSON side of the same collection, see the OpenSea metadata format.