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.

Docker Run​

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/cleanuparr:latest

Docker Compose​

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
    # Health check configuration
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:11011/health"]
      interval: 30s        # Check every 30 seconds
      timeout: 10s         # Allow up to 10 seconds for response
      start_period: 30s    # Wait 30 seconds before first check
      retries: 3           # Mark unhealthy after 3 consecutive failures

Environment Variables​

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

Volume Mounts​

Container PathDescription
/configConfiguration files, log files and database
💡Note

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

Unraid

Use the Unraid template available in the Community Applications plugin. If the template is not yet available, you can manually add using the above Docker Compose configuration or use this guide to create a custom template:

  1. Download the template from here: https://github.com/Cleanuparr/unraid/blob/main/templates/Cleanuparr.xml
  2. Rename the downloaded file to 'my-cleanuparr.xml'
  3. Drop it in the /boot/config/plugins/dockerMan/templates-user/ folder of your Unraid machine
  4. Go to the Docker tab of the Unraid webui
  5. Click on Add Container
  6. From the Template dropdown menu, select cleanuparr
  7. Set the repository to ghcr.io/cleanuparr/cleanuparr:latest
  8. Most other settings can be left at default, with the exception of the downloads folder which should be mapped to where your *arr stack / torrent client downloads its files to

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\
💡Note

To change the port or base path, see Port and Base Path (Non-Docker).

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. To change the port or base path, see Port and Base Path (Non-Docker).

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.

💡Note

To change the port or base path, see Port and Base Path (Non-Docker).

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
💡Note

To change the port or base path, see Port and Base Path (Non-Docker).

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
💡Note

To change the port or base path, see Port and Base Path (Non-Docker).

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
💡Note

For systemd services, you can also configure PORT and BASE_PATH directly in the service file using the Environment directive, or use the Port and Base Path (Non-Docker) configuration file method.

Arch Linux​

cleanuparr on AUR cleanuparr-bin on AUR

Cleanuparr is available on the AUR:

You can install it using your AUR helper of choice.

Example:

$ yay -Sy cleanuparr
💡Note

To change the port or base path for AUR installations, see Port and Base Path (Non-Docker).

Port and Base Path (Non-Docker)

For all non-Docker installations (Windows, macOS, Linux portable), you can configure the PORT and BASE_PATH by creating a configuration file.

Initial Setup​

  1. Start Cleanuparr for the first time to initialize the application and create the config directory

  2. Navigate to the config directory:

    • Windows Installer: C:\ProgramFiles\Cleanuparr\config\
    • Windows Portable: [installation-directory]\config\
    • macOS Installer: /Applications/Cleanuparr.app/Contents/MacOS/config/
    • macOS Portable: [installation-directory]/config/
    • Linux: [installation-directory]/config/

  3. Create a file named cleanuparr.json in the config directory with the following contents (modify as needed):

{
  "PORT": 11011,
  "BASE_PATH": ""
}
  1. Restart Cleanuparr for the changes to take effect

Example Configurations​

Running on port 8080:

{
  "PORT": 8080,
}

Access via: http://localhost:8080

Running with reverse proxy at /cleanuparr:

{
  "BASE_PATH": "/cleanuparr"
}

Access via: http://yourdomain.com/cleanuparr

Custom port with base path:

{
  "PORT": 8080,
  "BASE_PATH": "/apps/cleanup"
}

Access via: http://yourdomain.com:8080/apps/cleanup

Post Installation

Default Configuration​

  • Web Interface: http://localhost:[PORT][BASE_PATH] (default: http://localhost:11011)
  • Configure your download clients and *arr applications
  • Refer to the Configuration section for detailed setup instructions

Health Checks​

Cleanuparr provides health check endpoints for monitoring and container orchestration. For detailed information about available endpoints and configuration, see the Health Checks documentation.