VMware Photon OS: a minimal Linux container host for ESXi and cloud images

What Photon OS is for, and who should care

Photon OS is a Linux distribution whose stated purpose is narrower than most: it is a container host. The README describes it as optimized for cloud-native applications, cloud platforms and VMware infrastructure, and it lists the Linux kernel as tuned for performance when Photon OS runs on VMware ESXi. That single sentence explains most of the design decisions downstream. This is not a desktop distribution and not a general purpose server distribution in the Debian or RHEL sense. It is a host you install so that a Docker daemon has somewhere small and predictable to run.

The intended audience follows from that. If your containers already live on vSphere, Photon OS removes a layer of translation: the kernel is tuned for the hypervisor you are paying for, and the image formats match the platforms you deploy to. The README lists ISO, OVA and cloud images including Amazon AMI, Google Cloud GCE image and Azure VHD. That spread matters because it means the same base system can be a VM template in your vSphere cluster and a cloud instance in a public region without you maintaining two build pipelines.

The second audience is people who want lifecycle management to be boring. Photon OS ships the tdnf package manager and the Photon Management Daemon (pmd), and the README frames these together as efficient lifecycle management: easy to manage, patch and update. For a fleet of container hosts, that is the actual daily cost. Nobody enjoys patching a hypervisor guest image by hand, and Photon OS assumes you would rather not.

How the build system works, and why Photon 5 needs two clones

The repository is a build system, not a compiled binary. The top level holds SPECS/, data/, support/, a Makefile and a build-config.json, and the README states that Photon OS 5 now requires the common branch as part of the build system. That is the most consequential change in the 5.0 line for anyone building from source, and it is easy to miss.

The mechanism is visible in the Makefile. It reads build-config.json with jq to obtain the common-branch-path and the stage-path, exports COMMON_BRANCH_PATH, RELEASE_BRANCH_PATH and STAGE_PATH, and then runs the actual build from inside the common branch directory. Every target, including the default, wraps its work in a pushd into the common branch path. In other words, the release branch you cloned is mostly a configuration and specification layer; the Python build driver lives on the common branch and is invoked from there.

The Makefile also enforces a dependency up front. TOOLS is set to jq, and the Makefile checks for each tool with command -v, aborting with a message if it is missing. So jq is not optional tooling you can skip. The default goal is all, and the all target branches three ways: if pkgs is set it builds only those packages, if BUILD_EXTRA_PKGS is 1 it runs the extra-packages target, otherwise it runs the packages target. Pattern targets pass the target name through to build.py as -t. That structure is worth understanding before you file a bug, because a failure in the build driver is a failure on the common branch, not on the branch you cloned first.

Installing Photon OS and running a first container

Photon OS is distributed as prebuilt images rather than installed from a package repository. The README points to a Download Guide in the project wiki for binaries and download links, and states that the images come as ISO, OVA and cloud images such as Amazon AMI, Google Cloud GCE image and Azure VHD. There is no single install command, because the right artifact depends on where you are deploying. On vSphere you would deploy the OVA or boot the ISO; on AWS, GCP or Azure you would launch the corresponding cloud image.

For a local test the README gives an official Vagrant box. The documented command is a single line, and the README notes that some users found the box requires VirtualBox 4.3 or later and suggests checking your version if you hit issues.

vagrant init vmware/photon

After that, bring the box up with the usual Vagrant workflow and you land in a Photon OS guest. The README also points to a Vagrant guest plugin at github.com/vmware/vagrant-guests-photon, which is what makes Photon OS behave properly as a Vagrant guest rather than a generic Linux box.

Once the host is running, the container story is the Docker daemon the README says is included. The README names Docker, Mesos and Kubernetes as the container and orchestration tooling Photon OS works with, so the first real use is to start the daemon and run a container against it, then manage the host itself with tdnf and pmd.

Building your own Photon OS image from source

If you need to build rather than download, the README gives explicit steps, and they involve two clones. First clone the repository itself. Then clone the common branch, which is the same repository checked out at the common branch. Photon 5 will not build without it.

git clone https://github.com/vmware/photon.git
git clone -b common https://github.com/vmware/photon.git common

The path to that second clone is supplied either through build-config.json or as a command-line argument. The README shows the config form as a small JSON object with the key common-branch-path, and notes that by default the build system looks for the common branch at the relative path ../common.

{
"common-branch-path": "../common"
}

