The .penpot file format

Penpot's native file format is designed to be open, inspectable, and efficient. Unlike proprietary formats, you can always look inside a .penpot file to understand your design data.

What is a .penpot file?

A .penpot file is a ZIP archive containing:

  • JSON metadata — human-readable descriptions of your pages, shapes, colors, components, and more
  • Binary media files — images, fonts, and other assets used in your design

This means your design data is never locked in a proprietary format. You can always unzip a .penpot file and read the JSON to understand what's inside.

What's inside a .penpot file?

When you unzip a .penpot file, you'll find this structure:

your-design.penpot (ZIP archive)
├── manifest.json          ← Table of contents
├── files/                 ← Your design data
│   ├── file-metadata.json
│   └── file-data/
│       ├── pages/         ← Each page of your design
│       ├── colors/        ← Library colors
│       ├── components/    ← Library components
│       ├── typographies/  ← Library typographies
│       ├── tokens.json    ← Design tokens
│       └── media/         ← Media references
└── objects/               ← Images and binary assets

manifest.json

The manifest is the table of contents. It tells you:

  • Which version of the format is used
  • Which Penpot version created the file
  • What files are included
  • What features are enabled

File data

The files/ directory contains all your design data organized by type:

  • Pages — Each page is split into individual shape files for efficiency
  • Colors — Your color library with hex values, gradients, or image fills
  • Components — Reusable component definitions
  • Typographies — Text style definitions
  • Tokens — Design tokens organized in sets and themes
  • Media — References to images and other assets

Objects

The objects/ directory contains the actual binary files (PNG, JPG, SVG) referenced by your design. Each object has a JSON metadata file alongside the binary file.

How to inspect a .penpot file

Since .penpot files are just ZIP archives, you can inspect them with standard tools.

On macOS or Linux

1. List the contents without extracting:

unzip -l your-design.penpot

2. Extract to a temporary folder:

unzip your-design.penpot -d /tmp/penpot-inspect

3. View the manifest:

cat /tmp/penpot-inspect/manifest.json | jq .

4. Browse the structure:

tree /tmp/penpot-inspect

5. View a specific shape:

cat /tmp/penpot-inspect/files/*/pages/*/*.json | jq .

On Windows

1. Right-click the .penpot file and select "Extract All..." or use 7-Zip.

2. Browse the extracted folder to see the structure.

3. Open any JSON file with a text editor or use a JSON viewer tool.

Using AI tools

You can use the Penpot MCP server to inspect .penpot files with AI assistance. The MCP server can read and analyze your design files, making it easy to understand complex designs or automate tasks.

Format versions

The .penpot format has evolved over time:

Version Description Status
v3 ZIP + JSON format (current) ✅ Current
v1 Custom binary format ⚠️ Deprecated

All current Penpot versions export in v3 format. Old v1 files can still be imported, but new exports will use v3.

Version numbers inside the file

Inside a .penpot file, you'll see two different version numbers:

  • Format version (in manifest.json) — Tracks changes to the ZIP structure itself. Currently 1.
  • Data version (in each file's JSON) — Tracks changes to the data model. This number increases as Penpot evolves.

Feature flags

Files also include a list of feature flags that indicate which capabilities are used. For example:

  • design-tokens/v1 — Uses design tokens
  • components/v2 — Uses the v2 component system
  • variants/v1 — Uses component variants
  • layout/grid — Uses grid layouts

These flags help Penpot know what features need to be supported when importing the file.

For developers

If you're building tools or integrations that work with .penpot files, the complete technical specification provides detailed schema definitions for every JSON file in the archive.

Key resources: