Installation

Overview

screenpipe is available as:

Desktop app (recommended) - One-time purchase with auto-updates
Build from source - For developers and contributors

The CLI package (npx screenpipe) has been discontinued. Use the desktop app instead.

System Requirements

Before installing, make sure your system meets these requirements:

Platform	Minimum Requirements
macOS	macOS 11+ (Big Sur or later), 8 GB RAM, ~10 GB disk space
Windows	Windows 10/11, 8 GB RAM, ~10 GB disk space
Linux	Ubuntu 20.04+ or equivalent, 8 GB RAM, ~10 GB disk space

screenpipe uses ~5-10 GB disk space per month. Event-driven capture only stores frames when something changes, reducing storage by ~90% compared to continuous recording.

Desktop App Installation

macOS
Windows
Linux

Download

Visit screenpi.pe/onboarding and download the .dmg installer.Both Apple Silicon and Intel Macs are fully supported.

Install

Open the downloaded .dmg file
Drag screenpipe to your Applications folder
Eject the disk image

Launch

Open screenpipe from Applications
If you see “screenpipe cannot be opened because it is from an unidentified developer”:
- Go to System Settings > Privacy & Security
- Scroll down to find “screenpipe was blocked from use”
- Click “Open Anyway”
- Confirm by clicking “Open”

Grant Permissions

screenpipe requires the following permissions:Screen Recording (Required)

screenpipe will prompt for Screen Recording access
Click “Open System Settings”
Enable the toggle next to screenpipe
Restart screenpipe

Accessibility (Required)

Go to System Settings > Privacy & Security > Accessibility
Click the + button and select screenpipe
Enable the toggle next to screenpipe

Microphone (Optional)

Only needed if you want audio transcription
screenpipe will prompt when you enable audio capture

These permissions are required for screenpipe to function. Without Screen Recording and Accessibility access, the app cannot capture your screen or extract text.

Verify Installation

After granting permissions:

Click the screenpipe icon in the menu bar
Select “Start Recording”
Use your computer for a minute
Open the timeline view to see your captured activity

macOS-Specific Notes

Dev builds: If you’re building from source, dev builds are signed with a developer certificate for consistent permissions. Other devs without the cert will see permission issues—the onboarding has a “continue anyway” button after 5s.
Data location: All data is stored in ~/.screenpipe/
Uninstall: Drag screenpipe from Applications to Trash, then delete ~/.screenpipe/ to remove all data

Download

Visit screenpi.pe/onboarding and download the .exe installer for Windows 10 or 11.

Install

Run the downloaded .exe file
If Windows SmartScreen appears, click “More info” then “Run anyway”
Follow the installation wizard
Choose installation location (default: C:\Program Files\screenpipe)
Click “Install”

Firewall Permission

Windows will prompt you to allow screenpipe through the firewall:

Check both “Private networks” and “Public networks”
Click “Allow access”

This is required for the local API server (runs on localhost:3030).

Launch

Start screenpipe from the Start menu or desktop shortcut
The app will appear in your system tray (taskbar notification area)

Verify Installation

Right-click the screenpipe icon in the system tray
Select “Start Recording”
Use your computer for a minute
Open the app to see your timeline

Windows-Specific Notes

No additional permissions required: Unlike macOS, Windows doesn’t require explicit screen recording permissions
Data location: All data is stored in %APPDATA%\screenpipe\
Uninstall: Use Windows Settings > Apps > screenpipe > Uninstall, then delete %APPDATA%\screenpipe\ to remove all data

Build from Source

For developers and contributors who want to build screenpipe from source:

macOS
Windows
Linux

Install dependencies

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install system dependencies via Homebrew
brew install pkg-config ffmpeg jq cmake wget git-lfs

Install Xcode (required):

Download from the App Store
Accept the license and run first launch:

sudo xcodebuild -license
xcodebuild -runFirstLaunch

Xcode command line tools alone are insufficient. You need the full Xcode app.

Install Bun

curl -fsSL https://bun.sh/install | bash

screenpipe uses Bun (not npm or pnpm) for JavaScript/TypeScript development.

Clone and build

# Clone the repository
git clone https://github.com/screenpipe/screenpipe
cd screenpipe

# Build the core engine
cargo build --release --features metal,apple-intelligence

