How to install QIT in WSL2 Ubuntu

This guide is for installing the WooCommerce **Quality Insights Toolkit (QIT)** CLI on a WSL (Ubuntu) machine.

Official docs here [https://qit.woo.com/docs/getting-started/](https://qit.woo.com/docs/getting-started/)

Prerequisites

Install these in WSL first:

• PHP 7.2.5 or higher — check with `php –version`
• Composer — check with `composer –version`
• Docker and Docker Compose — check with `docker –version` and `docker compose version`
• Node.js and npm — check with `node –version`

If Composer is missing, install it from here.

Step 1 — Install the QIT CLI

Run:

composer global require "woocommerce/qit-cli:*"

Composer puts the `qit` binary in its **global bin directory**, not in `/usr/bin`. That is why `qit` is often “not found” until you add that directory to your PATH.

Step 2 — Add `qit` to your PATH

Find the bin directory:

composer global config bin-dir --absolute

On this machine it is usually:

/home/iakovos/.config/composer/vendor/bin

Add it to `~/.bashrc`:

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

source ~/.bashrc

Verify:

qit --version

If you still see `qit: command not found`, open a new terminal, or call it with the full path:

~/.config/composer/vendor/bin/qit --version

Step 3 — Log in to WooCommerce.com

Run:

qit connect

Then:

1. Enter your WooCommerce.com partner email.

2. Open the authorization URL it prints. Stay logged into WooCommerce.com in the browser.

3. Paste the QIT token into the terminal. The characters will not appear as you type. That is normal.

Confirm it worked:

qit extensions

You should see your marketplace extensions, including `blacklist-for-woocommerce`.

Step 4 — Playwright on WSL (needed for E2E tests)

QIT runs Playwright on the host machine, not inside Docker.

From a plugin test package (example):

cd tests/e2e

npm install

npx playwright install chromium

Ubuntu 24.04 often lacks `libasound.so.2`. Chromium then fails to start.

Option A — install the system library (needs sudo):

sudo apt-get install -y libasound2t64

Option B — no sudo: some test packages vendor that library (for example under `tests/e2e/.playwright-libs`) and download it on the first QIT run.

Step 5 — Smoke test

From the plugin root:

qit run:e2e blacklist-for-woocommerce \

  --test-package=./tests/e2e \

  --zip=devscripts/blacklist-for-woocommerce.zip

Later — update QIT

composer global update woocommerce/qit-cli

qit --version

Common problems

`qit: command not found`

Composer’s bin directory is not on your PATH. Repeat Step 2, then run `source ~/.bashrc` or open a new terminal.

`Authentication failed`

The token was copied incorrectly, or you were not logged into the matching WooCommerce.com account. Run `qit connect` again.

`libasound.so.2: cannot open shared object file`

Install `libasound2t64`, or use the vendored library from the test package.

`./bootstrap/*.sh: Permission denied`

Make the bootstrap scripts executable:

chmod +x tests/e2e/bootstrap/*.sh

Git on WSL sometimes drops the execute bit. If this comes back after a clone, run `chmod` again.