# Piwigo: a self-hosted PHP photo gallery for organisations that outgrow folder trees

> Piwigo is GPL-2.0 photo gallery software written in PHP, aimed at organisations, teams and individuals who want their library on their own server. Here is how it installs, how its album and plugin model works, and where it stops being the right tool.

**Piwigo/Piwigo** — Manage your photos with Piwigo, a full featured open source photo gallery application for the web. Star us on Github! More than 200 plugins and themes available. Join us and contribute!

- Repository: https://github.com/Piwigo/Piwigo
- Website: https://piwigo.org
- Stars: 3,865 · Forks: 487
- Language: PHP
- License: GPL-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/piwigo-piwigo

## What Piwigo actually solves, and for whom

The README describes Piwigo as "open source photo gallery software for the web. Designed for organisations, teams and individuals." That wording is the whole positioning. This is not a desktop catalogue and not a sync client. It is a web application you put on a server, and the people who need it are the ones who have to give other people access to a shared library without handing over a cloud account.

The problem it addresses is narrower than "manage photos". A school wants parents to see the sports day album and nothing else. A club wants members to upload to one album and browse the rest. An agency wants a client to download a selection without seeing the other clients. Piwigo's answer is a server-side gallery with user accounts, albums and tags, plus more than 200 plugins and themes according to the README. The repository layout supports that claim: plugins/, themes/, language/ and template-extension/ sit at the top level, so extension points are part of the shipped tree rather than bolted on.

If your actual need is a private folder of RAW files on your own laptop, this is more machinery than the problem deserves. If your need is a URL you can send to thirty people with different levels of access, it is the right shape.

## Albums, tags and the PHP request path

The architecture is a classic PHP application. The top-level entries tell most of the story: index.php, picture.php, search.php, tags.php, comments.php and identification.php are separate entry points, each handling one kind of request. There is no single front controller routing everything. admin/ handles the administration area, include/ holds shared code, and ws.php exposes a web service endpoint for programmatic access. install/ and upgrade.php are separate concerns, which matters later.

Storage is split. The galleries/ directory is where image files live, and local/ holds installation-specific configuration, which is why both appear in .gitignore territory rather than being part of the distributed code. Metadata, users, album structure and permissions live in MySQL or MariaDB. That split is the important design decision: the database is the catalogue, the filesystem is the payload. Backing up one without the other gives you a gallery that either has no pictures or no idea what they are.

Album organisation is hierarchical and separate from tags, and both are queryable. search.php and qsearch.php exist as distinct entry points, so quick search and full search are different code paths. Images are processed through i.php, with ImageMagick recommended and PHP GD as the fallback. The README is explicit that ImageMagick is the recommended option, and the practical consequence is that GD will handle fewer formats and, in most deployments, do less with what it handles.

## Installing Piwigo and getting a first album online

The README gives two routes. The manual route is: download the latest stable version, unzip it, transfer everything to your web space with any FTP client, then open the site and follow the steps. The Docker route is delegated to a separate installation guide on doc.piwigo.org, so the README itself does not list image names, ports or volume mounts. Do not expect to find them here.

For the manual route, the requirements are fixed: a webserver (Apache or nginx recommended), PHP 7.4 or newer, MySQL 5 or greater or a MariaDB equivalent, and ImageMagick or PHP GD. The README notes that Piwigo can run on PHP 7.0+, but states those end-of-life versions are no longer maintained and may expose your site to security vulnerabilities. Treat 7.4 as the floor, not a suggestion.

After the files are in place, the installer is a browser flow. The repository ships install.php and the install/ directory, and the README's instruction is simply to open your website and follow the steps.

```bash
# after uploading the unzipped release to your web root
# open the installer in a browser, for example:
# http://example.com/piwigo
```

The installer will ask for database credentials and an administrator account. Once it completes, the first real task is getting pictures in. The README does not document the upload UI, but the repository shows galleries/ as the image directory, and the administration area is reached through admin.php. The practical first use is: create an album in the admin area, upload a handful of files, then open picture.php for one of them to confirm that image processing is working. If thumbnails fail to generate, the cause is almost always the ImageMagick or GD requirement rather than the upload itself.

For a server-based install, the standard shape is a webserver document root pointing at the Piwigo directory, a MySQL database created beforehand, and write access for the web server user to galleries/ and local/. The README does not spell out file permissions, so verify them yourself before blaming the installer.

## Where Piwigo is the wrong choice

The dependency stack is the first limitation, and it is not negotiable. PHP plus MySQL or MariaDB plus a webserver is a heavier operational footprint than a single binary that reads a directory. If you wanted to point a container at a folder of photos and be done, Piwigo is not that, and the README's Docker section points elsewhere precisely because the container still wraps this stack.

The second limitation is the split between database and filesystem. Because the catalogue lives in MySQL and the images live in galleries/, restoring one without the other produces a broken gallery. The README does not document a backup procedure, and it does not document rollback for upgrades either. The repository ships upgrade.php and upgrade_feed.php, which tells you upgrades are a first-class operation, but the documentation gives no recovery path if one fails partway. Take your own database dump and file copy before running an upgrade.

