Skip to content
Get packs

Guide · Open source

How to use FrankenPHP: install, serve a PHP app and run with Docker

Updated · written with AI from the project's own documentation and checked against our catalogue data

FrankenPHP is an application server for PHP, built on the Caddy web server. It can serve PHP websites and apps with HTTPS handled for you, and it can also be used as a Go library. This guide shows you how to install it, serve a PHP directory, run it with Docker, and find the next steps for worker mode and framework integrations.

FrankenPHPphp/frankenphp · ★ 11.5k · MIT

Quick start

  1. 1Install FrankenPHP. Run the install script for your platform, or install with Homebrew using brew install dunglas/frankenphp/frankenphp.
  2. 2Open your project folder. Change into the directory that contains your PHP files.
  3. 3Start the server. Run frankenphp php-server to serve the content of the current directory.
  4. 4Open the site over HTTPS. Visit https://localhost and accept the self-signed certificate.
  5. 5Try Docker if preferred. Run the Docker image with port 80, 443 and 443/udp published, mounting your code into /app/public.
  6. 6Read the docs before production. Review worker mode, production guidance and known issues before running critical workloads.

What FrankenPHP is and who it suits

FrankenPHP is a modern application server for PHP built on top of the Caddy web server. It works with any PHP app, and the project lists official integrations for Laravel and Symfony that use its worker mode.

It is server software, so you run and maintain it yourself. It only runs PHP applications, so it is not useful if you have no PHP code to serve.

  • Good fit: PHP developers who want one binary that serves their app with HTTPS included.
  • Good fit: teams that want to run a PHP app without installing a separate web server.
  • Less suited: people who need a fully managed hosting platform.
  • Test first: the README points to a known-issues page, so test thoroughly before critical production use.

Install FrankenPHP on Linux, macOS or Windows

The install script is the quickest route. On Linux and macOS, run the command below in your terminal. It installs an appropriate version for your platform.

On Windows, open PowerShell and run the second command.

  • Standalone binaries are provided for Linux, macOS (Apple Silicon) and Windows.
  • Linux binaries are statically linked, so they should run on any Linux distribution without installing dependencies.
curl https://frankenphp.dev/install.sh | sh irm https://frankenphp.dev/install.ps1 | iex

Install with Homebrew or a Linux package manager

On macOS and Linux you can install FrankenPHP with Homebrew. The maintainers also publish rpm, deb and apk packages for dnf, apt and apk. The deb and rpm packages include a systemd service you can start.

Extensions not available by default can be installed with PIE, as described in the README.

  • Homebrew: use the formula from the dunglas tap.
  • Packages for dnf, apt and apk are provided by the maintainers; follow the commands in the project README for your system.
brew install dunglas/frankenphp/frankenphp

Serve your PHP site with frankenphp php-server

To serve the content of the current directory, change into your project folder and run the command below. You can also run a PHP command-line script with php-cli by giving it the script path.

For the deb and rpm packages, you can start the systemd service instead.

  • Serve a directory: frankenphp php-server
  • Run a CLI script: frankenphp php-cli /path/to/your/script.php
  • Systemd service (deb and rpm packages): sudo systemctl start frankenphp
frankenphp php-server frankenphp php-cli /path/to/your/script.php

Run FrankenPHP with Docker

Docker images are available if you prefer containers. The command mounts the current directory into /app/public, publishes ports 80 and 443, and publishes 443 over UDP for HTTP/3.

Open https://localhost in your browser. Do not use https://127.0.0.1. Accept the self-signed certificate. To change the domain, set the SERVER_NAME environment variable.

  • Use https://localhost, not 127.0.0.1.
  • Change the domain with the SERVER_NAME environment variable.
docker run -v .:/app/public \ -p 80:80 -p 443:443 -p 443:443/udp \ dunglas/frankenphp

Go further: worker mode, migrations and docs

Once your site runs, the official docs cover the features that set FrankenPHP apart. Worker mode keeps the app loaded between requests. Early Hints, real-time (Mercure), hot reloading and automatic HTTPS are also documented.

If you are moving an existing site, the docs include a guide for migrating from Nginx with PHP-FPM, plus integration pages for WordPress, Symfony and Laravel.

  • Worker mode: frankenphp.dev/docs/worker/
  • Migrating from Nginx/PHP-FPM: frankenphp.dev/docs/migrate/
  • Production guidance: frankenphp.dev/docs/production/
  • Known issues: frankenphp.dev/docs/known-issues/

What people use it for

  • Serve a PHP website from one binary with HTTPS included.
  • Run a Laravel or Symfony project with the official worker mode integrations.
  • Run a PHP app without installing a separate web server such as Nginx.
  • Package a PHP app as a standalone executable using the embed docs.
  • Embed PHP in a Go program as a library that uses net/http.

Frequently asked questions

Is FrankenPHP free to use?

FrankenPHP is released under the MIT licence, according to the project information. The source does not cover commercial support or hosted plans.

What do I need to install FrankenPHP?

The project lists no separate prerequisites. You can use the install script, Homebrew, a package manager, or Docker, as shown in the README.

How do I run FrankenPHP with Docker?

Run docker run -v .:/app/public -p 80:80 -p 443:443 -p 443:443/udp dunglas/frankenphp, then open https://localhost and accept the self-signed certificate.

Why does https://127.0.0.1 not work for local testing?

The README says not to use https://127.0.0.1. Use https://localhost instead and accept the self-signed certificate. You can change the domain with the SERVER_NAME environment variable.

How does FrankenPHP compare to Nginx with PHP-FPM?

FrankenPHP is built on Caddy and includes automatic HTTPS, HTTP/2 and HTTP/3, so you do not need a separate web server. The project provides a migration guide from Nginx with PHP-FPM for existing sites.

Can I use FrankenPHP in production?

The README points to a known-issues page and recommends testing before critical production use. Read the production deployment and known-issues docs first.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

FrankenPHP suits PHP developers and small teams who want to serve a PHP app from a single binary with HTTPS included, and it is a strong option for Laravel or Symfony projects that can use worker mode. It is not a managed hosting service, and it is not the right choice if you have no PHP to serve or need a long-proven setup without testing first. Compare it with Nginx with PHP-FPM or Apache if you want a more established stack.

Install options & downloads