# Ampache: a self-hosted music and video server that expects you to have your files in order

> Ampache is a PHP web application that streams an existing music and video collection to browsers and API clients. It is a presentation layer for tagged files, not a media organiser, and the current develop branch is Ampache8.

**ampache/ampache** — A web based audio/video streaming application and file manager allowing you to access your music & videos from anywhere, using almost any internet enabled device.

- Repository: https://github.com/ampache/ampache
- Website: http://ampache.org
- Stars: 3,831 · Forks: 610
- Language: PHP
- License: AGPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/ampache-ampache

## What Ampache actually does, and who it is built for

Ampache is a web based audio and video streaming application and file manager. You point it at a collection you already own, it reads the embedded tags and file names, and it serves that collection back to you over HTTP through a browser or one of the API clients. The README is unusually direct about the division of labour: Ampache "is not a media organiser; it is meant to be a tool which presents an already organised collection in a useful way." That sentence should decide whether you keep reading.

If your library is a folder of files named track01.mp3 with no tags, Ampache will show you track01.mp3. The project assumes you know how you want your files arranged and that you have already chosen a tool to do it. The audience is therefore people who have done that work: someone with a tagged library on a home server, a NAS or a VPS who wants remote access without uploading anything to a streaming service. It is also aimed at administrators, because someone has to run the PHP stack, the database and the catalog scans.

Ampache has been around long enough that its client ecosystem is part of the pitch. The README links to Power Ampache 2, ample, the python3-ampache client and helper scripts, and the API is documented separately with examples. The develop branch adds a new, opt-in Jellyfin-compatible API so third-party Jellyfin clients (the README names Finamp, Symfonium and gelly) can browse and stream the library. That is a meaningful change: it means an existing Jellyfin client can talk to Ampache without a dedicated Ampache app.

## Two branches, two PHP versions, and why the choice matters

The single most important decision before installing anything is which branch you run. The README states that the recommended and most stable version is the current stable release7 branch, and that the develop branch is the in-progress Ampache8. The develop branch, which is the repository default, carries the newest changes and fixes but may be unstable, and it requires PHP 8.5 or higher. Ampache8 supports php8.5+ only, and the README calls the structural changes in progress.

The version table in the README maps releases to PHP versions, and it is worth reading as a compatibility contract rather than a suggestion. Ampache 6.0.0 through Ampache7 wants PHP 8.2; 6.2.0 onward wants 8.3; 7.1.0 onward wants 8.4; 7.9.0 and higher wants 8.5. Older lines are documented too, down to PHP 7.1-7.4 for Ampache4. If your distribution ships an older PHP, you are not choosing a version of Ampache, you are choosing which line you can run at all.

The module list is the other constraint. Required extensions include curl, dom, fileinfo, gd, gettext, hash, iconv, intl, json, libxml, mbstring, openssl, PDO, PDO_MYSQL, session, simplexml, xml, zip and zlib. Two of these are called out with links to troubleshooting pages: fileinfo is required in Ampache 8.0.0 and higher, and zip is required in Ampache 7.0.0 and higher. Optional modules degrade specific features rather than blocking the install: http for the Yourls plugin, ldap for LDAP authentication, sockets and xmlreader for UPnP. An admin can confirm what the server actually has under Admin -> Server Config -> Ampache Debug, in the PHP Modules table.

There is a front-end toolchain requirement that catches people out. Node.js ^20.19.0 or >=22.12.0, plus the npm that ships with it, is required in Ampache 7.0.0 and higher. The README attributes the constraint to Vite, which builds the front-end assets, and warns that an older Node fails at npm run build. On FreeBSD the README lists php-xml, php-dom, php-intl and php-zip as modules that must be loaded.

## Installing Ampache from the wiki or from Docker

The README does not walk through installation itself. It points to the wiki installation guide and then to the basic config guide, which is where the actual steps live. What the repository does provide is a docker-compose.yml at the top level, and that is the fastest way to see Ampache running.

The compose file defines two services. The ampache service builds from docker/Dockerfilephp85 and maps host port 8084 to container port 80, so after starting it you reach the app at http://localhost:8084. The db service uses the mariadb:lts image and exposes 3306 on the host so you can connect with an external database tool. Media is mounted from ./docker/media on the host to /media in the container, and the comment in the file says to add a catalog pointing at /media in Ampache.

Start it with:

```bash
docker compose up -d
```

The environment block controls first-run behaviour. DB_HOST, DB_PORT, DB_NAME, DB_USER and DB_PASSWORD are the admin credentials used to create the schema, while AMPACHE_DB_USER and AMPACHE_DB_PASSWORD are the application credentials written into config/ampache.cfg.php. The comment is explicit that leaving DB_NAME empty skips auto-install and sends you to the web installer instead. An optional first-run admin account is created unless you omit AMPACHE_ADMIN_USER.

```yaml
environment:
  DB_NAME: ${DB_NAME-ampache}
  DB_USER: ${DB_USER-root}
  DB_PASSWORD: ${DB_PASSWORD-ampache}
  AMPACHE_DB_USER: ${AMPACHE_DB_USER-ampache}
  AMPACHE_DB_PASSWORD: ${AMPACHE_DB_PASSWORD-ampache}
```

Once the container is healthy, log in with the admin account, then add a catalog. That is the step that makes Ampache useful: a catalog is the mapping between a path on disk and the library Ampache indexes. Point it at /media, run the catalog update, and the files appear. If nothing appears, the problem is almost always metadata or the path, not the streaming layer.

## Where Ampache breaks down

