How To Install PhotoPrism on Linux Mint 22

Managing thousands of photos across multiple devices can become overwhelming. PhotoPrism offers a powerful solution: an AI-powered, self-hosted photo management application that keeps your memories organized while maintaining complete privacy. This comprehensive guide walks you through installing PhotoPrism on Linux Mint 22, giving you full control over your photo library without relying on third-party cloud services.

PhotoPrism stands out with its advanced features including automatic tagging, face recognition, and support for RAW image formats. Unlike proprietary cloud services, this open-source platform ensures your photos remain on your own server. Linux Mint 22 provides an ideal environment for hosting PhotoPrism, combining the stability of Ubuntu 24.04 LTS with a user-friendly desktop experience.

Throughout this tutorial, you’ll learn how to install Docker and Docker Compose, configure a MariaDB database for optimal performance, and set up PhotoPrism with proper security measures. Whether you’re a photography enthusiast or simply want better control over your digital memories, this step-by-step installation guide provides everything needed to get PhotoPrism running on your Linux Mint system.

What is PhotoPrism?

PhotoPrism represents a new generation of photo management software designed for privacy-conscious users who want professional-grade features without sacrificing control over their data. Developed as a self-funded, independent open-source project, it leverages artificial intelligence to automatically organize and categorize your photo collection.

Core Features and Capabilities

The platform excels with AI-powered automatic photo organization that intelligently tags images based on content recognition. Its face recognition technology identifies people across your entire photo library, making it effortless to find pictures of friends and family. PhotoPrism supports an extensive range of file formats including RAW files from professional cameras, JPEG, PNG, HEIF, and video formats like MP4 and AVI.

Duplicate photo detection eliminates redundant images automatically, saving valuable storage space. The built-in geographic tagging system integrates with world maps, allowing you to browse photos by location. WebDAV support enables direct file access from Windows Explorer, macOS Finder, and mobile devices, creating seamless integration with your existing workflow.

Privacy and Self-Hosting Benefits

PhotoPrism prioritizes privacy with a 100% self-hosted architecture that never shares your data with third parties. You maintain complete control over your photo library, deciding where files are stored and who can access them. This approach provides a compelling alternative to cloud services like Google Photos or Apple iCloud, which analyze your images on their servers.

The self-funded development model ensures long-term commitment to privacy principles without pressure from investors or advertisers. Running PhotoPrism on your own hardware means your personal moments remain truly personal, with no external scanning, advertising, or data harvesting.

System Requirements

Before beginning the installation process, verify your system meets the minimum requirements for running PhotoPrism effectively. These specifications ensure smooth performance during photo indexing and browsing.

Hardware Requirements

PhotoPrism performs best with at least 2 CPU cores, though 4 cores are recommended for handling large photo libraries efficiently. Memory requirements start at 4 GB RAM, and ideally your RAM should match your CPU core count for optimal performance. For example, a 4-core system should have 4 GB RAM minimum.

Storage needs vary based on your photo collection size, but allocate at least 20 GB of free disk space for the application and initial photos. SSD storage is strongly recommended rather than traditional hard drives. Database operations and thumbnail generation benefit significantly from SSD speeds, reducing indexing time dramatically.

The platform supports 64-bit AMD, Intel, and ARM processor architectures, making it compatible with most modern computers and servers. Plan for additional storage based on your photo library size, keeping in mind that RAW files and high-resolution images consume substantial space.

Software Requirements

Linux Mint 22, which is based on Ubuntu 24.04 LTS, provides the perfect foundation for PhotoPrism installation. Ensure your system is fully updated before proceeding. Docker and Docker Compose are essential for container management, providing isolated environments that simplify deployment.

You’ll need root access or a user account with sudo privileges to install packages and configure services. An active internet connection is required for downloading Docker images and software packages during installation.

The minimum glibc version requirement of 2.35 is automatically satisfied by Linux Mint 22. For database backends, PhotoPrism supports SQLite 3 for small collections or MariaDB 10.5.12+ for production environments. MariaDB is highly recommended for photo libraries exceeding 100,000 images due to superior performance and scalability.

Prerequisites

Proper system preparation ensures a smooth installation process. These preliminary steps update your system and install necessary dependencies.

