How to Install PHPUnit on Ubuntu

PHPUnit helps you write and run automated tests for PHP applications, catching bugs before they reach production. Whether you are building a Laravel API, maintaining a WordPress plugin, or developing a Symfony application, PHPUnit provides the testing framework to verify that your code works as expected. By the end of this guide, you will have PHPUnit installed globally via Composer, configured in your PATH for easy access, and verified with a working test case.

This guide covers Ubuntu 22.04 LTS, 24.04 LTS, and 26.04 LTS. PHPUnit version depends on your PHP version: PHP 8.3+ receives PHPUnit 12.x, while PHP 8.1 receives PHPUnit 10.x. Commands work identically across all supported LTS releases.

Install Prerequisites for PHPUnit

Before installing Composer and PHPUnit, you need PHP and several extensions that PHPUnit requires. Ubuntu’s default repositories include PHP, so most users can install directly with APT. If you need a specific PHP version such as 8.3 or 8.4, see our guide on installing PHP on Ubuntu for additional options. First, update your package index to ensure you install the latest available versions:

sudo apt update

Next, install the required packages. The php-xml extension provides DOM support for PHPUnit’s test output, php-mbstring handles multibyte string operations, and unzip allows Composer to extract downloaded packages:

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

Once installed, verify that PHP is working correctly by checking the version:

php --version

You should see output similar to the following, confirming PHP is available:

PHP 8.3.6 (cli) (built: Mar 14 2025 17:57:07) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.6, Copyright (c) Zend Technologies
    with Zend OPcache v8.3.6, Copyright (c), by Zend Technologies

The PHP version varies by Ubuntu release: Ubuntu 26.04 includes PHP 8.4, Ubuntu 24.04 includes PHP 8.3, and Ubuntu 22.04 includes PHP 8.1. All versions work with PHPUnit, though the installed PHPUnit version will differ accordingly.

Install Composer on Ubuntu

Composer is the dependency manager for PHP that handles PHPUnit installation. If you already have Composer installed globally, you can skip to the next section. Otherwise, download and run the official Composer installer script:

curl -sS https://getcomposer.org/installer | php

The -sS flags run curl in silent mode while still showing errors. This command downloads the installer and pipes it directly to PHP, which creates a composer.phar file in your current directory.

To use Composer from any directory, move the phar file to a location in your system PATH:

sudo mv composer.phar /usr/local/bin/composer

Verify the installation by checking the Composer version:

composer --version

You should see output confirming Composer is ready to use:

Composer version 2.9.2 2025-11-19 21:57:25
PHP version 8.3.6 (/usr/bin/php8.3)
Run the "diagnose" command to get more detailed diagnostics output.

For a more detailed Composer installation guide, including signature verification and troubleshooting, see how to install Composer on Ubuntu.

Install PHPUnit with Composer

With Composer installed, you can now install PHPUnit globally. The global installation makes PHPUnit available for all your PHP projects without adding it as a dependency to each project individually:

composer global require phpunit/phpunit

Composer downloads PHPUnit and all its dependencies to your home directory. This process may take a minute as it resolves and installs approximately 25 packages:

Changed current directory to /home/username/.composer
./composer.json has been created
Running composer update phpunit/phpunit
Loading composer repositories with package information
Updating dependencies
Lock file operations: 25 installs, 0 updates, 0 removals
  - Locking myclabs/deep-copy (1.13.4)
  - Locking phpunit/phpunit (12.5.4)
  ...
Writing lock file
Installing dependencies from lock file
  - Installing phpunit/phpunit (12.5.4): Extracting archive
Generating autoload files
No security vulnerability advisories found.
Using version ^12.5 for phpunit/phpunit

Add Composer Global Bin Directory to PATH

By default, globally installed Composer packages are placed in ~/.composer/vendor/bin/. To run PHPUnit from any directory without specifying the full path, add this directory to your shell’s PATH environment variable.

Append the following line to your ~/.bashrc file:

echo 'export PATH="$PATH:$HOME/.composer/vendor/bin"' >> ~/.bashrc

This command adds the Composer bin directory to your PATH permanently for future terminal sessions. To apply the change immediately without opening a new terminal, reload your shell configuration:

source ~/.bashrc

Alternatively, you can simply open a new terminal window for the changes to take effect automatically.

Verify that your PATH now includes the Composer bin directory:

echo $PATH

Look for .composer/vendor/bin in the output. You can also confirm PHPUnit is accessible by checking its version:

phpunit --version

The output confirms PHPUnit is installed and accessible from your terminal:

PHPUnit 12.5.4 by Sebastian Bergmann and contributors.

If you use Zsh instead of Bash, add the export line to ~/.zshrc and run source ~/.zshrc instead.

Verify PHPUnit with a Test Case

After installation, verify that PHPUnit works correctly by creating and running a simple test. First, create a test file using your preferred text editor:

nano ~/test.php

Add the following PHP code, which defines a basic test that asserts 2+2 equals 4:

<?php

class Test extends PHPUnit\Framework\TestCase
{
    public function testAddition()
    {
        $this->assertEquals(2+2, 4);
    }
}

This test class extends PHPUnit\Framework\TestCase, which provides the assertion methods you need for testing. The testAddition method uses assertEquals to verify that the expected value (4) matches the actual result.

Save the file and run the test with PHPUnit:

phpunit ~/test.php

A successful test run produces output similar to the following:

PHPUnit 12.5.4 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.6

.                                                                   1 / 1 (100%)

Time: 00:00, Memory: 14.00 MB

OK (1 test, 1 assertion)

The single dot represents one passing test, and “OK (1 test, 1 assertion)” confirms everything works correctly. You can now clean up the test file:

rm ~/test.php

Troubleshoot Common PHPUnit Issues

Command Not Found After Installation

If you receive “phpunit: command not found” after installation, the PATH was not updated correctly. First, verify that PHPUnit exists in your Composer bin directory:

ls ~/.composer/vendor/bin/phpunit

If the file exists, check that your PATH includes the directory:

echo $PATH | grep -o '.composer/vendor/bin'

If nothing is returned, the PATH export was not applied. Run source ~/.bashrc or open a new terminal session.

Missing PHP Extensions

PHPUnit requires several PHP extensions to function properly. If you encounter errors about missing classes or functions, install the commonly required extensions:

sudo apt install php-xml php-mbstring php-tokenizer -y

Composer Cannot Download Packages

If Composer fails with “The zip extension and unzip/7z commands are both missing,” install the unzip package:

sudo apt install unzip -y

Then retry the PHPUnit installation command.

Manage PHPUnit Installation

Update PHPUnit

To update PHPUnit to the latest version when new releases become available, use Composer’s global update command:

composer global update phpunit/phpunit

After updating, verify the new version is installed:

phpunit --version

Remove PHPUnit

If you no longer need PHPUnit globally, remove it with Composer:

composer global remove phpunit/phpunit

Verify the removal by attempting to run PHPUnit:

phpunit --version

You should see “command not found” if the removal was successful. The PATH export in your ~/.bashrc can remain in place as it does not cause issues when the directory is empty.

Conclusion

You now have PHPUnit installed globally on Ubuntu and configured for command-line access. From here, explore PHPUnit’s assertion methods, data providers, and mocking capabilities to build comprehensive test suites for your PHP applications. For detailed usage documentation and advanced features, refer to the official PHPUnit documentation.