The dependency on correct metadata is the failure mode the project itself names. Ampache's usefulness is "heavily dependent on being able to extract correct metadata from embedded tags in your files and/or the file name." A library of untagged files produces a library of unlabelled rows, and no amount of configuration fixes that, because the fix belongs upstream in a tagging tool.

The branch situation is a second, structural limitation. The repository default branch is develop, which the README describes as in-progress Ampache8 that may be unstable and requires PHP 8.5 or higher. Anyone who clones the default branch expecting the stable product is running the development line. The stable option, release7, is a separate branch, and release6 is still available for older installations. That split also means documentation is versioned: the README links separate Ampache 8 for Admins and Ampache 8 for Users pages, and notes that Ampache 7 for Admins still applies to the older line.

The upgrade path is deliberately manual. The README recommends moving the old directory out of the way, extracting the new copy in its place, and then copying back /config/ampache.cfg.php, /rest/.htaccess and /play/.htaccess if they exist. Database updates are handled by Ampache itself. That is a reasonable procedure for a self-hoster, but it is not a package-managed upgrade, and it means the configuration file you carry forward is the thing most likely to need attention after a major version change. The README does not document rollback.

Finally, Ampache is the wrong tool if you want transcoding-on-the-fly decisions made for you, or if you have no intention of running a web server, PHP and MySQL. The requirement list is long and the project does not pretend otherwise.

## Ampache compared with Navidrome and Subsonic-style servers

The comparison people reach for is with Navidrome, and the difference in approach is architectural rather than cosmetic. Navidrome is a single Go binary that speaks the Subsonic API, which is why so many mobile clients work with it out of the box. Ampache is a PHP application on top of MySQL or MariaDB, served by Apache, lighttpd, nginx or IIS, with a front-end asset pipeline built by Vite and npm. The README says Ampache receives the most testing with Apache. If your deployment model is one binary and a config file, Ampache is on the other side of that line.

What Ampache offers in exchange is a long-lived, broad feature surface: a web interface with themes, plugins, LDAP authentication, UPnP, an API documented with examples, and translations managed through Transifex. The README lists several clients built around it, including Power Ampache 2, ample and python3-ampache. The new opt-in Jellyfin-compatible API on develop is a notable move in the other direction, borrowing compatibility from a different ecosystem so that Jellyfin clients can browse and stream an Ampache library. Navidrome's Subsonic compatibility and Ampache's Jellyfin compatibility are both attempts to meet clients where they already are, just with different protocols.

Subsonic is the other name that comes up, and the distinction is similar: Subsonic-style servers tend to be judged on API compatibility with the client apps that speak that protocol, while Ampache is judged on its own web interface, its catalog management and its API. If your priority is the smallest possible footprint, Ampache is not that. If your priority is a mature PHP application with a web UI, plugin hooks and a documented API you can script against, the trade-off goes the other way.

## Licence, upgrade cost and what maintenance looks like

Ampache is licensed under the GNU Affero General Public License v3 or later. The AGPL matters for anyone embedding it in a service: if you modify Ampache and let users interact with it over a network, the licence's network clause is the part to read, and that is a question for your own legal review rather than something this article can settle. The README also notes that Ampache includes external modules listed in composer.lock that carry their own licensing, so the dependency tree is not uniformly AGPL.

The maintenance picture is active. The last push to the repository was on 2026-09-18, and recent releases include 8.1.0 on 2026-09-11, 8.0.1 on 2026-08-17 and 7.10.3 on 2026-09-15. Note that releases are being cut on both lines: 7.10.3 is the release7 series and 8.1.0 and 8.0.1 are the Ampache8 series. Running stable means tracking one of those, not both.

The upgrade cost is dominated by the PHP version treadmill. Each major line moves the minimum PHP version, and the front-end build needs Node.js ^20.19.0 or >=22.12.0. On a distribution with a slow PHP cadence, staying on a supported Ampache line may mean running a PHP version your package manager does not ship. Budget for that before you migrate a working install.

## Conclusion

Adopt Ampache if you already have a curated, tagged library and want a PHP web front end with a documented API and a Jellyfin-compatible endpoint on the develop branch. Do not adopt it if you want software to fix messy tags or rename files, because the README states plainly that Ampache is not a media organiser. Before committing, check the PHP version your chosen branch requires, confirm the required modules including fileinfo and zip are loaded, and decide whether you are running the stable release7 line or the in-progress Ampache8 develop branch.

## FAQ

### How do I install Ampache?

The README points to the wiki installation guide and the basic config guide rather than listing steps itself. The repository also ships a docker-compose.yml that builds from docker/Dockerfilephp85 and serves the app on host port 8084.

### How do I use Ampache?

You point Ampache at an already organised, tagged collection, add a catalog for the path where the media lives, and then browse or stream it through the web interface or an API client. The README is explicit that Ampache is not a media organiser and depends on reading correct metadata from tags or file names.

### How does Ampache compare with Jellyfin?

The README does not compare the two products directly. It does state that the develop branch adds a new, opt-in Jellyfin-compatible API, which lets third-party Jellyfin clients such as Finamp, Symfonium and gelly browse and stream an Ampache library.

### What are alternatives to Ampache?

The README does not name alternatives. It does describe the shape of the project: a PHP web application on MySQL or MariaDB, served by Apache, lighttpd, nginx or IIS, with a Vite and npm front-end build, which is a different deployment model from a single-binary server.

## Sources

- [ampache/ampache on GitHub](https://github.com/ampache/ampache)
- [License: AGPL-3.0](https://github.com/ampache/ampache/blob/develop/LICENSE)
- [Project website](http://ampache.org)
- [README](https://github.com/ampache/ampache/blob/develop/README.md)
- [Releases](https://github.com/ampache/ampache/releases)

---

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