Updating Linux Mint 22 System

Begin by opening a terminal window through the menu or by pressing Ctrl+Alt+T. Execute the following commands to refresh package repositories and upgrade all installed software:

sudo apt update
sudo apt upgrade -y

The update process typically takes several minutes depending on your internet connection and the number of packages requiring updates. This step is crucial as it ensures compatibility with Docker and prevents conflicts from outdated dependencies.

Installing Required Packages

Docker installation requires several prerequisite packages for secure repository management. Install these essential components with the following command:

sudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg-agent -y

These packages enable secure HTTPS connections for package downloads, proper SSL certificate handling, and GPG key verification. The curl utility downloads files from the command line, while software-properties-common manages repository sources.

Step 1: Install Docker on Linux Mint 22

Docker provides the containerization platform that runs PhotoPrism isolated from your main system. This approach simplifies updates and prevents conflicts with other installed software.

Adding Docker’s Official GPG Key

Security best practices require verifying package authenticity through GPG keys. Download and add Docker’s official signing key to your system:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

This command fetches Docker’s public key and adds it to your system’s trusted key store. The GPG key ensures that packages downloaded from Docker’s repository haven’t been tampered with, protecting against malicious software injection.

Adding Docker Repository

Configure your system to download Docker packages from the official repository. Linux Mint uses Ubuntu as its base, so we reference Ubuntu repositories:

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

The lsb_release -cs command automatically detects your Ubuntu base version, ensuring compatibility. After adding the repository, update your package index:

sudo apt update

Installing Docker Engine

Now install Docker’s core components including the engine, command-line interface, and container runtime:

sudo apt install docker-ce docker-ce-cli containerd.io -y

The docker-ce package provides the Docker daemon that manages containers. Docker-ce-cli delivers the command-line tools for interacting with Docker. Containerd.io handles the low-level container runtime operations. Installation typically completes within 2-3 minutes.

Verifying Docker Installation

Confirm Docker installed correctly and is running properly:

sudo systemctl status docker

You should see output indicating the service is “active (running)”. Check the installed version:

docker --version

Optionally, test Docker’s functionality by running a test container:

sudo docker run hello-world

This command downloads a small test image and runs it, confirming Docker can pull images and execute containers successfully.

Step 2: Install Docker Compose

Docker Compose orchestrates multi-container applications, perfect for PhotoPrism which requires coordination between the application and database containers.

Downloading Docker Compose Binary

Fetch the latest stable release of Docker Compose from GitHub’s official repository:

sudo curl -L "https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

The uname commands automatically detect your operating system and processor architecture, downloading the correct binary version. This installation method places Docker Compose in the system-wide binary directory.

Setting Permissions and Creating Symlink

Make the Docker Compose binary executable:

sudo chmod +x /usr/local/bin/docker-compose

Create a symbolic link for easier access:

sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Verify successful installation:

docker-compose --version

The output displays the installed Docker Compose version number, confirming proper installation and configuration.

Step 3: Create Directory Structure for PhotoPrism

Organizing your PhotoPrism installation with proper directory structure maintains system cleanliness and simplifies management.

Creating Storage Directories

Create a dedicated directory for PhotoPrism in your home folder or /opt:

mkdir -p ~/photoprism
cd ~/photoprism

Establish subdirectories for different data types:

mkdir -p originals import storage database

Alternatively, if you prefer storing data in a separate location with more space:

sudo mkdir -p /mnt/photoprism/{originals,import,storage,database}

Set appropriate ownership if using system directories:

sudo chown -R $USER:$USER /mnt/photoprism

Understanding Directory Purpose

Each directory serves a specific function in PhotoPrism’s operation. The originals directory stores your permanent photo collection. PhotoPrism never modifies files in this location, ensuring your original images remain untouched.

The import directory acts as a temporary staging area for new photos. Files placed here can be moved to originals during the import process. The storage directory contains thumbnails, cache files, and sidecar files (JSON metadata). The database directory holds MariaDB data files when using an external database.

Step 4: Install and Configure MariaDB (Optional but Recommended)

While PhotoPrism supports SQLite for small collections, MariaDB significantly improves performance for larger photo libraries.

Why Use MariaDB Instead of SQLite

