# Directory Lister: PHP folder browsing with a one-minute install

> Directory Lister exposes a web-accessible folder as a browsable, searchable page. It is a public file-sharing tool with a deliberately small feature set, and the README's warning about sensitive files is the first thing to read.

**DirectoryLister/DirectoryLister** — 📂 Directory Lister is the easiest way to expose the contents of any web-accessible folder for browsing and sharing.

- Repository: https://github.com/DirectoryLister/DirectoryLister
- Website: https://www.directorylister.com
- Stars: 2,534 · Forks: 518
- Language: PHP
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/directorylister-directorylister

## The problem Directory Lister solves, and the audience it assumes

A web server can already serve a plain directory index, but the default Apache or nginx listing is ugly, has no search, no sorting controls and no download bundling. Directory Lister replaces that listing with a themed page that shows the contents of a folder, and the README describes it as "the easiest way to expose the contents of any web-accessible folder for browsing and sharing." The target user is someone who already has files sitting in a directory that the web server can reach: release artifacts, documentation, media, a shared drop of documents. The project assumes the operator wants those files public, not gated. The README's warning is explicit: "DO NOT USE DIRECTORY LISTER TO HOST PRIVATE OR SENSITIVE FILES!" and it notes that hidden files inside the configured files path are publicly accessible too. That single constraint defines the audience more sharply than any feature list. If you need authentication, signed URLs or per-user permissions, this is the wrong product, and the README does not claim otherwise. What it does claim is speed of setup: a "zero configuration, drag-and-drop installation" that the README says puts you up and running in less than a minute. The feature set backs that up. Light and dark themes, custom sort ordering, file search, file hashes for download verification, README rendering, zip downloads for a whole directory, and multi-lingual support. Each of those is a display or convenience feature. None of them is an access-control feature.

## How the PHP application and its assets fit together

The repository layout makes the architecture legible. index.php sits at the top level as the entry point, app/ holds the application code, and the front end is built rather than hand-written: package.json lists Alpine.js, axios and highlight.js as runtime dependencies, with Tailwind CSS 4 and Vite 8 in devDependencies. Two scripts matter. "dev" runs vite, and "build" runs vite build, producing the assets the page loads. The Dockerfile confirms the two-stage shape: a base image on php:8.5-apache with the zip extension installed through docker-php-ext-install, plus apcu, memcached and redis installed through pecl and enabled with docker-php-ext-enable. A build stage runs composer install with --no-dev and --optimize-autoloader, then npm install --no-save && npm run build && npm prune --production, then make production. The prod stage copies the built tree and sets FILES_PATH=/data. So the data flow is: Apache serves index.php, the application reads the directory named by FILES_PATH, and the built JavaScript handles search, sorting and theme switching in the browser. The optional infrastructure is worth noting. The compose file declares memcached and redis services alongside the app, and the Dockerfile installs both extensions, which tells you the application is built to talk to a cache backend rather than recomputing directory metadata on every request. The README does not spell out what gets cached or when the cache is invalidated, so if you run this against a directory that changes constantly, that is a question to answer from the configuration documentation rather than from the README.

## Installing Directory Lister and getting a first listing on screen

There are two documented paths. The README points at a separate repository, Directory Lister Compose, for Docker Compose management, and gives a manual route otherwise: download the archive from directorylister.com, extract it, and copy the extracted files and folders to your web server. Configuration is a single step, and the README states it plainly: copy .env.example to .env, then edit the configuration values in .env. The example file is short and worth reading in full before you change anything.

```bash
cp .env.example .env
```

What you should see is a .env containing APP_DEBUG, APP_LANGUAGE, a commented-out FILES_PATH, DISPLAY_READMES, READMES_FIRST, ZIP_DOWNLOADS, SORT_ORDER and REVERSE_SORT. The defaults are conservative: debug off, language en, readmes displayed but not first, zip downloads on, sort by type, no reverse sort. To point the application at your own folder, uncomment FILES_PATH and set it to a path on the server.

```bash
FILES_PATH=/data
```

After that, load index.php in a browser. The documentation states that PHP 8.2 or newer is required, and that the Zip extension is needed for zip downloads while the DOM and Fileinfo extensions are needed for README rendering. If you skip those extensions, you lose the corresponding feature rather than the whole page. For a container-based first run, the README points at the Directory Lister Compose repository, and this repository's own docker-compose.yaml defines the app service, which maps port 80 on the container to the host port named by APP_PORT.

```yaml
services:
  app:
    ports:
      - ${APP_PORT:-80}:80
```

The compose file also defines a memcached service on 11211 and a redis service on 6379, both overridable through MEMCACHED_PORT and REDIS_PORT, and a separate npm service that runs npm run dev for front-end work. If you are only deploying, you do not need that service. One practical note from the Dockerfile: the production image sets FILES_PATH=/data, so a container deployment puts your files there unless you override it.

## The public-by-design constraint is the real limitation

