-
Notifications
You must be signed in to change notification settings - Fork 0
Getting Started Desktop
The Photosphere Desktop app is an application for managing your media file database through a graphical user interface on Windows, macOS, and Linux.
Get the latest release from GitHub:
Find the latest numbered version, or if you are feeling lucky find the latest nightly build.
Download the appropriate installer or archive for your platform:
| Platform | File |
|---|---|
| Windows (installer) | photosphere-desktop-*-win-x64.exe |
| Windows (portable) | photosphere-desktop-*-win-x64.zip |
| macOS Apple Silicon (installer) | photosphere-desktop-*-mac-arm64.dmg |
| macOS Apple Silicon (portable) | photosphere-desktop-*-mac-arm64.zip |
| macOS Intel (installer) | photosphere-desktop-*-mac-x64.dmg |
| macOS Intel (portable) | photosphere-desktop-*-mac-x64.zip |
| Linux (Debian/Ubuntu) | photosphere-desktop-*-linux-amd64.deb |
| Linux (portable) | photosphere-desktop-*-linux-x64.zip |
Run the .exe installer and follow the prompts, or extract the .zip archive and run Photosphere.exe directly.
Open the .dmg file, drag Photosphere to your Applications folder, and launch it from there.
macOS Security Warning: If you see "cannot be opened because the developer cannot be verified", right-click the app and choose Open, then confirm. Alternatively, remove the quarantine attribute from the terminal:
xattr -cr /Applications/Photosphere.appThis is required because macOS Gatekeeper quarantines downloaded binaries not signed by a registered Apple developer. This is safe for trusted applications like Photosphere.
Debian/Ubuntu: Install the .deb package:
sudo dpkg -i photosphere-desktop-*-linux-amd64.debOther distributions: Extract the .zip archive and run the photosphere executable directly.
Photosphere requires ImageMagick and FFmpeg to import photos and videos. See the Required Tools page for platform-specific installation instructions and troubleshooting.
When you launch Photosphere, you will be presented with the option to open an existing database or create a new one.
- Open existing: Click Open Database and navigate to a directory that already contains a Photosphere database.
- Create new: Click Open Database, navigate to an empty directory (or create a new one), and select it. Photosphere will initialise a new database there.
The app remembers your recently opened databases and will automatically reopen the last one on subsequent launches.
Adding media files directly in the desktop app is coming soon. In the meantime, use the CLI tool to add photos and videos to your database:
psi add ~/Pictures/2024/See Getting-Started-CLI for full details on the psi add command.
Your media is displayed in a scrollable gallery sorted by date (newest first). You can:
- Scroll through the gallery to browse all your photos and videos
- Click a photo to open a full-size view
- Search using the search icon in the navigation bar — see Gallery-Search to search for photos by name, description, location, label, etc.
Click any photo in the gallery to open the full-screen view. The toolbar at the top contains:
- Star — marks the photo with a "starred" label for easy filtering
- Flag — marks the photo with a "flagged" label
- Download — saves the original file to your local filesystem
- Copy to clipboard — copies a display-quality version as a PNG
- Info — opens the Photo Details panel (see below)
- Delete — removes the photo (with a confirmation prompt)
Labels are shown at the bottom of the screen. Click a label to search the gallery for other photos with the same label. Use the tag icon to add a new label inline.
Click Download to save the original file.
Click the Info button in the photo view to open the Photo Details panel. This shows:
- Description — editable free-text field
- Asset ID and Asset hash
- Date and time the photo or video was taken
- Location (if present in the file metadata)
- Original filename and dimensions
- Labels — add or remove labels; click a label to search the gallery for matching photos
- Star / Flag toggles
- Delete button
To select multiple photos, hover over any photo in the gallery and click the checkmark that appears. You can also select the current photo while in the photo view using the select button in the toolbar.
When one or more photos are selected, the navbar shows the selection count. Open the overflow menu (⋮) to perform bulk operations:
- Move to — move selected photos to another open database
- Download — save all selected photos to your local filesystem
- Delete — delete all selected photos (with a confirmation prompt)
Click the ✕ next to the selection count in the navbar to clear the selection.
The desktop app includes a database management page for registering, editing, and removing database entries. Open it from the left sidebar by clicking Manage Databases. Each entry has a name, path, and optional links to shared secrets — when you open a database with linked secrets, credentials are resolved automatically.
See Managing-Databases for full details.
The desktop app includes a secrets management page for storing S3 credentials, encryption keys, and API keys. Open it from the left sidebar by clicking Manage Secrets. Secrets can also be created inline when adding or editing a database entry.
See Managing-Secrets for full details.
The desktop app stores preferences in ~/.config/photosphere/desktop.json, including:
- UI theme (light, dark, or system)
- Recently opened databases
- Last opened database (auto-reopened on launch)
See Configuration-Desktop for the full list of configuration keys.