SCRATCH File Documentation

Summary

A Scratch project file is a program built in MIT’s free, block-based coding environment for children — the scripts, sprites, costumes and sounds of a game or animation. The real extensions are .sb3 (Scratch 3.0), .sb2 (2.0) and .sb (1.x), not a literal .scratch. Open one for free in the online editor at scratch.mit.edu (File › Load from your computer) or the offline Scratch Desktop app. A current .sb3 is really a ZIP archive of a project.json plus media, so you can rename it to .zip to look inside.

Technical details

FeatureValue
Full nameScratch project file
Real extensions.sb3 (3.0), .sb2 (2.0), .sb (1.x)
MIME typeapplication/x.scratch.sb3
Format typeVisual-programming project
DeveloperMIT Media Lab (Lifelong Kindergarten) / Scratch Foundation
IntroducedScratch 1.0 (2007); Scratch 3.0 from 2019
Container (2.0 / 3.0)ZIP archive
Container (1.x)Binary Squeak/Smalltalk object store
Magic number (sb2/sb3)50 4B 03 04 (“PK”, ZIP local file header)
Project descriptionproject.json (sprites, blocks, variables)
AssetsCostumes (PNG/SVG), sounds (WAV/MP3)
Open standardPartial (format is documented; runtime is MIT’s)
SpecificationScratch Wiki — Scratch File Format
Sprite export.sprite3 / .sprite2
Opens inScratch online editor, Scratch Desktop, TurboWarp
Related extensions.sb3, .sb2, .sb, .zip, .json
File signature (magic bytes)
50 4B 03 04

Offset 0, ASCII PK\x03\x04. A modern Scratch project (.sb3 or .sb2) is a ZIP archive, so it carries the standard ZIP local-file-header signature, the same first bytes as a .zip. Inside, a project.json holds the whole program — every sprite, block, variable and the stage — alongside the referenced costume images and sound files. Rename an .sb3 to .zip (or open it with 7-Zip) to inspect it. The original Scratch 1.x .sb is not a ZIP: it is a binary Squeak object store with its own header.

What is a Scratch project file?

A Scratch project is a program made in Scratch, the free block-based coding environment created by MIT’s Lifelong Kindergarten group (now stewarded by the Scratch Foundation) to teach programming to children. Instead of typing code, you snap together colour-coded blocks to control sprites and build games, animations and interactive stories. The project file is the saved program: its scripts, its sprites and their costumes, the stage, and any sounds. Scratch 1.0 launched in 2007; the current Scratch 3.0 has been the standard since 2019.

One correction up front, because it is the single most common point of confusion. The standard extension is not .scratch. Real Scratch projects use .sb3 (Scratch 3.0), .sb2 (Scratch 2.0) or .sb (the original 1.x). A file that literally ends in .scratch is almost always an unrelated temporary or working file from some other program, not an MIT Scratch project. The rest of this page describes the genuine Scratch project formats.

The .sb3 (and .sb2) project is a ZIP archive

The modern formats are well understood, because they are ordinary ZIP archives. An .sb3 or .sb2 file begins with the ZIP local-file-header signature 50 4B 03 04 (“PK”), exactly like a ZIP file, and you can rename one to .zip and open it in any archive tool to see its contents. Inside you find a single JSON file that describes the whole program plus the media assets it uses:

my_project.sb3   (ZIP archive)
 ├─ project.json          the entire program: stage, sprites, blocks, variables
 ├─ 83a9....svg           a costume (vector sprite image)
 ├─ b7e2....png           a costume (bitmap)
 ├─ c1f0....wav           a sound
 └─ ...                   more costume and sound assets

The asset files are named by a hash of their contents (an MD5 digest with the original file extension appended), and project.json refers to each one by that hashed name. This content-addressed scheme means two identical costumes are stored once, and it lets the editor verify assets. The costumes are ordinary PNG or SVG images and the sounds are WAV or MP3, so once extracted they open in any normal media tool.

Inside project.json

The JSON is the actual program. At the top level it lists targets — one for the stage and one for each sprite — plus metadata such as the editor version. Each target carries its variables and lists, its costumes and sounds (referencing the hashed asset files), and its blocks: a dictionary of every script block keyed by a unique id, each recording its opcode (for example motion_movesteps), its input values, and the id of the next block in the stack. The visual scripts you drag around in the editor are stored as this graph of linked block objects. Reading project.json is how third-party tools reconstruct, run or analyse a project without the Scratch editor.

The original .sb format is different

The first-generation .sb (Scratch 1.x) is not a ZIP. It is a binary Squeak/Smalltalk object store — a serialised graph of Smalltalk objects with its own header — because early Scratch was written in Squeak. That is why you cannot rename an old .sb to .zip: only the 2.0 and 3.0 generations use the ZIP-plus-JSON design. Scratch 3.0 can still open an old .sb or .sb2 and convert it forward when you save.

Opening and running a project

No special viewer is needed. The Scratch online editor at scratch.mit.edu opens a saved project with File › Load from your computer and runs it in the browser, no account required. The offline Scratch Desktop app does the same without internet. TurboWarp, a Scratch-compatible editor and compiler, opens the same .sb3 files, runs them faster, and can package a project into a standalone Windows .exe or a self-contained HTML page that plays in any browser. To inspect a project’s parts rather than run it, open the .sb3 as a ZIP with 7-Zip.

Because the current format is just ZIP + JSON, converting is often trivial: renaming .sb3 to .zip exposes the assets and project.json directly, no conversion tool involved. Going the other direction, Scratch 3.0 saves older .sb2/.sb projects as .sb3; the reverse (.sb3 back to .sb2) is not supported, because 3.0 added blocks that 2.0 has no way to represent.

References