Penpot File Format (.penpot) #

The .penpot file format is Penpot's native export format for design files. It's a ZIP archive containing JSON metadata and binary assets, designed to be open, inspectable, and efficient.

Overview #

The .penpot format (version 3) uses a ZIP container with JSON files for metadata and binary files for media assets. This approach provides several advantages:

• Open and inspectable: All metadata is human-readable JSON
• Efficient: ZIP compression reduces file size
• Interoperable: Standard formats enable third-party tooling
• Versioned: Clear versioning system for format and data evolution

Version History #

File Structure #

A .penpot file contains the following structure:

pencil.penpot (ZIP archive)
├── manifest.json                          # Root metadata
├── files/
│   ├── {file-id}.json                     # File metadata
│   └── {file-id}/
│       ├── pages/
│       │   ├── {page-id}.json             # Page metadata
│       │   └── {page-id}/
│       │       └── {shape-id}.json        # Individual shapes
│       ├── media/
│       │   └── {media-id}.json            # Media references
│       ├── colors/
│       │   └── {color-id}.json            # Library colors
│       ├── components/
│       │   └── {component-id}.json        # Library components
│       ├── typographies/
│       │   └── {typography-id}.json       # Library typographies
│       ├── tokens.json                    # Design tokens library
│       └── thumbnails/
│           └── {tag}/{page-id}/{frame-id}.json  # Thumbnail metadata
└── objects/
    ├── {uuid}.json                        # Storage object metadata
    └── {uuid}.{ext}                       # Binary media files (png, jpg, etc.)

Manifest Specification #

The manifest.json file is the root of the archive and contains metadata about the export.

Schema #

{
  "version": 1,
  "type": "penpot/export-files",
  "generatedBy": "penpot/2.12.0",
  "refer": "penpot",
  "files": [
    {
      "id": "uuid",
      "name": "File Name",
      "features": ["feature1", "feature2"]
    }
  ],
  "relations": []
}

Fields #

Example #

{
  "type": "penpot/export-files",
  "version": 1,
  "generatedBy": "penpot/2.12.0-RC1-99-g40c27591f",
  "refer": "penpot",
  "files": [
    {
      "id": "73b59a94-3ea3-8189-8007-3d36adc8c3e3",
      "name": "Pencil | Penpot Design System",
      "features": [
        "fdata/path-data",
        "design-tokens/v1",
        "variants/v1",
        "layout/grid",
        "components/v2",
        "fdata/shape-data-type"
      ]
    }
  ],
  "relations": []
}

File Metadata #

Each file has a JSON file at files/{file-id}.json containing the file's metadata.

Schema #

Features #

The features field is a set of strings indicating which features are enabled in the file. Common features include:

Migrations #

The migrations field lists all data migrations applied to the file. This ensures backward compatibility when the data model evolves.

Example #

{
  "id": "73b59a94-3ea3-8189-8007-3d36adc8c3e3",
  "name": "Pencil | Penpot Design System",
  "revn": 28425,
  "vern": 0,
  "createdAt": "2025-12-10T10:24:18.686066Z",
  "modifiedAt": "2025-12-10T12:13:49.799076Z",
  "teamId": "b62e1aa4-d9a7-8147-8005-2813bed4056e",
  "projectId": "f23add0e-6b77-8069-8005-41b48b93a5da",
  "isShared": true,
  "features": [
    "fdata/path-data",
    "design-tokens/v1",
    "variants/v1",
    "layout/grid",
    "components/v2",
    "fdata/shape-data-type"
  ],
  "migrations": [
    "legacy-2",
    "legacy-3",
    "0001-remove-tokens-from-groups",
    "0002-normalize-bool-content-v2"
  ],
  "options": {
    "componentsV2": true
  }
}

Pages and Shapes #

Page Structure #

Each page is stored at files/{file-id}/pages/{page-id}.json.

Shapes #

Individual shapes are stored at files/{file-id}/pages/{page-id}/{shape-id}.json.

Shape Types #

Penpot supports 9 shape types:

Base Shape Attributes #

All shapes share these base attributes:

Geometry Attributes #

Shapes with geometry (frame, rect, circle, image, svg-raw, text):

Generic Attributes #

Optional attributes available on all shapes:

Type-Specific Attributes #

Frame

• shapes: array of child shape UUIDs
• showContent: boolean
• hideInViewer: boolean

Group

• shapes: array of child shape UUIDs

Bool

• shapes: array of child shape UUIDs
• boolType: string (union, difference, exclude, intersection)
• content: path data

Path

• content: path data (SVG path commands)

Text

• content: text content with formatting
• positionData: glyph position data

Image

• metadata: object with width, height, mtype, id

Example Shape #

{
  "id": "260aea33-4e55-808c-8007-3d4f2efe4230",
  "name": "Rectangle",
  "type": "rect",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 150,
  "selrect": {
    "x": 100,
    "y": 100,
    "width": 200,
    "height": 150
  },
  "points": [
    {"x": 100, "y": 100},
    {"x": 300, "y": 100},
    {"x": 300, "y": 250},
    {"x": 100, "y": 250}
  ],
  "transform": [1, 0, 0, 1, 0, 0],
  "transformInverse": [1, 0, 0, 1, 0, 0],
  "parentId": "00000000-0000-0000-0000-000000000000",
  "frameId": "00000000-0000-0000-0000-000000000001",
  "fills": [
    {
      "color": "#FF5733",
      "opacity": 1
    }
  ],
  "r1": 8,
  "r2": 8,
  "r3": 8,
  "r4": 8
}