# Run the engine
./target/release/screenpipe

The metal feature enables GPU acceleration on Apple Silicon, and apple-intelligence enables on-device AI processing.

Build the desktop app (optional)

cd apps/screenpipe-app-tauri
bun install
bun tauri build --features metal,apple-intelligence

The built app will be in apps/screenpipe-app-tauri/src-tauri/target/release/bundle/.

Install winget

If you don’t have winget, install it from winget.pro/winget-install-powershell.

Install dependencies

Open PowerShell as Administrator and run:

# Install build tools
winget install -e --id Microsoft.VisualStudio.2022.BuildTools
winget install -e --id Rustlang.Rustup
winget install -e --id LLVM.LLVM
winget install -e --id Kitware.CMake
winget install -e --id GnuWin32.UnZip
winget install -e --id Git.Git
winget install -e --id JernejSimoncic.Wget
winget install -e --id 7zip.7zip

# Install Bun
irm https://bun.sh/install.ps1 | iex

Set environment variables

[System.Environment]::SetEnvironmentVariable('LIBCLANG_PATH', 'C:\Program Files\LLVM\bin', 'User')
[System.Environment]::SetEnvironmentVariable('PATH', "$([System.Environment]::GetEnvironmentVariable('PATH', 'User'));C:\Program Files (x86)\GnuWin32\bin", 'User')

Close and reopen PowerShell after setting environment variables.

Clone the repository

git clone https://github.com/screenpipe/screenpipe.git
cd screenpipe

Install vcredist

$path = "C:\Windows\System32\vcruntime140.dll"

if (-Not (Test-Path $path)) {
    Start-Process powershell -Verb RunAs -ArgumentList '-NoProfile -ExecutionPolicy Bypass -Command "& {
        Set-ExecutionPolicy Bypass -Scope Process -Force
        [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
        $url = ''https://vcredist.com/install.ps1''
        $scriptPath = ''$env:TEMP\install_vcredist.ps1''
        Invoke-WebRequest -Uri $url -OutFile $scriptPath
        & $scriptPath
    }"' -Wait
}

# Copy to build directory
$vcredist_dir = (pwd).Path + "\apps\screenpipe-app-tauri\src-tauri\vcredist"
New-Item -ItemType Directory -Force -Path $vcredist_dir | Out-Null
Copy-Item $path -Destination $vcredist_dir -Force

Build

# Build the engine
cargo build --release

# Build the desktop app
cd apps/screenpipe-app-tauri
bun install
bun tauri build

Install dependencies

# Install system dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y \
  g++ \
  ffmpeg \
  tesseract-ocr \
  cmake \
  libavformat-dev \
  libavfilter-dev \
  libavdevice-dev \
  libssl-dev \
  libtesseract-dev \
  libxdo-dev \
  libsdl2-dev \
  libclang-dev \
  libxtst-dev \
  libpipewire-0.3-dev

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.bashrc

Install Bun

curl -fsSL https://bun.sh/install | bash

Optional: Install Vulkan (for AMD GPU acceleration)

sudo apt-get install -y libvulkan-dev glslc

Clone and build

git clone https://github.com/screenpipe/screenpipe
cd screenpipe

# Build the engine
cargo build --release

# Run the engine
./target/release/screenpipe

Build the desktop app (optional)

# Install additional dependencies for Tauri
sudo apt-get install -y \
  libayatana-appindicator3-1 \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  libwebkit2gtk-4.1-dev

# Build the app
cd apps/screenpipe-app-tauri
bun install
bun tauri build

Running from Source

After building from source:

# Run with default settings
./target/release/screenpipe

# Run on a different port
./target/release/screenpipe --port 3035

# Use a different data directory (useful for testing)
./target/release/screenpipe --data-dir /tmp/sp

When running dev builds alongside production, use --port and --data-dir flags to avoid conflicts.

Data Storage

screenpipe stores all data locally in these locations:

Platform	Location
macOS	`~/.screenpipe/`
Windows	`%APPDATA%\screenpipe\`
Linux	`~/.screenpipe/`

The data directory contains:

~/.screenpipe/
├── db.sqlite              # SQLite database (metadata, text, audio)
├── data/                  # Screenshot snapshots
│   ├── 2026-03-08/       # Organized by date
│   │   ├── 1709884800000_m0.jpg
│   │   ├── 1709884803000_m0.jpg
│   │   └── ...
│   └── 2026-03-09/
└── pipes/                 # Pipe configurations (AI agents)

To back up your data, simply copy the entire .screenpipe directory. To reset, delete it and restart the app.

Verification

After installation, verify screenpipe is working:

Check the health endpoint

Open your browser and visit:

http://localhost:3030/health

You should see:

{
  "status": "ok",
  "version": "1.x.x"
}

Start recording and test search

Start recording in the app
Use your computer for a few minutes
Try a search query:

curl "http://localhost:3030/search?q=test&limit=5"

Check resource usage

CPU: Should be 5-10% during active use
RAM: Should be 0.5-3 GB
Disk: Check ~/.screenpipe/data/ for snapshots

Troubleshooting

macOS: Permission issues

If recording isn’t working:

Go to System Settings > Privacy & Security > Screen Recording
Remove screenpipe from the list
Quit and restart screenpipe
Grant permissions again when prompted

Dev builds require the developer certificate for consistent permissions. If you’re building from source without the cert, you may need to grant permissions after each rebuild.

Windows: Firewall blocking

If the API isn’t accessible:

Open Windows Security > Firewall & network protection
Click “Allow an app through firewall”
Find screenpipe and ensure both Private and Public are checked
Restart screenpipe

Linux: Missing dependencies

If you get build errors:

# Check for missing packages
pkg-config --list-all | grep -E 'tesseract|pipewire|sdl2'

# Install any missing dependencies
sudo apt-get install -y libtesseract-dev libpipewire-0.3-dev libsdl2-dev

Build errors: Database migrations

If you encounter migration errors when building from source:

# Remove problematic migration
sqlite3 ~/.screenpipe/db.sqlite "DELETE FROM _sqlx_migrations WHERE version = XXXXXXXXXX;"

# Or reset completely (backup first!)
mv ~/.screenpipe/db.sqlite ~/.screenpipe/db.sqlite.backup

High disk usage

If storage is growing too fast:

Lower capture sensitivity in settings (Low uses ~5 GB/month)
Reduce the number of monitors being captured
Set up automatic cleanup (Settings > Storage > Auto-delete after X days)

Uninstalling

macOS
Windows
Linux

Quit screenpipe (right-click menu bar icon > Quit)
Drag screenpipe from Applications to Trash
Delete data directory:

rm -rf ~/.screenpipe

Revoke permissions (optional):
- System Settings > Privacy & Security > Screen Recording > Remove screenpipe
- System Settings > Privacy & Security > Accessibility > Remove screenpipe

Close screenpipe (right-click system tray icon > Exit)
Windows Settings > Apps > screenpipe > Uninstall
Delete data directory:

Remove-Item -Recurse -Force "$env:APPDATA\screenpipe"

# If installed from source
rm -rf ~/screenpipe
rm -rf ~/.screenpipe

Next Steps

Quickstart

Learn how to use screenpipe in 5 minutes

Architecture

Understand how screenpipe works

API Reference

Explore the REST API

Join Discord

Get help from the community

Get Started

Core Features

Pipes & Automation

Integrations

Advanced

Developers

Comparison

Resources

Overview

System Requirements

Desktop App Installation

macOS-Specific Notes

Windows-Specific Notes

Build from Source

Running from Source

Data Storage

Verification

Troubleshooting

Uninstalling

Next Steps

Quickstart

Architecture

API Reference

Join Discord

Build docs developers (and LLMs) love

Get Started

Core Features

Pipes & Automation

Integrations

Advanced

Developers

Comparison

Resources

​Overview

​System Requirements

​Desktop App Installation

​macOS-Specific Notes

​Windows-Specific Notes

​Build from Source

​Running from Source

​Data Storage

​Verification

​Troubleshooting

​Uninstalling

​Next Steps

Quickstart

Architecture

API Reference

Join Discord

Build docs developers (and LLMs) love

Overview

System Requirements

Desktop App Installation

macOS-Specific Notes

Windows-Specific Notes

Build from Source

Running from Source

Data Storage

Verification

Troubleshooting

Uninstalling

Next Steps