Most directory browsers are framed around access control. This one is framed around exposure, and the README says so in a warning block rather than a footnote. Files within the configured files path, including hidden files, will be publicly accessible. That is not a bug to be worked around; it is the design. The consequences are concrete. A stray .env, a .git directory, a backup file with a predictable name, or a database dump left in the folder will be listed and downloadable. The application does not appear to filter by extension or by name pattern, and the README documents no exclusion list. The second limitation is the front end. The page depends on a Vite build producing JavaScript assets, and package.json shows Alpine.js, axios and highlight.js as runtime dependencies. That means the browsing experience is a JavaScript application, not a static HTML directory index. Anyone with scripting disabled, or any crawler that does not execute JavaScript, sees less than a browser does. The README does not describe a no-JavaScript fallback. Third, the caching story is only half-visible. Redis and memcached are wired into the image and the compose file, but the README does not describe cache invalidation, so a directory that changes frequently may behave in ways you have to test yourself. Finally, the maintenance picture is straightforward: the last push was on 2026-09-08, and the most recent release is 5.7.0 from the same day, following 5.6.1 in July 2026 and 5.5.2 in June 2026. That is a steady release cadence, and the repository is not archived.

## Alternatives and where the approach differs

The obvious alternative is the directory index your web server already produces. Apache's mod_autoindex and nginx's autoindex module both list a folder with zero application code, zero PHP requirement and zero build step. The difference is everything above the listing: no search box, no theme, no file hashes, no zip download of a whole directory, no README rendering. If all you want is a list of filenames with links, the web server wins on operational cost, because there is nothing to update. If you want the browsing experience, Directory Lister is the layer that adds it. A second alternative is a general file-sharing or cloud-storage service. Those typically add accounts, permissions and expiring links, which Directory Lister does not have and does not pretend to have. The trade is the reverse of the usual one: you give up access control and get a self-hosted, MIT-licensed PHP application that you drop into a folder. The related searches that people run against this project include phrases like "Directory Lister Pro" and "FilelistCreator". Neither appears anywhere in the README or the repository files, so there is nothing here to compare against them. The honest comparison set is narrow: a plain autoindex, or a file-sharing service with permissions. Directory Lister sits in the gap between them, and the gap is defined by the assumption that the files are meant to be public.

## Licence, upgrade cost and what a version bump involves

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the standard permissive arrangement, and it carries no copyleft obligation on your own code. It also means no warranty, and the README's warning about public exposure is an operator responsibility, not something the licence or the maintainer enforces. This is not legal advice; read the LICENSE file in the repository before relying on it for a commercial deployment. Upgrade cost is where the two installation paths diverge. The manual route means replacing the extracted files on your web server and re-checking your .env against the current .env.example, since configuration keys can be added between releases. The container route means pulling a new image tag and restarting, with your files mounted rather than baked in. Either way, the front end is prebuilt in the production image, so you do not need Node on the server unless you are building assets yourself. The release history shows why this matters: three releases between June and September 2026, which is frequent enough that a pinned version will fall behind within a quarter. If you deploy the manual way, keep the archive you replaced so a rollback is a file copy. The README does not document a rollback procedure, so that habit is yours to establish.

## Conclusion

Adopt Directory Lister when you need a public, read-only view of a folder of files and you want it running in minutes: PHP 8.2 or newer, a web server, and a copied .env.example. Do not adopt it for private or sensitive files, because the README states that everything inside the configured files path, hidden files included, is publicly accessible. Before deploying, verify that FILES_PATH points only at a directory you are willing to publish, and confirm the Zip extension is loaded if you want the zip download feature.

## FAQ

### How do I use Directory Lister to browse a folder?

Download and extract the archive, copy the files to your web server, then copy .env.example to .env and edit the configuration values. Loading index.php in a browser shows the listing. The README states that PHP 8.2 or newer is required.

### What are the alternatives to Directory Lister?

The closest alternative is the directory index your web server already produces through Apache mod_autoindex or nginx autoindex, which lists files with no application code but has no search, themes, hashes or zip downloads. A file-sharing service with accounts and permissions is the other direction, and it covers the access control Directory Lister deliberately omits.

### Can I run Directory Lister with Docker?

Yes. The README points to the separate Directory Lister Compose repository for Docker Compose management, and the repository includes a Dockerfile plus a docker-compose.yaml that maps the app on port 80 by default and defines memcached and redis services. The production image sets FILES_PATH=/data.

### Is Directory Lister safe for private files?

No. The README carries an explicit warning not to use it for private or sensitive files, and states that files within the configured files path, including hidden files, will be publicly accessible. It is designed for public file sharing only.

### What PHP version and extensions does Directory Lister need?

PHP 8.2 or newer. The Zip extension is required for zip downloads, and the DOM and Fileinfo extensions are required for README rendering. Missing extensions remove those features rather than preventing the page from loading.

## Sources

- [DirectoryLister/DirectoryLister on GitHub](https://github.com/DirectoryLister/DirectoryLister)
- [License: MIT](https://github.com/DirectoryLister/DirectoryLister/blob/master/LICENSE)
- [Project website](https://www.directorylister.com)
- [README](https://github.com/DirectoryLister/DirectoryLister/blob/master/README.md)
- [Releases](https://github.com/DirectoryLister/DirectoryLister/releases)

---

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