Skip to content

Installation

Requirements

  • PHP 8.4 or higher
  • Composer (any modern version)

Tip

Not sure which PHP version you have? Run php -v in your terminal.

Install Qualimetrix as a development dependency in your project:

composer require --dev qualimetrix/qualimetrix

After installation, the qmx binary is available at:

vendor/bin/qmx

PHAR

A standalone archive that runs without adding Qualimetrix to your project's dependencies. Download qmx.phar from the latest release, make it executable, and run it:

chmod +x qmx.phar
./qmx.phar check src/

Keep the .phar suffix

Parallel analysis copies the whole archive into your temporary directory on every run when the file it runs from is not named *.phar. Renaming it to qmx costs several megabytes of copying per run.

Notes for PHAR use:

  • HTML reports use the analysed project's composer.json name, falling back to its directory name. Pass --format-opt=project-name=your/project to override the label.
  • Releases published before this feature carry no qmx.phar asset; the first release that does is the one whose changelog entry announces it.

Building it yourself

From a checkout of this repository, composer phar writes build/qmx.phar. It fetches its build tool from GitHub, so it needs the GitHub CLI on PATH.

Docker

Run Qualimetrix in a container without installing PHP locally:

docker run --rm -v $(pwd):/app qmx check src/

This mounts your current directory into the container and analyzes the src/ folder. The image sets XDG_CACHE_HOME=/cache. Without a /cache volume, AST entries disappear with the container. Mount a persistent volume per uid; a volume owned by another uid disables the implicit cache with a warning. Keep it outside /app. For runs with --user $(id -u), use a separate volume owned by that uid.

You can pass any CLI options after check:

# JSON output
docker run --rm -v $(pwd):/app qmx check src/ --format=json

# With baseline
docker run --rm -v $(pwd):/app qmx check src/ --baseline=baseline.json

Verifying Installation

vendor/bin/qmx --version

bin/qmx --version

./qmx.phar --version

docker run --rm qmx --version

You should see output like:

Qualimetrix x.x.x

What's Next?

Head to the Quick Start guide to run your first analysis and set up integration with your workflow.