Library Assets #

Colors #

Stored at files/{file-id}/colors/{color-id}.json.

Plain Color Example #

{
  "id": "abc123...",
  "name": "Primary Blue",
  "path": "Brand/Primary",
  "color": "#0066CC",
  "opacity": 1
}

Gradient Color Example #

{
  "id": "def456...",
  "name": "Sunset Gradient",
  "gradient": {
    "type": "linear",
    "startX": 0,
    "startY": 0,
    "endX": 1,
    "endY": 1,
    "stops": [
      {"color": "#FF6B6B", "offset": 0, "opacity": 1},
      {"color": "#4ECDC4", "offset": 1, "opacity": 1}
    ]
  }
}

Components #

Stored at files/{file-id}/components/{component-id}.json.

Typographies #

Stored at files/{file-id}/typographies/{typography-id}.json.

Design Tokens #

Stored at files/{file-id}/tokens.json.

The tokens library contains:

• Sets: Collections of tokens organized hierarchically
• Themes: Named combinations of token sets
• Active Themes: Currently applied themes

Token Structure #

{
  "sets": {
    "core": {
      "id": "uuid",
      "name": "Core",
      "tokens": {
        "color": {
          "primary": {
            "id": "uuid",
            "name": "primary",
            "type": "color",
            "value": "#0066CC"
          }
        }
      }
    }
  },
  "themes": {
    "light": {
      "id": "uuid",
      "name": "Light",
      "sets": ["core"]
    }
  },
  "activeThemes": ["light"]
}

Media and Storage Objects #

Storage Objects #

Binary assets (images, fonts, etc.) are stored in the objects/ directory.

Each storage object has:

• objects/{uuid}.json - Metadata
• objects/{uuid}.{ext} - Binary content (png, jpg, svg, etc.)

Metadata Schema #

Example #

{
  "id": "0039433d-adc8-430d-b2c3-d884dea6e050",
  "size": 575,
  "contentType": "image/png",
  "bucket": "file-media-object",
  "hash": "blake2b:77d447db38eb5daf31acb7344a504cacc6b79aa11855a00501d9475c595053d0"
}

Media References #

File media references are stored at files/{file-id}/media/{media-id}.json.

Thumbnails #

Page thumbnails are stored at files/{file-id}/thumbnails/{tag}/{page-id}/{frame-id}.json.

Plugin Data #

Plugins can store custom data on files, pages, shapes, components, colors, and typographies using the pluginData field.

Structure #

{
  "pluginData": {
    "plugin-id": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

The plugin ID is a keyword (e.g., "my-plugin"), and the values are string key-value pairs.

Inspecting a .penpot File #

List Contents #

unzip -l design.penpot

Extract and View #

# Extract to temporary directory
unzip design.penpot -d /tmp/penpot-inspect

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

# List all files
find /tmp/penpot-inspect -name "*.json" | head -20

# View a specific shape
cat /tmp/penpot-inspect/files/*/pages/*/*.json | jq .

Browser-Based Inspector #

For an interactive way to explore a .penpot file, try the Penpot file inspector. It runs entirely in your browser, displays a collapsible file tree, syntax-highlighted JSON, image previews, and clickable cross-references between shapes, components, colors, and media.

Quick Inspection Script #

#!/bin/bash
# Inspect .penpot file structure

FILE=$1
TMPDIR=$(mktemp -d)

unzip -q "$FILE" -d "$TMPDIR"

echo "=== Manifest ==="
cat "$TMPDIR/manifest.json" | jq '{type, version, files: [.files[] | {id, name}]}'

echo -e "\n=== Files ==="
for f in "$TMPDIR"/files/*.json; do
  echo "- $(jq -r '.name' "$f")"
done

echo -e "\n=== Pages ==="
for f in "$TMPDIR"/files/*/pages/*.json; do
  echo "- $(jq -r '.name' "$f")"
done

echo -e "\n=== Storage Objects ==="
ls -lh "$TMPDIR"/objects/*.{png,jpg,svg} 2>/dev/null | wc -l
echo "media files"

rm -rf "$TMPDIR"

Cross-References #

• Penpot file inspector - Browser-based interactive inspector
• Data Model - Conceptual data model
• Data Guide - Working with data structures
• Export/Import Files - User guide for exporting and importing

Source Code References #

The authoritative schema definitions are in the Penpot source code:

• Manifest: backend/src/app/binfile/v3.clj (schema:manifest)
• File: common/src/app/common/types/file.cljc (schema:file)
• Page: common/src/app/common/types/page.cljc (schema:page)
• Shape: common/src/app/common/types/shape.cljc (schema:shape)
• Component: common/src/app/common/types/component.cljc (schema:component)
• Color: common/src/app/common/types/color.cljc (schema:library-color)
• Typography: common/src/app/common/types/typography.cljc (schema:typography)
• Tokens: common/src/app/common/types/tokens_lib.cljc (schema:tokens-lib)
• Plugin Data: common/src/app/common/types/plugins.cljc (schema:plugin-data)
• Features: common/src/app/common/features.cljc (schema:features)