FAQ

Identrix runs as a standalone console application — there is no traditional installer. Just download the archive for your platform, extract it, and run it. See the Installation guide for your operating system (Windows, macOS, or Linux).

Yes. Because Identrix isn’t distributed through the Microsoft Store or the Apple App Store, Windows SmartScreen or macOS Gatekeeper may show a warning the first time you run it.

• On Windows, click Run Anyway, or right-click Identrix.exe → Properties and check Unblock.
• On macOS, open System Settings → Privacy & Security and click Open Anyway, or Control-click the application and choose Open.

See the Windows and macOS installation guides for the full steps.

Two things: a license key and a configuration file. See Running Identrix for the first time for the full walkthrough.

You should receive a license key from us by email, named something like <company>.<username>.identrix.identrix.<expdate>.license.lic. Copy it into the folder where Identrix is installed, rename it to license.lic, and make sure it’s readable by the user that runs Identrix. Details in Running Identrix for the first time.

Copy the supplied config.default.yml and rename the copy to config.yml:

cp config.default.yml config.yml

Then edit config.yml to match your needs — see Configuration for an overview of the file and Configuration parameters for details on individual settings.

Run the following commands:

identrix devices -list
identrix nfc -list

Each command lists the recognized devices, which port they’re connected to (e.g. COM4 or /dev/ttyUSB0), and the product name. See Connect a Scanner for the full procedure.

A few quick checks that solve most cases:

• Try a different USB port (preferably USB 3.0) and a different cable
• Connect the scanner directly to the computer rather than through a USB hub
• Unplug and reconnect the scanner, or restart your computer
• On Windows, open Device Manager and look for devices with a yellow warning icon

If the scanner still doesn’t show up in identrix devices -list or identrix nfc -list, you may need to (re)install drivers — see Connect a Scanner and the platform-specific notes below.

It depends on your platform:

• Windows: halfpage scanners usually need the VCOM driver package — see Halfpage Readers for the full installation and troubleshooting guide.
• Linux: make sure the required packages are installed and the smartcard reader is identified by the system, as described in the Linux installation guide.
• macOS: built-in PC/SC support means no extra drivers are normally needed. If a reader still isn’t recognized, see Connect a Scanner.

Identrix reads its settings from config.yml in its install directory. It controls logging, MRZ parsing behavior, serial port settings, NFC reading options, output targets, and the built-in webserver. See Configuration for an annotated example and Configuration parameters for details on each setting.

Run the diagnostics command:

identrix diag

This reports on the current configuration, device state (VCOM/NFC), and other runtime information — useful both for verifying your own setup and for sharing with support when something goes wrong.

Run:

identrix start

This starts Identrix in service mode: it listens on the configured serial ports and sends results to your configured output targets or webserver. See Console & Commands for the full command reference and Running Identrix for more on running it day to day.

Identrix can output scan results as JSON, XML, or TEXT, and can send them to a file, a URL/webhook, or stream them over a websocket. See Output, File & URL/Webhook output, and Websockets for configuration details.

Identrix relies on ImageMagick to convert JP2/J2K images (commonly found on identity documents) to JPG on the fly. If ImageMagick isn’t installed, this conversion won’t happen automatically. Install it from the official ImageMagick download page — Identrix will autodetect it. See Automatic image conversions and Configuration parameters for how to enable it in your config.

To help us help you faster, please include:

• The output of identrix diag (copy it to your clipboard or save it to a file)
• Your operating system and version
• Any error messages you received
• Whether the issue is new, or something that used to work

Head to the Downloads page — it detects your operating system and links you straight to the right build for Windows, macOS, or Linux.