How to Install PHPUnit on Ubuntu 26.04, 24.04 and 22.04

Writing tests is easier when the runner matches both Ubuntu’s PHP runtime and your project’s dependency tree. You can install PHPUnit on Ubuntu from the default repositories for the quickest system command, or add PHPUnit with Composer inside a project when you need a newer branch locked in composer.json.

Ubuntu 26.04 already ships a current 13.x package, while Ubuntu 24.04 and 22.04 keep older 9.x packages for release stability. The sections below cover Ubuntu 26.04, 24.04, and 22.04, with version-specific notes where the default PHP or PHPUnit branch changes.

Install PHPUnit on Ubuntu

Ubuntu gives you two practical paths for PHPUnit. The repository package is the fastest route and keeps updates inside normal APT maintenance, while Composer installs PHPUnit as a project development dependency from Packagist.

Method	Source	PHPUnit Branch	Update Path	Best For
Ubuntu package	Ubuntu Universe	13.x on Ubuntu 26.04, 9.x on Ubuntu 24.04 and 22.04	APT upgrades	Quick setup and a system-wide phpunit command
Composer project install	Packagist through Composer	Newest branch compatible with the project’s PHP runtime	Composer dependency updates	Active PHP projects that track dependencies in Composer

Pick one primary runner for each project. Ubuntu’s package installs /usr/bin/phpunit for any terminal session, while Composer creates ./vendor/bin/phpunit inside the project directory. If both exist, run the path that matches the method you intend to use.

Current Ubuntu package candidates install PHPUnit 13.0.0 on 26.04, 9.6.17 on 24.04, and 9.5.10 on 22.04. Composer resolves by PHP compatibility instead: Ubuntu 26.04’s default PHP can use PHPUnit 13.x, Ubuntu 24.04’s default PHP can use 12.x, and Ubuntu 22.04’s default PHP can use 10.x.

Install the Ubuntu phpunit package

This is the simplest path when the repository package already fits your project. It works on all supported Ubuntu LTS releases, but the installed PHPUnit branch differs sharply between 26.04 and the older 24.04 or 22.04 releases.

sudo apt update

These commands use sudo for tasks that need root privileges. If your account does not have sudo access yet, run them as root or use add a new user to sudoers on Ubuntu first.

The phpunit package lives in Ubuntu’s Universe component on 26.04, 24.04, and 22.04. If APT cannot find it, enable Universe first with enable Universe and Multiverse in Ubuntu. Only Universe is required for PHPUnit.

sudo apt install phpunit -y

Check the installed version once APT finishes:

phpunit --version

Relevant output on Ubuntu 26.04 includes:

PHPUnit 13.0.0 by Sebastian Bergmann and contributors.

Ubuntu 24.04 and 22.04 still report older 9.x builds here, which is fine for legacy suites but not ideal for active projects that want a current PHPUnit branch.

Install PHPUnit with Composer in a Project

Use Composer when PHPUnit belongs to a specific PHP project. This is the normal dependency-managed workflow because the project records PHPUnit in composer.json and locks the resolved patch release in composer.lock. Composer is already packaged in Ubuntu. If you prefer Composer’s upstream installer instead of the Ubuntu package, use install Composer on Ubuntu.

The next command installs Composer from Ubuntu along with the PHP extensions PHPUnit expects. php-cli provides the command-line interpreter, php-xml and php-mbstring satisfy PHPUnit’s platform requirements, and unzip lets Composer extract distribution archives cleanly. If you need a different PHP branch before continuing, use install PHP on Ubuntu first.

sudo apt install composer php-cli php-xml php-mbstring unzip -y

Verify the Composer package before you use it:

composer --version

Relevant output begins with the Composer version:

Composer version 2.x.x

Move into your PHP project before adding PHPUnit. If you only want to test the workflow, create a small scratch project first:

mkdir -p ~/phpunit-example
cd ~/phpunit-example