SQLite works adequately for testing and small libraries under 100,000 photos. However, it struggles with concurrent access and complex queries on larger datasets. MariaDB provides superior scalability, handling millions of photos efficiently with multiple simultaneous users.

Production environments benefit from MariaDB’s transaction management, better concurrent access handling, and faster query execution. The performance difference becomes noticeable during initial indexing and when browsing large albums.

Database Configuration Settings

MariaDB requires specific character set configurations for proper multilingual support. The utf8mb4 character set handles emojis and special characters correctly, while utf8mb4_unicode_ci collation ensures proper sorting across languages.

Strong passwords protect your database from unauthorized access. Choose passwords containing uppercase letters, lowercase letters, numbers, and special characters. Never use default or simple passwords in production environments.

Step 5: Create Docker Compose Configuration File

Docker Compose uses YAML files to define service configurations, making complex setups manageable and reproducible.

Creating docker-compose.yml File

Navigate to your PhotoPrism directory and create the configuration file:

cd ~/photoprism
nano docker-compose.yml

Copy and paste the following comprehensive configuration:

version: '3.5'

services:
  photoprism:
    image: photoprism/photoprism:latest
    container_name: photoprism
    restart: unless-stopped
    security_opt:
      - seccomp:unconfined
      - apparmor:unconfined
    ports:
      - "2342:2342"
    environment:
      PHOTOPRISM_ADMIN_USER: "admin"
      PHOTOPRISM_ADMIN_PASSWORD: "ChangeThisPassword"
      PHOTOPRISM_AUTH_MODE: "password"
      PHOTOPRISM_SITE_URL: "http://localhost:2342/"
      PHOTOPRISM_SITE_TITLE: "My PhotoPrism"
      PHOTOPRISM_SITE_CAPTION: "AI-Powered Photos App"
      PHOTOPRISM_DATABASE_DRIVER: "mysql"
      PHOTOPRISM_DATABASE_SERVER: "mariadb:3306"
      PHOTOPRISM_DATABASE_NAME: "photoprism"
      PHOTOPRISM_DATABASE_USER: "photoprism"
      PHOTOPRISM_DATABASE_PASSWORD: "DatabasePassword123"
      PHOTOPRISM_ORIGINALS_LIMIT: 5000
      PHOTOPRISM_HTTP_COMPRESSION: "gzip"
      PHOTOPRISM_LOG_LEVEL: "info"
      PHOTOPRISM_READONLY: "false"
      PHOTOPRISM_EXPERIMENTAL: "false"
      PHOTOPRISM_DISABLE_CHOWN: "false"
      PHOTOPRISM_DISABLE_WEBDAV: "false"
      PHOTOPRISM_DISABLE_SETTINGS: "false"
      PHOTOPRISM_DISABLE_TENSORFLOW: "false"
      PHOTOPRISM_DISABLE_FACES: "false"
      PHOTOPRISM_DISABLE_CLASSIFICATION: "false"
      PHOTOPRISM_JPEG_QUALITY: 85
      PHOTOPRISM_DETECT_NSFW: "false"
      PHOTOPRISM_UPLOAD_NSFW: "true"
    working_dir: "/photoprism"
    volumes:
      - "./originals:/photoprism/originals"
      - "./storage:/photoprism/storage"
      - "./import:/photoprism/import"
    depends_on:
      - mariadb

  mariadb:
    image: mariadb:10.11
    container_name: mariadb
    restart: unless-stopped
    security_opt:
      - seccomp:unconfined
      - apparmor:unconfined
    command: mysqld --innodb-buffer-pool-size=512M --transaction-isolation=READ-COMMITTED --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --max-connections=512 --innodb-rollback-on-timeout=OFF --innodb-lock-wait-timeout=120
    volumes:
      - "./database:/var/lib/mysql"
    environment:
      MARIADB_AUTO_UPGRADE: "1"
      MARIADB_INITDB_SKIP_TZINFO: "1"
      MARIADB_DATABASE: "photoprism"
      MARIADB_USER: "photoprism"
      MARIADB_PASSWORD: "DatabasePassword123"
      MARIADB_ROOT_PASSWORD: "RootPassword456"

Save the file by pressing Ctrl+X, then Y, then Enter in nano.

PhotoPrism Service Configuration

