Documentation

FAQ
Code Examples
Pixel Printing
Raw Printing
Communication
Network Information Data Filtering Getting Started Using QZ Tray Signing Messages API Overrides Command Line Usage
Licensing/Renewing
Generate Certificate Certificate Renewal Company Branded Signing Messages General Licensing Information
Printer Emulators
Deployment Options
Print Server Deployment Multiple Instances Windows Service Headless Operation Unattended Deployment Custom Provisioning Client Side Substitutions
Configure Raw Printer
Windows Ubuntu Linux macOS
Compiling
Install Dependencies Compile (QZ Tray)

Deployment

Compatibility

  • ✅ 2.2 | ✅ 2.1 | ✅ 2.0 | ✅ 1.9 | ...

Objective

Perform a silent, unattended or slipstream installation of QZ Tray, such as in a corporate environment.

  • Note For continuous-integration (CI/CD) or quick-installation to a developer's machine, you may be interested in utilizing qz.sh instead, which will automatically connect to the download page and fetch the latest stable release.
    • 💡 CI/CD consideration: Due to environment differences, knowledge of [[starting QZ Tray manually|command-line]] and handling [[headless operation|headless]] is a prerequisite.

Steps

Windows

We use NSIS (Nullsoft Scriptable Installer System) for Windows.

  • Install silently to the default location (run Command Prompt as Administrator)

    start /wait "" qz-tray-2.x.x.exe /S

  • Install silently to a non-standard location (run Command Prompt as Administrator)

    start /wait "" qz-tray-2.x.x.exe /S /D=C:\Program Files\QZ Tray

Linux

We use Makeself for Linux.

  • Install silently to the default location

    sudo bash qz-tray-2.x.x.run -- -y

Mac

We can use the installer command on Mac to silently install QZ Tray via the command line. Type (or click here): man installer on the command line for more examples.

  • Install silently to the default location

    sudo installer -pkg qz-tray-2.x.x.pkg -target /

  • Install silently to a non-standard location

    Note: Use at your own risk; Non-standard install locations are currently not supported.

    sudo installer -pkg qz-tray-2.x.x.pkg -target /Alternate/Volume

Uninstall

Windows Uninstall

We use NSIS (Nullsoft Scriptable Installer System) for Windows.

  • Uninstall silently 
    start /wait "" "%programfiles%\QZ Tray\uninstall.exe" /S

Linux Uninstall

  • Uninstall silently

    sudo bash /opt/qz-tray/uninstall

Mac Uninstall

  • Uninstall silently 
    # 2.2+
sudo bash /Applications/QZ\ Tray.app/Contents/Resources/uninstall

# 2.1 and older
sudo /Applications/QZ\ Tray.app/Contents/uninstall

Automatic Start

Automatic start steps (legacy versions only)

QZ Tray 2.1+

QZ Tray 2.1 and higher will automatically start at login, no steps are needed.

QZ Tray 2.0

For versions 2.0 and older, the user must click "Automatically start" in the tray icon, which may not be desired for corporate environments.

There are several methods for making an application launch automatically on various desktops, however to mimic the technique used by QZ Tray 1.9 - 2.0 is:

Windows Automatic Start

  1. First, uncheck "Automatically start" and close QZ Tray.

  2. Run the following command through a Command Prompt window. Administrative access is not required.

    reg.exe add HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ /v "QZ Tray" /d "%programfiles%\QZ Tray\qz-tray.exe" /f
    • For white-label customers, replace QZ Tray with the name of your application, e.g. Acme Printing, etc.

  3. Re-launch QZ Tray and verify the "Automatically start" option has been reselected.

    screen shot 2017-12-18 at 12 52 33 pm

  4. To secure this change (user cannot disable) requires modifying registry permissions using regini and a separate .reg file which can have other negative side-effects and is out of scope of this tutorial.

qz.sh

(or pwsh.sh for Windows)

For quick installation of the latest version, qz offers an online scripted installer.

Screen Shot 2022-04-19 at 1 30 32 PM

macOS

# Download and install the latest stable release of QZ Tray
curl qz.sh |bash

Linux

# Download and install the latest stable release of QZ Tray
wget -O - qz.sh |bash

Windows

# Download and install the latest stable release of QZ Tray
irm pwsh.sh | iex
Click to expand what to do if you recieve a security error 
# Optional: Needed to run a remote script the first time
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Advanced

Additional parameters can be provided to specify beta or an exact tagged release. Note: There may not be a beta version available. Check https://qz.io/download if unsure.

Curl

curl qz.sh |bash -s -- "beta"   # latest beta release
curl qz.sh |bash -s -- "2.2.1"  # tagged "v2.2.1" release

Wget

wget -O - qz.sh |bash -s -- "beta"   # latest beta release
wget -O - qz.sh |bash -s -- "2.2.1"  # tagged "v2.2.1" release

PowerShell

& ([scriptblock]::Create((irm pwsh.sh))) beta   # latest beta release
& ([scriptblock]::Create((irm pwsh.sh))) 2.2.1  # tagged "v2.2.1" release

Troubleshooting

Steps for gathering additional logs from a failed installation.

macOS

  • macOS will write the debug installation logs to /tmp. 
    cat /tmp/qz-installer.log
# For Company Branded versions:
# cat /tmp/<vendor_abbreviation>-install.log

Linux

  • Linux will write the debug installation logs to the terminal if environment variable DEBUG is set. 
    sudo bash # or su
export DEBUG=true
./qz-tray-x.x.x.run
# Detailed logs should appear in the console

Windows

  • Windows does not have a dedicated logging location other than the NSIS installation Window.
  • To obtain logs from the NSIS installation Window, start the installation interactively, click the Show details button and copy/paste the installation logs to a text editor such as Visual Studio Code. If you believe your error may occur during the startup process, you may run qz-tray-console.exe from C:\Program Files\QZ Tray for a live,m interactive log.

Additional Troubleshooting

  • If the issue with installation is suspected to be certificate-related, you may re-run the certgen step interactively. 
    # macOS
sudo "/Applications/QZ Tray.app/Contents/MacOS/QZ Tray" certgen

# Windows (CMD as Administrator)
cd "%PROGRAMFILES%\QZ Tray"
qz-tray-console.exe certgen

# Linux
sudo /opt/qz-tray/qz-tray certgen
Edit this page