The command-line form passes COMMON_BRANCH_PATH to make, as shown in the README. Both end up feeding the same Makefile variable.

make package COMMON_BRANCH_PATH="../common"

One constraint to plan for: the Makefile requires jq to be installed, and it will stop with an error message telling you so if it is not. On a minimal build host, install jq before you run anything.

Where Photon OS is the wrong choice

The clearest limitation is scope. Photon OS is a container host, and the README keeps returning to that framing: secure run-time environment for efficiently running containers, Docker daemon included, works with orchestration frameworks such as Mesos and Kubernetes. If what you actually need is a general purpose Linux server with a deep third-party package ecosystem, Photon OS is the wrong tool, and no amount of tdnf configuration changes that. You would be adopting a small, opinionated base and then fighting it.

The second limitation is the build path. Requiring a second clone of the common branch, plus jq, plus a build-config.json that must point at the right relative path, raises the cost of a source build compared with a project that builds from one checkout. The README documents the requirement but does not document rollback, nor does it describe what happens when the common branch and the release branch drift apart. That silence is a real operational consideration: if you build your own images, you own the pairing between those two branches.

The third is the release cadence visible in the release list. The most recent release listed is 5.0-GA from 2023-04-28, preceded by 5.0-RC and 5.0-Beta earlier that year. The repository's last push was on 2026-09-23, so development activity continues, but the tagged release line has not moved past 5.0-GA in the releases shown. If your adoption policy requires a recent tagged GA, that gap is something to weigh rather than assume away.

Photon OS compared with a general purpose container host

The natural alternative is a general purpose distribution that also runs containers, such as a mainstream enterprise Linux. The difference is not feature lists; it is what the project optimizes for. A general purpose distribution optimizes for breadth: the widest possible set of packages, hardware and use cases, with a container runtime as one workload among many. Photon OS optimizes for a narrow target: cloud-native containers, cloud platforms and VMware infrastructure, with the kernel tuned for ESXi and the image formats matching the platforms the README names.

That difference shows up in the management tooling. Photon OS pairs tdnf with the Photon Management Daemon, and the README presents the two together as the lifecycle story. A general purpose distribution typically gives you a package manager and leaves host management to whatever configuration management you already run. Neither approach is better in the abstract. If you already have configuration management for your fleet, Photon OS's management daemon is an additional component to learn; if you do not, it is a component you get.

The second real difference is the image supply chain. Photon OS is delivered as ISO, OVA, AMI, GCE image and Azure VHD, and the README directs you to the wiki for download links rather than to a package repository. A general purpose distribution usually expects you to install from media or a network installer and then pull packages. Photon OS expects you to start from an image that already matches the platform you are deploying to.

Licence and upgrade cost

The licensing is split, and the split matters. The README states that the Photon OS ISO and OVA images are distributed under the Photon OS EULA. Separately, with the exception of the libtdnf source code, the Photon OS source code is distributed under GNU GPL v2, and libtdnf is under GNU LGPL v2.1. The repository carries both EULA.txt and LICENSE.md at the top level, along with COPYING, NOTICE-Apachev2 and NOTICE-GPL2.0. The practical reading is that the artifact you deploy and the source you build from are not governed by the same document, so if you redistribute images, read the EULA rather than assuming the GPL terms cover the image. This is a description of what the files say, not legal advice.

Upgrade cost is dominated by the build change in 5.0. Because Photon 5 requires the common branch alongside the release branch, any pipeline you built for an earlier Photon line that cloned a single branch will need rework: a second clone, a build-config.json entry or a COMMON_BRANCH_PATH argument, and jq on the build host. The README documents the requirement and the two ways to satisfy it, and documents nothing about rollback or about version skew between the branches. Budget for testing the pairing yourself.

Editorial conclusion

Adopt Photon OS when your containers already run on vSphere or you need a small, tdnf-managed host image for an AMI, GCE image or Azure VHD, and when you are willing to track Photon 5.0 rather than an older branch. Do not adopt it as a general purpose server distribution, and do not assume the ISO and OVA carry the same terms as the source tree, because the images ship under the Photon OS EULA while the source is GPL v2 apart from libtdnf under LGPL v2.1. Before you commit, verify three things: that the packages you need exist in the Photon 5.0 repositories, that your build machine has jq installed since the Makefile errors out without it, and that you can clone both the release branch and the common branch, because Photon 5 will not build from a single checkout.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. vmware/photon on GitHub