The configuration defines critical settings for your PhotoPrism instance. Replace PHOTOPRISM_ADMIN_PASSWORD with a strong, unique password for your admin account. Change PHOTOPRISM_DATABASE_PASSWORD to match the MariaDB user password.

The PHOTOPRISM_SITE_URL should reflect your actual access URL. Use your server’s IP address if accessing remotely. Security options allow PhotoPrism to perform necessary system operations within the container.

Port mapping 2342:2342 exposes PhotoPrism’s web interface on port 2342. Volume mounts connect host directories to container paths, ensuring data persistence even when containers are recreated.

MariaDB Service Configuration

MariaDB configuration includes performance optimizations for photo management workloads. The innodb-buffer-pool-size allocates memory for database caching, significantly improving query performance. Adjust this value based on available system RAM.

Character set configuration ensures proper handling of international characters and emojis in filenames and metadata. The max-connections parameter allows sufficient concurrent database connections during intensive operations like initial indexing.

Root password provides administrative access to the database. Keep this separate from the PhotoPrism user password for better security segregation.

Step 6: Launch PhotoPrism with Docker Compose

With configuration complete, start your PhotoPrism installation using Docker Compose.

Starting the Containers

Execute the following command from your photoprism directory:

sudo docker-compose up -d

The -d flag runs containers in detached mode, allowing them to operate in the background. During first launch, Docker downloads required images, which may take 5-10 minutes depending on internet speed.

You’ll see output showing image pulls and container creation. Once complete, PhotoPrism and MariaDB run continuously in the background.

Verifying Container Status

Check that both containers are running properly:

sudo docker-compose ps

Both services should show “Up” status. View real-time logs to monitor startup progress:

sudo docker-compose logs -f photoprism

Press Ctrl+C to exit log viewing. Look for messages indicating successful database connection and server startup. Initial database migration may take a few minutes on first launch.

Step 7: Initial PhotoPrism Setup and Configuration

Access PhotoPrism’s web interface to complete setup and begin organizing your photos.

Accessing PhotoPrism Web Interface

Open your web browser and navigate to:

http://localhost:2342

If accessing from another computer on your network, replace localhost with your server’s IP address:

http://192.168.1.100:2342

The PhotoPrism login screen appears. Enter the admin username and password specified in your docker-compose.yml file.

First-Time Configuration

After logging in, navigate to Settings through the menu icon in the top right. Review and adjust the following critical settings:

Library Settings: Configure automatic indexing schedules if desired. Enable or disable face recognition based on your preferences and system resources. Face detection requires additional processing time but provides powerful search capabilities.

Quality Settings: Adjust JPEG quality for thumbnails between 80-95. Higher values produce better quality at the cost of storage space. Balance quality with available disk space based on your library size.

Privacy Settings: Configure upload permissions, disable features you don’t need, and set appropriate access controls. Consider enabling require authentication for downloads if security is paramount.

Display Settings: Set your preferred language, timezone, and theme. These settings affect how dates appear and localization of the interface.

Importing Photos

PhotoPrism offers multiple methods for adding photos to your library. The web interface provides an upload button for adding photos directly through your browser. This method works well for small batches but may be slow for large collections.

For bulk imports, copy photos directly to the originals directory:

