Overview
Penpot is an open-source design and prototyping platform that can be self-hosted or used via its cloud service. It is built on web-open standards, using SVG as its native format, which means designs are inherently compatible with web technologies. Penpot supports real-time collaboration, allowing multiple designers and developers to work on the same project simultaneously.
Penpot serves as an alternative to proprietary tools like Figma and Sketch. It provides vector editing, component libraries, interactive prototyping, design tokens, CSS-ready inspect mode, and a plugin system. Because it outputs standard SVG and CSS, the handoff between designers and developers is more seamless than with proprietary formats.
Installation
Cloud (Hosted)
Access the free hosted version at design.penpot.app. Create an account and start designing immediately.
Self-Hosted (Docker)
# Clone the Penpot repository
git clone https://github.com/penpot/penpot.git
cd penpot/docker/images
# Copy the example configuration
cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
# Edit the environment file
nano .env
# Set PENPOT_PUBLIC_URI=https://penpot.yourdomain.com
# Start the services
docker compose -p penpot -f docker-compose.yml up -d
# Access at http://localhost:9001
Environment Configuration
# .env file for self-hosted
PENPOT_PUBLIC_URI=https://penpot.yourdomain.com
PENPOT_FLAGS=enable-registration enable-login-with-password enable-smtp
PENPOT_SECRET_KEY=your-random-secret-key
# Database
PENPOT_DATABASE_URI=postgresql://penpot:password@postgres:5432/penpot
# Redis
PENPOT_REDIS_URI=redis://redis:6379/0
# SMTP
PENPOT_SMTP_DEFAULT_FROM=noreply@yourdomain.com
PENPOT_SMTP_DEFAULT_REPLY_TO=support@yourdomain.com
PENPOT_SMTP_HOST=smtp.yourdomain.com
PENPOT_SMTP_PORT=587
PENPOT_SMTP_USERNAME=smtp-user
PENPOT_SMTP_PASSWORD=smtp-password
PENPOT_SMTP_TLS=true
# Storage
PENPOT_ASSETS_STORAGE_BACKEND=assets-fs
PENPOT_STORAGE_ASSETS_FS_DIRECTORY=/opt/data/assets
# Telemetry (optional, disable for privacy)
PENPOT_TELEMETRY_ENABLED=false
Core Features
Keyboard Shortcuts
| Shortcut | Action |
|---|
V | Select tool |
R | Rectangle tool |
E | Ellipse tool |
P | Pen tool (paths) |
T | Text tool |
B | Board/frame tool |
I | Eyedropper / color picker |
K | Comment tool |
Ctrl+G | Group selection |
Ctrl+Shift+G | Ungroup |
Ctrl+D | Duplicate selection |
Ctrl+C / Ctrl+V | Copy / Paste |
Ctrl+Z / Ctrl+Shift+Z | Undo / Redo |
Ctrl+A | Select all |
Ctrl+0 | Zoom to fit |
Ctrl++ / Ctrl+- | Zoom in / out |
Space + drag | Pan canvas |
Alt + drag | Duplicate while moving |
Shift + drag | Constrain proportions |
| Tool | Description |
|---|
| Select (V) | Select and transform objects |
| Board (B) | Create artboards / frames |
| Rectangle (R) | Draw rectangles and squares |
| Ellipse (E) | Draw circles and ellipses |
| Pen (P) | Draw custom vector paths |
| Text (T) | Add and edit text |
| Image | Import and place images |
| Comments (K) | Add review comments |
| Measure | Measure distances between objects |
Layer Operations
| Action | Description |
|---|
Ctrl+] | Bring forward |
Ctrl+[ | Send backward |
Ctrl+Shift+] | Bring to front |
Ctrl+Shift+[ | Send to back |
Ctrl+G | Group layers |
Ctrl+Shift+G | Ungroup layers |
Ctrl+Enter | Create component |
| Toggle eye icon | Show/hide layer |
| Toggle lock icon | Lock/unlock layer |
Components and Design Systems
Creating Components
1. Select the element(s) you want to make into a component
2. Right-click → "Create Component" (or Ctrl+Enter)
3. The component appears in the Assets panel
4. Drag instances from Assets onto the canvas
5. Changes to the main component propagate to all instances
Component Features
| Feature | Description |
|---|
| Main Component | The source of truth; edits propagate to instances |
| Instance | A copy linked to the main component |
| Override | Instance-level changes that do not affect the main |
| Detach | Break the link between instance and main |
| Swap | Replace one component instance with another |
| Nested | Components inside other components |
Design Tokens
# Penpot supports design tokens for consistent design systems:
- Colors: Define palette colors in the Assets panel
- Typography: Create reusable text styles
- Shadows: Save shadow presets
- Grids: Configure reusable grid layouts
- Export presets: Define export settings per component
Prototyping
Interaction Types
| Trigger | Description |
|---|
| On Click | Activates when element is clicked |
| Mouse Enter | Activates on hover |
| Mouse Leave | Activates when cursor leaves |
| After Delay | Activates after a time delay |
Actions
| Action | Description |
|---|
| Navigate To | Go to another board/frame |
| Open Overlay | Show a frame as an overlay |
| Close Overlay | Dismiss the current overlay |
| Previous Board | Navigate back |
| Open URL | Open an external link |
Animation Options
| Type | Description |
|---|
| Dissolve | Fade transition between boards |
| Slide | Slide in from a direction |
| Push | Push the current board away |
| Instant | No animation |
# Creating a prototype:
1. Switch to Prototype mode (top-right toggle)
2. Select an element
3. Drag the connection point to a target board
4. Configure the interaction trigger and animation
5. Click Play (▶) to preview the prototype
Advanced Usage
Inspect Mode
# For developers handoff:
1. Switch to Inspect mode (top-right toggle)
2. Click any element to see:
- CSS properties (position, size, colors, fonts)
- SVG code
- Spacing and dimensions
- Design token references
3. Click "Copy" buttons to copy CSS or SVG snippets
Plugins
// Penpot Plugin API (JavaScript)
// Plugins run in the browser context
penpot.ui.open("My Plugin", `
<div>
<h1>Hello Plugin</h1>
<button id="btn">Get Selection</button>
</div>
`, { width: 300, height: 200 })
penpot.ui.onMessage((message) => {
if (message.type === "get-selection") {
const selection = penpot.selection
penpot.ui.sendMessage({ type: "selection", data: selection })
}
})
Flex Layout
# Penpot supports CSS Flexbox-based layouts:
1. Select a frame/board
2. Open the Design panel → Layout section
3. Toggle "Flex Layout"
4. Configure:
- Direction: Row / Column
- Alignment: Start, Center, End, Stretch
- Gap: Space between items
- Padding: Internal spacing
- Wrap: Allow items to wrap to next line
Exporting
# Export options:
- PNG: Raster export at configurable resolution (1x, 2x, 4x)
- SVG: Native vector format
- JPEG: Compressed raster
- PDF: Print-ready output
# To export:
1. Select element(s)
2. Design panel → Export section
3. Add export preset (format, scale)
4. Click export button
Troubleshooting
| Issue | Solution |
|---|
| Self-hosted not starting | Check Docker logs: docker compose -p penpot logs; verify PostgreSQL is running |
| Slow canvas with many objects | Group objects; use components to reduce unique elements |
| Fonts not loading | Upload custom fonts via Assets panel; ensure font files are accessible |
| Prototype links broken | Verify target boards exist and have not been renamed or deleted |
| Export quality low | Increase export scale (2x or 4x) for raster formats |
| Collaboration not syncing | Check WebSocket connection; ensure Redis is running for self-hosted |
| Login not working (self-hosted) | Verify PENPOT_FLAGS includes enable-login-with-password |
| SMTP email not sending | Check SMTP credentials and TLS settings in .env |
| Large file slow to open | Break project into multiple pages; optimize imported images |
