Skip to main content

Installation Guide

This guide will walk you through the installation process for Cleanuparr. Cleanuparr can be installed in several ways depending on your preference and system configuration.

Note

For most users, we recommend the Docker installation method as it provides the most consistent experience across all platforms.

Table of Contents​

Docker is the preferred installation method as it ensures all dependencies are correctly installed and provides consistent behavior across all platforms.

Prerequisites​

  • Docker (version 20.10 or newer)
  • Docker Compose (optional, for compose method)

Docker Run Method​

The simplest way to run Cleanuparr is with a single Docker command:

docker run -d --name cleanuparr \
  --restart unless-stopped \
  -p 11011:11011 \
  -v /path/to/config:/config \
  -e PORT=11011 \
  -e BASE_PATH= \
  -e PUID=1000 \
  -e PGID=1000 \
  -e UMASK=022 \
  -e TZ=Etc/UTC \
  ghcr.io/cleanuparr:latest

Option 2: DockerHub​

docker run -d --name cleanuparr \
  --restart unless-stopped \
  -p 11011:11011 \
  -v /path/to/config:/config \
  -e PORT=11011 \
  -e BASE_PATH= \
  -e PUID=1000 \
  -e PGID=1000 \
  -e UMASK=022 \
  -e TZ=Etc/UTC \
  cleanuparr/cleanuparr:latest

Docker Compose Method​

For easier management, create a docker-compose.yml file:

Option 1: GitHub Container Registry​

services:
  cleanuparr:
    image: ghcr.io/cleanuparr/cleanuparr:latest
    container_name: cleanuparr
    restart: unless-stopped
    ports:
      - "11011:11011"
    volumes:
      - /path/to/config:/config
    environment:
      - PORT=11011
      - BASE_PATH=
      - PUID=1000
      - PGID=1000
      - UMASK=022
      - TZ=Etc/UTC

Environment Variables​

VariableDefaultDescription
PORT11011Port for the web interface
BASE_PATH(empty)Base path for reverse proxy setups
PUID1000User ID for file permissions
PGID1000Group ID for file permissions
UMASK022File creation mask
TZEtc/UTCTimezone setting

Volume Mounts​

Container PathDescription
/configConfiguration files and database
Note

Replace /path/to/config with your desired configuration directory path on the host system.

Windows Installation​

Windows Installer​

The easiest way to install Cleanuparr on Windows is using the provided installer.

Installation Steps​

  1. Download the Windows installer (.exe) from the GitHub Releases page
  2. Double-click the downloaded .exe file to start installation
  3. Important: When Windows Defender SmartScreen appears, click "More info" and then "Run anyway"
  4. Follow the on-screen instructions to complete installation
  5. Cleanuparr will be installed as a Windows service and start automatically

Default Configuration​

  • Web Interface: http://localhost:11011
  • Service Name: Cleanuparr
  • Installation Directory: C:\Program Files\Cleanuparr\
  • Configuration: C:\ProgramFiles\Cleanuparr\config\

Windows Portable​

For users who prefer a portable installation:

  1. Download the Cleanuparr-{version}-win-amd64.zip from GitHub Releases
  2. Extract the zip file to your desired directory (e.g., C:\Tools\Cleanuparr\)
  3. Run Cleanuparr.exe to start the application
  4. Access the web interface at http://localhost:11011
Note

The portable version requires manual startup and doesn't install as a Windows service.

macOS Installation​

macOS Installer​

Cleanuparr provides native macOS installers for both Intel and Apple Silicon Macs.

Installation Steps​

  1. Download the appropriate .pkg installer from GitHub Releases:
    • Cleanuparr-{version}-macos-intel.pkg for Intel Macs
    • Cleanuparr-{version}-macos-arm64.pkg for Apple Silicon Macs
  2. Double-click the downloaded .pkg file
  3. When macOS shows a security warning, go to System Settings → Privacy & Security
  4. Scroll down and click "Open Anyway" to proceed with installation
  5. Follow the installation prompts
  6. Cleanuparr will be installed as a system service and start automatically

Default Configuration​

  • Web Interface: http://localhost:11011
  • Application: /Applications/Cleanuparr.app
  • Configuration: /Applications/Cleanuparr.app/Contents/MacOS/config/
  • Service: Managed by launchd
Important

macOS will show security warnings for unsigned applications. This is normal - click "Open Anyway" in System Settings to proceed.

macOS Portable​

For users who prefer a portable installation:

  1. Download the appropriate zip file from GitHub Releases:
    • Cleanuparr-{version}-osx-amd64.zip for Intel Macs
    • Cleanuparr-{version}-osx-arm64.zip for Apple Silicon Macs
  2. Extract the zip file to your desired directory
  3. Open Terminal and navigate to the extracted directory
  4. Make the binary executable: chmod +x Cleanuparr
  5. Run: ./Cleanuparr
  6. Access the web interface at http://localhost:11011

Linux Installation​

Linux users can use the portable executables, as we don't provide distribution-specific packages.

Portable Installation​

  1. Download the appropriate zip file from GitHub Releases:
    • Cleanuparr-{version}-linux-amd64.zip for x86_64 systems
    • Cleanuparr-{version}-linux-arm64.zip for ARM64 systems
  2. Extract the zip file: 
    unzip Cleanuparr-{version}-linux-amd64.zip
    cd Cleanuparr-{version}-linux-amd64/
  3. Make the binary executable: 
    chmod +x Cleanuparr
  4. Run Cleanuparr: 
    ./Cleanuparr
  5. Access the web interface at http://localhost:11011

Running as a Service (Systemd)​

To run Cleanuparr as a systemd service:

  1. Create a service file:

    sudo nano /etc/systemd/system/cleanuparr.service

  2. Add the following content:

    [Unit]
    Description=Cleanuparr
    After=network.target

    [Service]
    Type=simple
    User=cleanuparr
    Group=cleanuparr
    ExecStart=/opt/cleanuparr/Cleanuparr
    WorkingDirectory=/opt/cleanuparr
    Restart=always
    RestartSec=5
    Environment=PORT=11011
    Environment=BASE_PATH=

    [Install]
    WantedBy=multi-user.target

  3. Create a dedicated user:

    sudo useradd -r -s /bin/false cleanuparr

  4. Move Cleanuparr to /opt/cleanuparr and set ownership:

    sudo mkdir -p /opt/cleanuparr
    sudo cp Cleanuparr /opt/cleanuparr/
    sudo chown -R cleanuparr:cleanuparr /opt/cleanuparr

  5. Enable and start the service:

    sudo systemctl enable cleanuparr
    sudo systemctl start cleanuparr

Post Installation​

Default Configuration​

  • Web Interface: http://localhost:11011
  • Base Path: (empty) (for reverse proxy setups, change BASE_PATH environment variable)
  • Configuration Location: Varies by platform and installation method