Skip to main content

Quick Start Guide

This guide will help you quickly set up Pulsarr to monitor your Plex watchlists and route content to Sonarr and Radarr.

Prerequisites​

Before you begin, ensure you have:

  • Docker (recommended for deployment)
  • Plex Pass subscription (optional - non-Plex Pass users supported with 5-minute staggered polling)
  • Sonarr/Radarr installation(s)
  • API keys for your Sonarr/Radarr instances

Installation Options​

Pulsarr can be installed using Docker (recommended), Unraid, or manual installation. Choose the method that works best for your environment.

  1. Create a .env file with your configuration:
TZ=America/Los_Angeles          # Set to your local timezone

Most settings have sensible defaults and can be configured via the web UI. See the Environment Variables Reference for all available options.

  1. Create a docker-compose.yml file and add the following:
services:
  pulsarr:
    image: lakker/pulsarr:latest
    container_name: pulsarr
    ports:
      - "3003:3003"
    volumes:
      - ./data:/app/data
      - .env:/app/.env
    restart: unless-stopped
    env_file:
      - .env
  1. Pull the image and run Docker Compose to start the service:
docker compose pull && docker compose up -d
  1. Navigate to the web UI (http://your-server:3003) to complete setup.
Synology NAS / Legacy Systems

If you're running on a Synology NAS or a system with Linux kernel < 4.11, use the Node.js-based image instead:

image: lakker/pulsarr:node

This alternative image uses Node.js runtime instead of Bun, avoiding kernel compatibility issues with the statx syscall. Both images are functionally identical.

Unraid Installation​

Pulsarr is available in the Unraid Community Applications (CA) store:

  1. Open the Unraid web UI
  2. Navigate to the "Apps" tab
  3. Search for "Pulsarr"
  4. Click "Install"
  5. Configure the container settings as needed
  6. Start the container

Alternatively, you can use the Docker installation method described above.

Manual Installation​

If you prefer to build and run Pulsarr manually:

Upgrading from Previous Versions

If you previously installed Pulsarr with Node.js, you must switch to Bun before updating to the latest version. Install Bun: curl -fsSL https://bun.sh/install | bash

Prerequisites​

  • Bun 1.3 or higher (bun.sh)
  • Git

Steps​

# Clone the repository
git clone https://github.com/jamcalli/pulsarr.git

cd pulsarr

# Install dependencies
bun install

# Build the application
bun run build

# Run database migrations
bun run migrate

# Start the server
bun run start:prod

The server will start on port 3003 by default. Navigate to http://localhost:3003 to complete setup.

TMDB API Key Required

When building from source, you must provide your own TMDB API Read Access Token for metadata features. See the TMDB API Configuration section for setup instructions.

For more detailed configuration options, see:

Native Installation​

Standalone builds with easy installers are available for Linux, macOS, and Windows. No Docker or runtime install required.

PlatformRecommended Method
LinuxOne-line installer: curl -fsSL https://raw.githubusercontent.com/jamcalli/Pulsarr/master/scripts/installers/linux/install.sh | sudo bash
WindowsDownload and run pulsarr-vX.X.X-windows-x64-setup.exe (or baseline variant for older CPUs without AVX2)
macOSDownload pulsarr-vX.X.X-macos-{arch}.dmg and drag Pulsarr to Applications

See the Native Installation Guide for detailed instructions, service management, and manual installation options.

Initial Setup​

  1. Access the web interface at http://your-server:3003

  2. Create an Admin account when prompted

  3. Enter your Plex Token to begin synchronization

  4. Configure your Sonarr and Radarr connections:

    • Add instance details (URL, API key)
    • Configure default quality profiles and root folders
    • Set up content routing rules (optional)

  5. Review friend statuses and set sync permissions on the Plex > Users page

    • Each user displays a badge indicating their relationship to your Plex account:
    BadgeMeaning
    OwnerYour Plex account
    FriendOn your friends list and shared to your server. Click to remove
    No FriendOn your server but not your friend. Click to send a friend request
    PendingFriend request sent. Click for cancel/resend options
    IncomingThey sent you a request. Accept it in Plex
    No ServerOn your friends list but not shared to your server
    • Watchlist syncing requires Plex friendship. Users showing "No Friend" can be sent a friend request directly from the badge
    • Ensure users have their Account Visibility set to 'Friends Only' or 'Friends of Friends'

  6. Head to the Dashboard page and click on the Start button next to the Main Workflow heading

    • Toggle 'Auto Start' to true for automatic operation

Next Steps​

After completing the quick start, you might want to: