The safest way to run PhotoPrism on a private server is with Docker Compose: download the official example for your host and CPU architecture, review its storage and password settings, then start it with docker compose up -d. Sign in at http://localhost:2342/. For updates, make a backup first and run docker compose up -d --pull always from the same configuration directory.
This guide covers a first installation, storage layout, memory requirements, password changes, routine updates, major-version precautions, and recovery decisions without assuming a particular NAS model.
As an Amazon Associate I earn from qualifying purchases.
What you need before installing
PhotoPrism’s Docker examples use Docker Compose v2, provided by the Docker Compose plugin. Docker must be installed and running on the target machine, and your account must be allowed to access the Docker daemon. If docker compose is not recognized, verify both conditions before changing the PhotoPrism files.
Free tools Windows power users keep installed
One-click scans. No signup required.
The examples are available for Linux, Windows, macOS, Raspberry Pi/ARM64, and ARMv7. Choose the example that matches the operating system and processor architecture of the host. PhotoPrism also documents Docker-capable operating systems, FreeBSD, Raspberry Pi systems, and many NAS devices, but “many NAS devices” is not a guarantee that every model or operating-system release is compatible.
#1 Best Overall
- [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
- [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
- [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
- [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
- [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.
Check Docker Compose v2
- Open a shell on the host where PhotoPrism will run.
- Run
docker --versionanddocker compose version. - Confirm Docker is running and that the Compose command returns a v2 version.
PhotoPrism’s troubleshooting guidance also mentions Podman Compose as a possible alternative on Red Hat-compatible distributions. That is a platform-specific alternative, not a drop-in guarantee for every installation; commands, volume behavior, and support can differ, so use Docker Compose for the procedure below unless your distribution’s documentation specifically supports the alternative.
Plan disk locations
Decide where the original photos, the PhotoPrism storage directory, and any optional import directory will live. Your original files should remain on persistent storage outside the container’s writable layer. A container can be replaced during an update; bind-mounted data survives that replacement when the host paths are correct.
- Originals: your existing photo and video library. This is normally mounted at
/photoprism/originalsinside the container. - Storage: PhotoPrism’s index, thumbnails, sidecars, cache, and related application data. Keep this directory backed up.
- Import: an optional staging directory for files that PhotoPrism will copy or move into the originals tree according to your import settings.
Do not place the import directory inside the originals directory. PhotoPrism warns that this can create a loop in which indexed files are encountered and imported again.
Download and review the Compose file
Start with the official PhotoPrism Compose example suited to your host platform and architecture. Save it in a dedicated configuration directory, such as ~/photoprism on Linux or a clearly named folder on Windows or macOS. The default filename is compose.yaml. The older docker-compose.yml filename remains supported for backward compatibility.
Before starting anything, read the file rather than treating it as an opaque download. Confirm the image tag, service name, ports, environment variables, and every volume mapping. A path typo can make PhotoPrism appear to start normally while pointing at an empty library or an unintended disk.
Set a strong initial administrator password
Find PHOTOPRISM_ADMIN_PASSWORD and replace the example value with a unique password of at least eight characters. Do not retain an easy-to-guess or default password. This setting is used only during first startup; changing the value later does not change the existing administrator password.
If an environment value contains a literal dollar sign, escape it as $$ in the Compose file. Compose interprets an unescaped dollar sign as variable substitution, which can silently alter a password or another setting.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #2
- 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
- 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
- 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
- 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
- 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.
Map the originals and storage directories
Change the host-side path in the originals volume to the directory that actually contains your photos. Keep the container-side destination as /photoprism/originals unless you have a deliberate reason to change the application configuration. Add other photo directories as additional mounts beneath that destination when needed.
Use persistent host paths for PhotoPrism’s storage directory as well. If the storage mount is omitted or points to a temporary location, rebuilding the service can discard the index and thumbnails even though the original image files remain intact.
On Windows, use a drive letter and forward slashes in host paths, for example C:/Users/you/Photos. Ensure Docker Desktop has permission to access the drive or folder you select. The exact permission prompts depend on your Docker Desktop version and host settings.
Allocate enough memory and swap
PhotoPrism’s Compose guidance recommends at least 4 GB of swap for Linux examples and advises against imposing a hard container memory limit. Indexing can need additional memory, especially with RAW files and high-resolution panoramas. The 4 GB swap figure is the vendor’s recommendation, not an independent performance benchmark or a promise that every library will run within that amount.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →For Windows using Hyper-V, the guide calls for at least 4 GB of Docker memory. Docker Desktop with WSL 2 uses dynamic memory allocation, so a manual adjustment may not be necessary depending on the installed version and its configuration. The macOS instructions also call for 4 GB or more, compared with the 2 GB default noted by PhotoPrism.
- Do not confuse host RAM, Docker’s virtual-machine allocation, and swap; they solve different pressure points.
- If the indexer is killed or the host begins swapping heavily, reduce concurrent workloads and increase available resources before assuming the Compose file is broken.
- Keep free disk space available for thumbnails, database growth, logs, and temporary processing.
Start PhotoPrism for the first time
- Open a terminal and change to the directory containing
compose.yaml(ordocker-compose.yml). - Review the final paths, password, port mapping, and image tag.
- Start the services in the background:
docker compose up -dDocker downloads the required image layers and creates the containers. The first start can take several minutes, depending on the connection and disk speed. Watch the command output for image-pull, permission, or mount errors rather than assuming a returned prompt means indexing has finished.
Open the web interface
On the host itself, open http://localhost:2342/. Sign in with username admin and the initial password you placed in PHOTOPRISM_ADMIN_PASSWORD. If you are connecting from another computer, use the server’s reachable address and the port exposed by your Compose file; localhost always means the machine running the browser.
Rank #3
- [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
- [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
- [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
- [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
- [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by
Change the password after first startup
Because the environment variable does not update an already-created account, use PhotoPrism’s password command for a later change:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
docker compose exec photoprism photoprism passwd [username]Replace [username] with the account whose password you want to change. Run the command from the Compose directory so Compose can identify the project and the photoprism service.
Verify the installation before importing a large library
Use a small, representative set of photos to validate the mounts and permissions before pointing PhotoPrism at a large archive. Check that originals are visible, thumbnails are generated, and the indexer can read files without permission errors.
- Confirm the originals directory in the web interface corresponds to the intended host folder.
- Check that the storage directory is on persistent disk and is not inside a disposable container layer.
- Verify that an optional import directory is separate from originals.
- Look for sufficient free space and memory during initial indexing.
- Keep the terminal available for container-status and log checks if the interface does not load.
When a port or another Compose setting is changed, restart the services so the new configuration is applied:
docker compose stopdocker compose up -d
Stopping and starting containers does not delete bind-mounted originals or storage. Destructive reset commands are a different operation and require a backup first.
How routine updates work
PhotoPrism does not fetch a newer image merely because the Compose file uses a :latest tag. You must explicitly pull and recreate the service, or configure a separate automatic-update mechanism.
Manual update procedure
- Finish or pause any important import and indexing work.
- Back up the PhotoPrism storage folder and any other data you need to restore. Include the originals if they are not already protected by a separate backup system.
- Read the release notes for the version you are about to run, paying particular attention to database migrations and breaking changes.
- Change to the directory containing the Compose file.
- Pull the current image and recreate the service in the background:
docker compose up -d --pull alwaysThe pull and restart may take several minutes. Compose retains the declared volumes and settings while replacing containers as needed. After the command completes, open the web interface, verify login, and check that the expected originals, albums, and search data are present.
Rank #4
- Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
- Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
- All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
- Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
- Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
Why a backup is mandatory before an update
PhotoPrism states: “A new version may upgrade your index database when it starts.” A database migration can be one-way or difficult to reverse, so a backup gives you a recovery point if the new image exposes a problem. Take extra care before a major update or before switching from the stable image to the development preview tag.
A practical backup should cover the storage folder, the Compose file, and the environment values needed to recreate the service. Protect the original media separately; a database backup cannot replace the photo and video files themselves.
Manual versus automatic image updates
| Approach | How it works | Advantage | Risk or cost |
|---|---|---|---|
| Manual | Run docker compose up -d --pull always when you choose. |
You control timing, backups, release-note review, and maintenance windows. | Someone must remember to check for and apply updates. |
| Automatic | Use a separate update service configured to watch and restart containers. | Less routine administration and faster access to published fixes. | An update can interrupt indexing or import without a planned maintenance window. |
PhotoPrism describes Watchtower as an automatic-update option but warns that updates can interrupt indexing and import operations. Automatic updates are therefore a trade-off, not a universal default. A large or actively ingesting library generally benefits from deliberate timing and a verified backup.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Stable latest versus development preview
| Image choice | Best suited to | What to expect |
|---|---|---|
:latest |
Everyday personal or family libraries where predictable operation matters. | Stable releases still require a manual pull or another update mechanism; the tag itself does not auto-update. |
:preview |
Testing upcoming features or reproducing an issue before a stable release. | Greater change risk and a stronger need for backups and release-note review. |
Do not switch tags casually on a production library. Back up first, test the preview with a copy or a separately managed project when possible, and expect that database changes may require a recovery plan.
What to do after a major upgrade
Read the release notes and allow the first startup to complete its database work before launching other heavy tasks. If search results, filters, or sorting look incomplete after a major upgrade, consider a complete rescan. PhotoPrism specifically notes that a rescan can help expose new filters and sorting options and correct missing or inaccurate results.
A rescan is resource-intensive. Do not run concurrent indexing processes; overlapping jobs increase server load and can make troubleshooting harder. Let one indexing operation finish, then evaluate the results before starting another.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Signs that a rescan may help
- New search filters or sorting choices are not reflected in existing results.
- Images that should match a query are missing.
- Labels, metadata, or dates appear inconsistent after a schema or feature change.
- The release notes specifically call for re-indexing.
Troubleshooting common installation and update failures
docker compose is unavailable
Confirm Docker is installed, the Docker service or Desktop application is running, and your user has permission to access it. Install or enable the Docker Compose v2 plugin rather than relying on the obsolete standalone command. If your distribution uses a vendor package, check that the package actually provides the docker compose subcommand.
The site does not open on port 2342
Run the Compose command from the correct directory and inspect whether the service was created successfully. Check the port mapping in the file, confirm another process is not already using the host port, and verify that a host firewall or remote-network rule is not blocking access. Use localhost only on the Docker host; remote clients must use the host’s network address.
The library is empty
Re-check the host-side originals path and its permissions. A valid container can still show an empty library when the mount points to the wrong folder. On Windows, verify drive-sharing or folder-access permissions in Docker Desktop and use forward slashes with the drive letter.
Files are imported repeatedly
Inspect the import and originals mounts. Move the import directory outside the originals tree, then restart the services after editing the Compose configuration. Do not use an import location that is also scanned as the final originals directory.
Recommended Free Tools
The container runs out of memory or indexing stops
Check available host memory and swap, remove an imposed hard memory limit, and reduce competing workloads. RAW images and high-resolution panoramas can require more than the baseline recommendation. On Hyper-V and macOS, verify that Docker has at least the memory allocation specified in the platform guidance; WSL 2 may manage memory dynamically.
An update appears stuck
Image downloads can take several minutes. Check network connectivity and disk space, then inspect container status and logs from the Compose project. Do not repeatedly start overlapping update commands. If the new image started a database migration, allow it to finish and consult the release notes before attempting a rollback.
Reset and recovery warnings
PhotoPrism’s reset and migration-recovery commands can permanently delete data and cannot be undone. Before using any reset procedure, make a verified backup that includes the storage folder and the original media. A reset should be a deliberate recovery decision after identifying the failure, not a routine troubleshooting step.
If the service must be recreated, preserve the Compose file, host paths, environment values, and backups. Recreating containers is normally less dangerous than deleting volumes, but an incorrect volume declaration can still make existing data appear to vanish. Stop and verify the configuration before removing anything.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsQuick Recap
A repeatable maintenance checklist
- Keep the Compose file and its host paths documented.
- Check PhotoPrism release notes before major updates or preview use.
- Back up the storage folder and protect originals independently.
- Pause active imports and indexing before maintenance.
- Run
docker compose up -d --pull alwaysfrom the project directory. - Wait for startup and any database migration to finish.
- Sign in and verify originals, search, albums, and recent imports.
- Run a complete rescan only when a major update or incorrect results justify the load.
- Record the image tag and date of each deliberate change so a later recovery has a known starting point.
Key commands at a glance
| Purpose | Command |
|---|---|
| Start or recreate services without forcing an image pull | docker compose up -d |
| Pull the newest image and recreate services | docker compose up -d --pull always |
| Stop services before applying a configuration change | docker compose stop |
| Change an existing user’s password | docker compose exec photoprism photoprism passwd [username] |
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
