PiGallery2: A Read-Only, Directory-First Gallery for Weak Hardware
A fast directory-first photo gallery website, with rich UI, optimized for running on low resource servers (especially on raspberry pi)
At a glance
- What is it?
- PiGallery2 is a TypeScript photo gallery that keeps your folder tree intact and runs on low-resource servers, with Docker as the only officially supported install path. It suits people who already organise photos in directories and want a browsable web front end without a database import step.
- Who is it for?
- Adopt PiGallery2 if your photos already live in a folder tree you maintain by hand and the host is a Raspberry Pi or a small VPS, because the read-only guarantee means the worst case is a broken web front end, not a damaged library. Do not adopt it if you need face recognition, semantic search, or write-back editing of metadata, since the project describes itself as read-only and directory-first.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 22 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem PiGallery2 solves: browsing a folder tree you already own
Most self-hosted galleries ask you to import photos into a managed library. That import is a one-way door: filenames get rewritten, folders get flattened, and the tool's database becomes the source of truth. PiGallery2 takes the opposite position. The README calls it "directory-first" and says it "Shows your folder structure as it is." If your photos are already sorted as /photos/2024/Scotland/ or /photos/Kids/Birthday, the gallery renders that structure directly rather than inventing its own.
The second constraint is hardware. The project describes itself as "optimized for running on low-resource servers (especially on Raspberry Pi)." That is the target audience: someone with a Pi, an external drive, and a few hundred gigabytes of JPEGs who does not want to run a Postgres instance and a machine-learning pipeline just to look at holiday pictures. The README lists "Fast: Optimized for low-end hardware" and "Simple: Point to your photos and you are ready" as the first two features. Both claims are about the same thing: avoiding work at browse time that a bigger server would absorb.
The read-only property is the third leg. The README states plainly that "Your photo folder is never modified." For anyone who has watched a gallery tool reorganise files during an import, that sentence is the whole pitch.
Directory-first as an architecture decision, not a slogan
The phrase "directory-first" appears in the project description and the feature list, so it is fair to treat it as the organising principle rather than a marketing line. The practical consequence is that the filesystem is the index. There is no separate catalogue that can drift out of sync with the disk, because the disk is what gets read.
PiGallery2 is written in TypeScript and ships an Angular front end, going by the repository's own topic tags (angular2, node-js, photo-gallery). The README does not describe the internal data flow, so anything beyond that would be guesswork. What can be said from the supplied material is the shape of the deployment: a Node process serving a web UI, pointed at one or more photo directories, with the tree exposed as navigation.
The trade-off is worth naming. A directory-first design inherits whatever discipline you have. Tags, ratings, and albums that live only inside the application have no obvious home in a system whose stated model is the folder tree. If you have spent years curating a flat tag-based library in something else, PiGallery2 will show you a wall of files, not your carefully built taxonomy. The README does not claim otherwise.
Getting it running: Docker is the supported path
The README is unusually direct about installation. Under Getting Started it says the "official and recommended way to run PiGallery2 is using Docker," and links to a Docker setup page on the documentation site. Native installation is listed as "possible for users familiar with Node.js but is not officially supported."
That word, unsupported, matters. If you install from source and something breaks, the project's own framing puts you outside the supported configuration. For a Pi deployment, the Docker route is also the one that avoids arguing with Node version managers on ARM.
The README does not reproduce the docker run command, the image name, or the environment variables in the material provided here. Rather than invent them, the honest answer is: the exact flags live on the linked setup page at bpatrik.github.io/pigallery2/setup/docker, and the configuration keys are documented separately under the Configuration Guide. The README points to both, plus a User Rights page, which suggests permissions are configured rather than assumed.
There is a live demo at pigallery2.onrender.com. The README warns that the "First load may take up to 60s while the server boots up." That delay is a property of the free hosting tier the demo runs on, not of PiGallery2 itself, but it is useful as a smoke test of the UI before you commit to a deployment.
Where the read-only guarantee becomes a limitation
Read-only is a feature until it is not. If you want to rotate a photo, fix a wrong date, or write star ratings back into EXIF, PiGallery2's stated design says no. The README presents this as a safety property, and for a family archive on a Pi that is the right call. But it means any metadata you care about has to be maintained outside the gallery, with a separate tool, and then re-read.
The second limitation is the directory model itself. A folder tree is a single hierarchy. A photo of a child at a wedding belongs in two places, and a directory-first gallery cannot express that without duplicating the file. Applications built around tags or a database handle many-to-many relationships naturally; PiGallery2 does not, because it is not built that way.
Third, the README gives no performance figures, no supported file-format list, and no statement about how video files are handled. The word "Fast" appears twice without a number attached. For a project whose central claim is speed on weak hardware, that is a gap. Anyone with a large library should treat the live demo as a UI preview only, since it will not tell you how the software behaves against your own disk.
How PiGallery2 differs from a database-backed gallery
The clearest comparison is with galleries that ingest photos into an application-managed library. Those tools typically offer face grouping, object search, and duplicate detection, because they build a persistent index they can query. The cost is an import step, a database to back up, and a second copy of your organisational effort living somewhere other than the filesystem.
PiGallery2 inverts every one of those. No import step is described. No database is mentioned in the README. The folder tree is the interface. You give up the query power that a real index buys, and in exchange you get a deployment that fits on a Pi and a guarantee that the tool cannot touch your originals.
This is a genuine fork in the road rather than a quality difference. If your question is "which photo contains a beach," PiGallery2 is the wrong shape of tool. If your question is "show me the folder I made last summer," it is exactly the right one, and the absence of an index is why it can run where heavier galleries cannot.
Maintenance, releases, and what the MIT licence implies
The repository is not archived, the default branch is master, and the most recent push recorded here is 2026-08-25. Recent releases run 3.0.1, 3.1.0, and 3.5.2, with the newest dated 2026-01-24. That cadence suggests active work, though the README does not describe an upgrade procedure or a migration path between major versions. Version 3.0.1 to 3.5.2 spans several minor bumps, and without release notes in the supplied material, it is not possible to say whether configuration keys changed along the way.
Licensing is MIT. In plain terms, that is a permissive licence: you can use, modify, and redistribute the code, including in commercial settings, provided the licence text and copyright notice are preserved. That is a description of the licence, not legal advice, and anyone embedding PiGallery2 in a product should read the LICENSE file in the repository themselves.
The practical maintenance cost of a directory-first design is low by construction: there is no index to rebuild and no database to back up. The main ongoing work is keeping the Docker image current and re-checking the Configuration Guide when you cross a major version.
Who should run it, and what to confirm first
PiGallery2 fits a specific person: someone with a photo folder they already maintain, a small always-on machine, and no interest in a managed library. The read-only guarantee means a misconfiguration cannot destroy the archive, which is the property that makes it reasonable to hand the URL to family members.
It does not fit anyone who needs search by content, automatic face grouping, or metadata editing through the web interface. Those are not gaps in the documentation; they are consequences of the directory-first, read-only design the README states up front.
Before deploying, check three things against the project's own documentation. First, the Configuration Guide, to see which environment variables the Docker image expects, since the README does not list them. Second, the User Rights page, because the README links it separately and that implies access control is something you configure rather than something that is on by default. Third, the live demo, to confirm the interface suits you; the README's own note that the first load can take up to 60 seconds is a hosting artefact, but it is the fastest way to see the UI without touching your own hardware.
Editorial conclusion
Adopt PiGallery2 if your photos already live in a folder tree you maintain by hand and the host is a Raspberry Pi or a small VPS, because the read-only guarantee means the worst case is a broken web front end, not a damaged library. Do not adopt it if you need face recognition, semantic search, or write-back editing of metadata, since the project describes itself as read-only and directory-first. Before committing, open the live demo at pigallery2.onrender.com and confirm the first-load delay is acceptable, then check the user rights page in the docs to see whether the permission model covers the accounts you plan to create.
Community notes