Installation guide

Install QZX without fighting your Python environment

Choose an installation path that matches how you use Python. Keep QZX isolated as a standalone CLI with pipx, or install it with pip inside an environment you intentionally control.

QZX — Quick Zap Exchange is free and open source, created and maintained by Alejandro Sánchez. The current published package is 0.2.2.0.15 and declares Python >=3.11.

Choose an installation path Continue to the AI-agent quickstart

Already installed, but qzx will not start?

Choose by environment

Three honest ways to start

Standalone CLI

Keep QZX isolated with pipx

Use this when QZX is a command-line application on your machine rather than a dependency of a Python project. pipx gives the app its own environment while exposing the qzx command on your PATH.

pipx install qzx

Controlled Python environment

Use pip where you own the environment

An activated virtual environment or another Python environment you deliberately manage is a valid place for QZX. The published-channel command below remains supported.

python -m pip install --upgrade qzx

Evaluate first

Try the published CLI without keeping it

If pipx is already available, run QZX in a temporary isolated environment and ask the runtime to identify itself. This is useful when you want evidence before deciding to install.

pipx run --spec qzx qzx version

Verify the runtime

Turn installation into a first success

Do not assume an installer succeeded because it printed no obvious error. Ask the installed runtime for its identity, then complete QZX's canonical read-only first success.

qzx version --json
qzx getCurrentDateTime --output-format iso --json

Once that works, the AI-agent quickstart turns the installation into a useful project-inspection workflow. The installed runtime remains the source of truth for its own version and command catalog.

Installed, but your terminal cannot find qzx?

Choose the recovery path that matches your installation. A missing launcher does not necessarily mean the package is missing.

I installed with pip: run through the same Python

Use the same Python you installed with: python, python3 or py -3.13.

python -m qzx version --json
python -m qzx getCurrentDateTime --output-format iso --json

Use the exact Python interpreter that ran python -m pip install --upgrade qzx. The module form does not need the qzx launcher on PATH.

If you installed with python3 or py -3.13, replace python with that same prefix in every command below. Do not switch interpreters midway.

No module named qzx, or an unexpected version?

Check this interpreter before reinstalling. Activate the environment where you installed QZX, then inspect its pip and package location:

python -m pip --version
python -m pip show qzx

If pip cannot find QZX here, the package is absent from this interpreter. If bare qzx version --json and the module command show different versions, they resolve different installations. Update only the installation you intend to use. An externally-managed-environment error still calls for an environment you control or pipx, not an override.

I installed with pipx: restore its launcher

Run pipx list first. If QZX is listed, run pipx ensurepath and follow its instructions to reopen or refresh the terminal, then try qzx version --json. If QZX is not listed, use the pipx installation option above.

The system Python normally cannot import a pipx-isolated package: do not treat python -m qzx as a pipx repair. pipx run tests a temporary environment, not your existing installation.

Once verification works, open your own project folder and try python -m qzx diagnoseProject . with the pip-installed interpreter, or qzx diagnoseProject . with the pipx launcher. QZX inspects the project; it does not run its test or build scripts.

Still stuck? Get installation help

Before sharing diagnostics, remove personal paths, credentials and private project details.

If pip says externally-managed-environment

Respect the managed Python boundary

Some operating systems and package managers protect their base Python installation. That message means the base interpreter is not the right target for an ordinary application install.

Do not work around it with sudo pip, --break-system-packages, by deleting an EXTERNALLY-MANAGED marker, or by changing ownership of managed Python directories. Install pipx using your platform's supported method, then run pipx install qzx.

Official pipx installation guide QZX Python and platform evidence

Keep control later

Update or remove the isolated CLI cleanly

A pipx installation remains separately manageable instead of becoming an invisible dependency of another project.

pipx upgrade qzx
pipx uninstall qzx

If qzx is not visible after installation, run pipx ensurepath and follow pipx's instruction to refresh or reopen the shell.

Distribution boundary

Use published channels, not an imagined binary

QZX currently publishes its end-user Python package on PyPI. Native standalone Windows executables, macOS application bundles, Homebrew formulae, and Linux distribution packages are not currently advertised as official QZX release channels. Check releases for exact published artifacts and compatibility for current platform evidence.

Prefer the source-level installation document? The GitHub installation guide records the same public boundary alongside the code.