Third, this is a web gallery, not an asset manager for video. The topics list mentions photography and image galleries; nothing in the repository describes video transcoding or a media pipeline. If your library is mostly video, the image-processing path through i.php and ImageMagick is not the mechanism you need.

Finally, the README is thin on operational detail. Requirements and install steps are there. Permissions, backup, rollback, scaling and caching are not. That is a documentation gap, not a defect in the software, but it shifts the operational burden onto you.

## Piwigo compared with PhotoPrism and Immich

The comparison people actually search for is Piwigo against PhotoPrism or Immich, and the difference is architectural rather than cosmetic.

PhotoPrism and Immich are the two names that come up alongside Piwigo in search data, and both approach the problem from a different direction: they index a library, typically from a mounted directory, and lean on machine learning for classification and search. Piwigo's catalogue is explicit. You create albums and apply tags, and access is governed by user accounts and album permissions. The database is authoritative and the structure is something you build.

That makes Piwigo the better fit when the requirement is governance rather than discovery. Per-album permissions for different audiences, a plugin directory the README puts at more than 200 entries, and themes and language packs shipped in the repository are all aimed at running a gallery other people use. It is the weaker fit when the requirement is automatic organisation of a large unsorted library, because nothing in the repository describes automatic classification.

Immich in particular is usually discussed as a phone-photo backup target. Piwigo's README does not describe a mobile sync client, so that comparison is not one the project itself invites. The honest framing: Piwigo is a publishing and permissions system for a curated library; the others are indexing systems for a growing one. Which you want depends on whether the hard part is who can see what, or finding things you never filed.

## Licence, maintenance and the cost of upgrading

Piwigo is released under GPL v2, per the README, with COPYING.txt and LICENSE.txt both present at the top level. The practical implication for most adopters is that self-hosting and modification are permitted under the licence terms, and that if you distribute a modified version you inherit obligations. Plugins and themes are separate works with their own licensing, and the README does not state what those are, so check each one before shipping a modified gallery to anyone else. This is a description of the licence text, not legal advice.

Maintenance looks current. The last push to the default branch was on 2026-09-01, and the most recent release listed is 16.4.0 from 2026-05-03, following 16.3.0 in February and 16.2.0 in December. That is a steady release cadence across the listed window, and the repository is not archived.

The upgrade cost is the part worth planning for. Piwigo ships upgrade.php as a distinct entry point, so upgrading is a runnable operation rather than a redeploy. But the README does not document rollback, and because the catalogue lives in MySQL while the images live in galleries/, an upgrade that changes schema is not something you can undo by restoring the code directory alone. Budget for a database dump taken immediately before upgrade.php runs. If you run plugins, note that the README does not describe plugin compatibility guarantees across major versions, so a major upgrade is the moment to check each one.

## Conclusion

Adopt Piwigo if you already run PHP and MySQL and want albums, tags, user groups and per-album permissions on hardware you control, with a plugin directory to extend it. Do not adopt it if you want a single-binary container with no database, or if your library is video-first. Before committing, verify on your own host that PHP 7.4 or newer and MySQL 5 or MariaDB are available, that ImageMagick is installed rather than falling back to PHP GD, and that your intended upload path works, because the README does not document rollback if an upgrade goes wrong.

## FAQ

### What is Piwigo?

Piwigo is open source photo gallery software for the web, written in PHP and released under GPL v2. The README describes it as designed for organisations, teams and individuals, and the repository ships plugins, themes and language packs alongside the core application.

### How do I manually install Piwigo?

Download the latest stable version and unzip it, transfer everything to your web space with any FTP client, then open your website and follow the steps. The README links to a more detailed manual install guide on doc.piwigo.org.

### How do I install Piwigo with Docker?

The README does not give Docker commands itself. It points to a separate installation guide with Docker on doc.piwigo.org, so the image name, ports and volume configuration have to come from that guide.

### Is Piwigo free?

Yes. The README states Piwigo is released under the GPL v2 license, with copying details in COPYING.txt in the repository. The README also mentions a hosted Piwigo Cloud option on piwigo.org for people who do not have their own server.

### What are Piwigo's server requirements?

A webserver (Apache or nginx recommended), PHP 7.4 or newer, MySQL 5 or greater or a MariaDB equivalent, and ImageMagick (recommended) or PHP GD. The README notes Piwigo can run on PHP 7.0+ but says those end-of-life versions are no longer maintained and may expose your site to security vulnerabilities.

### What is the difference between Piwigo and PhotoPrism?

Piwigo's catalogue is explicit: you build albums and tags, and access is governed by user accounts and album permissions stored in MySQL, with images in the galleries/ directory. Nothing in the repository describes automatic classification or machine-learning search in Piwigo, so it is aimed at curating and publishing a library rather than indexing an unsorted one.

## Sources

- [License: GPL-2.0](https://github.com/Piwigo/Piwigo/blob/master/LICENSE)
- [Piwigo/Piwigo on GitHub](https://github.com/Piwigo/Piwigo)
- [Project website](https://piwigo.org)
- [README](https://github.com/Piwigo/Piwigo/blob/master/README.md)
- [Releases](https://github.com/Piwigo/Piwigo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/piwigo-piwigo