Add PHPUnit as a development dependency:

composer require --dev phpunit/phpunit

The exact branch depends on the PHP version Composer sees. Composer writes the resolved package set to composer.lock, so teammates and deployment hosts use the same PHPUnit release until you update it.

Confirm that the project-local PHPUnit binary works:

./vendor/bin/phpunit --version

PHPUnit 13.x.x by Sebastian Bergmann and contributors.

On Ubuntu 24.04, expect the version line to start with PHPUnit 12.x. On Ubuntu 22.04, expect PHPUnit 10.x unless you installed a newer PHP runtime first.

Match PHPUnit to Your PHP Version on Ubuntu

PHPUnit’s upstream support matrix is tied directly to your PHP runtime. The official PHPUnit supported versions page is the source of truth for minimum PHP requirements, and Ubuntu’s default PHP version decides which modern branch Composer can install without extra PHP changes.

PHPUnit Branch	Minimum PHP	Ubuntu Releases That Can Run It	Ubuntu-Specific Note
13.x	PHP 8.4+	Ubuntu 26.04	Default-package branch on Ubuntu 26.04 and Composer branch for PHP 8.4+
12.x	PHP 8.3+	Ubuntu 26.04, 24.04	Composer branch for Ubuntu 24.04’s default PHP 8.3 runtime
11.x	PHP 8.2+	Ubuntu 26.04, 24.04	Useful when a project is pinned to PHPUnit 11 instead of the newest compatible branch
10.x	PHP 8.1+	Ubuntu 26.04, 24.04, 22.04	Composer branch for Ubuntu 22.04’s default PHP 8.1 runtime
9.x	PHP 7.3+	Ubuntu 24.04, 22.04 through APT packages	Packaged by Ubuntu for release stability, but older than the branches active projects usually choose with Composer

Ubuntu’s repository package on 24.04 and 22.04 stays on PHPUnit 9.x for distribution stability, which is still workable for older suites. For new or actively maintained projects, Composer usually gives a better match because it follows the newest branch your PHP runtime can support.

If you specifically need a direct PHPUnit download, upstream publishes branch PHAR files at phar.phpunit.de. Use the branch that matches your PHP version; for normal Ubuntu project work, Composer is usually easier to update and audit because the dependency is recorded in the project files.

Verify PHPUnit on Ubuntu with a Test Case

A quick smoke test confirms that PHPUnit can load its framework classes and run a real assertion. The example below works on the older 9.x repository packages as well as newer Composer-installed branches.

Create the PHPUnit ExampleTest.php file

Create a temporary test file in /tmp so cleanup stays simple afterward:

nano /tmp/ExampleTest.php

Paste in this minimal test case:

<?php
declare(strict_types=1);

use PHPUnit\Framework\TestCase;

final class ExampleTest extends TestCase
{
    public function testAddition(): void
    {
        $this->assertSame(4, 2 + 2);
    }
}

Run the test with PHPUnit

Run the file with the binary from your install method. The --do-not-cache-result flag keeps this one-off smoke test from trying to write a result cache file you do not need:

# Ubuntu package method
phpunit --do-not-cache-result /tmp/ExampleTest.php

# Composer project method, run from the project directory
./vendor/bin/phpunit --do-not-cache-result /tmp/ExampleTest.php

Relevant output on Ubuntu 26.04 includes:

PHPUnit 13.0.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.5.x

OK (1 test, 1 assertion)

Ubuntu 24.04 and 22.04 still end with OK (1 test, 1 assertion), but the older 9.x output format is slightly shorter and can omit the runtime line. Remove the temporary file when you are done:

rm -f /tmp/ExampleTest.php

Troubleshoot Common PHPUnit Issues on Ubuntu

Most Ubuntu-specific problems come from using the wrong binary path after a Composer install or from missing PHP extensions during dependency resolution. These checks keep both problems local and straightforward to verify.