cp -r /path/to/your/photos/* ~/photoprism/originals/

Alternatively, use the import directory for photos you want to review before permanently adding to your library. Place files in the import directory, then use PhotoPrism’s Import tab to review and move them to originals.

After adding photos, trigger indexing through the Library section in settings. Initial indexing processes all photos, extracting metadata, generating thumbnails, and running AI analysis. Large libraries may require several hours for complete indexing.

Step 8: Configure Firewall (If Applicable)

Proper firewall configuration balances security with accessibility, especially when accessing PhotoPrism from other devices on your network.

UFW Firewall Configuration

Check if UFW (Uncomplicated Firewall) is active:

sudo ufw status

If active, allow access to PhotoPrism’s port:

sudo ufw allow 2342/tcp

For restrictive setups, limit access to specific IP addresses or subnets:

sudo ufw allow from 192.168.1.0/24 to any port 2342

Verify the new rule:

sudo ufw status numbered

Security Considerations

Never expose PhotoPrism directly to the internet without additional security measures. Implement a reverse proxy like Nginx with HTTPS encryption for internet-facing deployments. Use strong, unique passwords for all accounts, and consider implementing two-factor authentication if your usage scenario requires it.

Regular updates maintain security. Monitor PhotoPrism’s release announcements and apply updates promptly. Keep Docker, Docker Compose, and Linux Mint current with security patches.

Managing PhotoPrism

Understanding basic management commands ensures smooth long-term operation of your PhotoPrism installation.

Common Docker Compose Commands

Stop PhotoPrism and MariaDB containers:

sudo docker-compose down

This gracefully shuts down services while preserving all data. Start containers again:

sudo docker-compose up -d

Restart services without stopping:

sudo docker-compose restart

View container logs for troubleshooting:

sudo docker-compose logs -f

Check resource usage:

sudo docker stats

Updating PhotoPrism

Keep PhotoPrism current with the latest features and security fixes. Stop running containers first:

sudo docker-compose down

Pull the latest images:

sudo docker-compose pull

Recreate containers with updated images:

sudo docker-compose up -d

Always back up your database and configuration files before major updates. Create backups regularly to prevent data loss from hardware failures or configuration mistakes.

Troubleshooting Common Issues

Even with careful setup, you may encounter occasional issues. These solutions address the most common problems.

Container Won’t Start

If containers fail to start, first check Docker service status:

sudo systemctl status docker

Restart Docker if necessary:

sudo systemctl restart docker

Examine container logs for error messages:

sudo docker-compose logs mariadb
sudo docker-compose logs photoprism

Verify port 2342 isn’t already in use:

sudo netstat -tulpn | grep 2342

Check directory permissions on mounted volumes. PhotoPrism requires read and write access to originals, storage, and import directories.

Cannot Access Web Interface

If you can’t reach PhotoPrism’s web interface, verify containers are running:

sudo docker ps

Test connectivity locally first:

curl http://localhost:2342

If this works but remote access fails, check firewall rules. Clear browser cache and cookies if the login page doesn’t load correctly. Try accessing from a different browser to rule out browser-specific issues.

Database Connection Errors

Database connection problems typically stem from configuration mismatches or MariaDB startup failures. Verify MariaDB container is running and healthy:

sudo docker logs mariadb

Ensure database credentials in docker-compose.yml match between PhotoPrism and MariaDB sections. Both PHOTOPRISM_DATABASE_PASSWORD and MARIADB_PASSWORD must be identical.

Test database connectivity from PhotoPrism container:

sudo docker exec -it photoprism photoprism config

Review connection strings and verify database creation completed successfully.

Performance Optimization Tips

Optimize your PhotoPrism installation for the best possible performance based on your hardware capabilities.

Hardware Optimization

Allocate sufficient RAM to Docker containers by modifying the innodb-buffer-pool-size in your docker-compose.yml. Systems with 8 GB RAM can allocate 1-2 GB to MariaDB. Servers with 16 GB or more can dedicate 4 GB or higher.

SSD storage dramatically improves indexing speed and thumbnail generation. If possible, store the database and storage directories on SSD while keeping originals on larger, slower hard drives. This configuration provides fast access to frequently used data while maximizing storage capacity.

Monitor system resources during indexing operations. Use htop or docker stats to identify bottlenecks. If CPU usage consistently maxes out, consider reducing concurrent workers in PhotoPrism settings.

Software Configuration

Adjust PhotoPrism’s worker count based on CPU cores. Navigate to Settings > Library and modify indexing workers. More workers speed up processing but increase resource usage. A good starting point is one worker per CPU core.

Disable unnecessary features to reduce resource consumption. If you don’t need facial recognition, disable it to save processing time and memory. The same applies to TensorFlow-based classification if you prefer manual tagging.

Schedule intensive operations like indexing during off-peak hours. If accessing PhotoPrism mainly in evenings, schedule automatic indexing for early morning when system load is minimal.

Regular database maintenance improves query performance. Run PhotoPrism’s optimization commands periodically to keep the database efficient.

Congratulations! You have successfully installed PhotoPrism. Thanks for using this tutorial for installing the PhotoPrism open-source photo and video management on the Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official PhotoPrism website.