Fix phpunit: command not found on Ubuntu

A Composer project install does not create a global phpunit command. From the project directory, use the binary under vendor/bin:

./vendor/bin/phpunit --version

PHPUnit 13.x.x by Sebastian Bergmann and contributors.

If you installed the Ubuntu package instead, verify that APT’s binary is on your shell path:

command -v phpunit

/usr/bin/phpunit

When that command returns nothing, install the Ubuntu package or move into the Composer project and use ./vendor/bin/phpunit.

Fix Composer platform requirement errors on Ubuntu

Errors mentioning missing ext-dom, ext-mbstring, or ext-xml mean the CLI extensions are missing for the PHP version Composer is using. Install the required packages, then rerun the Composer command:

sudo apt install php-cli php-xml php-mbstring unzip -y

After the retry, run ./vendor/bin/phpunit --version again from the project directory to confirm Composer installed a compatible PHPUnit branch.

Avoid Exposing Old PHPUnit Files in Web Roots

Install PHPUnit as a development dependency, not as a public web asset. If web logs show probes for vendor/phpunit/phpunit/src/Util/PHP/eval-stdin.php or similar old PHPUnit paths, remove development dependencies from the public document root and redeploy only runtime files under the web server path.

Those scans usually target CVE-2017-9841, an old PHPUnit exposure tied to publicly reachable test tooling. Ubuntu lists its 24.04 and 22.04 packages as not affected, and Ubuntu 26.04 uses the newer 13.x branch, but Composer’s vendor/ directory should still stay outside the web root when possible.

Update or Remove PHPUnit on Ubuntu

The update and removal path depends on how you installed PHPUnit. Keep the package-manager method and the Composer method separate so the verification commands make sense.

Update the Ubuntu phpunit package

APT updates stay on the branch your Ubuntu release packages, so 24.04 and 22.04 do not jump to newer major PHPUnit branches here:

sudo apt install --only-upgrade phpunit

Check the installed version after the upgrade:

phpunit --version

PHPUnit 13.0.0 by Sebastian Bergmann and contributors.

Update the Composer installation

Composer can move PHPUnit to the newest compatible patch release or branch your project’s PHP version allows. Run the update from the project directory:

composer update phpunit/phpunit --with-dependencies

Verify the installed branch after the update:

./vendor/bin/phpunit --version

PHPUnit 13.x.x by Sebastian Bergmann and contributors.

Remove the Ubuntu phpunit package

Remove the repository package with APT when you no longer want the Ubuntu-managed version:

sudo apt remove phpunit

Preview unused dependencies before removing them. Continue only if the package list contains dependencies you no longer need:

sudo apt autoremove --dry-run

If the preview is clean, run the real cleanup interactively:

sudo apt autoremove

Verify that the package itself is no longer installed with an installed-state check:

dpkg-query -W -f='${db:Status-Abbrev} ${binary:Package}\n' phpunit 2>/dev/null | grep '^ii' || echo "phpunit is not installed"

Expected output after removal:

phpunit is not installed

If you also want to confirm the remaining repository candidate, check APT policy separately:

apt-cache policy phpunit

Remove the Composer installation

Remove the project dependency when you no longer need PHPUnit in that Composer project:

composer remove --dev phpunit/phpunit

Verify that Composer no longer lists the package as a direct project dependency:

composer show phpunit/phpunit --direct 2>/dev/null || echo "phpunit/phpunit is not installed in this project"

Relevant output includes:

phpunit/phpunit is not installed in this project

If phpunit --version still works after this removal, the Ubuntu repository package may still be installed. Remove the APT package separately if you no longer want the system-wide command.

Conclusion

PHPUnit is ready on Ubuntu once you choose the runner that fits your project: APT for a quick system-wide command, or Composer for a project-local dependency that follows the PHP version in that project. After the smoke test passes, use the official PHPUnit manual to build real test suites, configuration files, and coverage workflows around your installed runner.