Skip to content
Pete Batard edited this page Aug 4, 2021 · 22 revisions

Zadig 2.x - User Guide

Table of Contents

Basic usage

In its simplest mode of operation, Zadig is meant to install a libusb compatible driver, for a device that does not yet have such a driver installed.

Below is an overview for a typical driver installation:

  1. The first screen you will see when launching Zadig is the User Account Control prompt displayed below. This is because the application needs to run with administrative privileges. To be able to install a driver, you should answer Yes.

  2. With the application running, you should see your USB device appear in the dropdown list (click on the dropdown to see all devices).
    You can also plug your USB device after Zadig is running, as the list is refreshed automatically. When possible, we recommend that you leave only the device you want to install a driver for, and unplug any other USB device.
    The Vendor ID (VID, here 0x045E), Product ID (PID, here 0x289) and (optionally) Interface ID (MI) are also displayed under "USB ID" for your reference. If you leave your mouse over the Vendor ID, you should get the full name of the Vendor displayed. If the Vendor Name cannot be determined, and you know it, you are invited to report it to the USB ID Repository using the new button that will appear then.

    HELP! MY DEVICE DOES NOT APPEAR IN THE LIST!!

    If you cannot see your device listed, then it probably means that it already has a driver installed, in which case you need to be very cautious about replacing it, as other applications or the OS itself may no longer be able to access it afterwards. For instance, if you replace the existing driver for an USB keyboard or mouse, it will no longer be usable for input in Windows but instead will only work with a custom application, which is probably not what you want.

    To see USB devices that already have a driver installed, go to the Options menu and select List All Devices.
    Below is an example of what you would see for an USB mouse, with the HidUsb driver already installed:

  3. (Optional) With your device selected, you can edit its name if the default doesn't suit your needs by clicking the Edit checkbox.
    You can enter a description in the language of your choice. The description you enter here is how the device will appear in Device Manager and other locations.
    You can also select the driver you want to install, between WinUSB, libusb-win32/libusb0 and libusbK, depending on the type of application you plan to use. Currently, any of those drivers can be used for libusb, or LibusbDotNet, whereas libusb-win32 can be used for applications based on the library of the same name.

  4. Once you are satisfied with the selection and device description, simply click the Install Driver Button. Note that the label of this button may change according to the operation you are about to perform. You can also use the split part of the installation button to choose a different operation than the default one, such as extracting the driver files rather than installing them, performing the one-off installation of a WCID Device driver or installing/uninstalling the libusb-win32 filter driver.

  5. On some versions of Windows 7, it is possible that you get the following security alert:
    If that is the case, you should install the hotfix for KB2921916 from Microsoft or select Install this driver software anyway.

  6. Once the installation is started, just wait until it completes. Normally, the installation process takes a matter of seconds, but in some circumstances, if the local system policies cannot be temporarily overridden to disable the creation of a system restore point, it may take a lot longer. You will be notified once the installation is complete.

  7. If the installation was successful, you should end up with something similar to this:Notice how the driver is now being displayed (in green) and indicates WinUSB. WinUSB is one of the drivers supported by libusb-1.0.
    If the driver has been installed successfully, you should now be able to use your device with a libusb based application.

Advanced usage

For power users, Zadig offers the following list of features:

  • Advanced Mode (Options → Advanced Mode):
    In this mode, additional information is displayed, and users also have the ability to select the directory where the files should be extracted.

  • Setting of the options through an INI file:
    All the options that can be set in the menus can also be set from a zadig.ini file, which Zadig attempts to read when started. An example of such an ini file is provided below.

  • Info/Log:
    In Advanced Mode, you can also select the log level appearing in the logging window by going to Options → Log Level. If you want to find out more about what the installation process is doing, or report an issue, make sure you run your driver installation with a sufficient log level.

  • Automated Creation/Signing of a Catalog file (Options → Create a Catalog File / Options → Sign Catalog & Install Autogenerated Certificate):
    Depending on whether these options are enabled, and when using the default drivers, Zadig will automatically generate a Catalog (.cat) file, as well as sign it with a unique self-signed certificate generated on the fly, which is then installed on the current machine during file extraction

  • Fine control over devices listed (Options → List All Devices / Options → Ignore Hubs or Composite Parents):
    By default, Zadig only lists devices that don't have a driver installed. In some situations however, you might want to replace an existing driver, including the ones for USB hubs (usbhub.sys) or Composite Parent (usbccgp.sys). These options allow you to do just that.

  • Create New (Device → Create New Device):
    In the case where you want to install a driver for a device that is not yet plugged, and for which you have the relevant information (VID, PID, etc.), you can select the Create New option and run the installation process so that the next time the device is plugged, the driver will be available.

  • Open Preset (Device → Load Preset Device):
    Similar to the Create New option above, but using a zadig preset device config file. For an example of such a file, see below.

Example of a zadig.ini file

# Sample ini file for Zadig

[general]
  # Start application in advanced mode (default = false)
  advanced_mode = true
  # Exit application upon successful driver installation (default = false)
  exit_on_success = false
  # Log level (0=debug, 1=info, 2=warning, 3=error)
  log_level = 0
  
[device]
  # List all devices, including the ones that already have a driver (default = false)
  list_all = true
  # Include hubs and composite parent devices when listing all (default = false)
  include_hubs = true
  # Trim trailing whitespaces from the USB device description (default = false)
  trim_whitespaces = true
  
[driver]  
  # Select the following as the default driver to install:
  # WinUSB = 0, libusb0.sys = 1, libusbK.sys = 2, Custom = 3 (default = WinUSB)
  default_driver = 2
  # Extract driver files only, don't install (default = false)
  extract_only = false
  # Set the default destination directory for extraction of the driver files (default = "C:\\usb_driver")
  default_dir = "C:\\usb_driver"

[security]
  # If embedded, install the following certificate to the Trusted Publisher store
  # install_cert = "mycert.cer"
  # If set to true, will silently install the cert provided above (not recommended)
  # disable_cert_install_warning = false

Example of a zadig preset device config file

# This is a sample preset device configuration for Zadig
[device]
  Description = "Sample Device"
  VID = 0xABCD
  PID = 0x1234
  MI = 0x01
# You can also force a specific Device Interface GUID as follows
# GUID = "{11111111-2222-3333-4444-555555555555}"

Preventing the replacement of a Zadig libusbK USB Device Driver

The Problem

After replacing an existing USB device driver with libusbK, using Zadig, one may find that Windows silently rolls back the device driver to the previous driver. This usually happens after reboot, but may also occur after unplugging the device. Similar behaviour can also occur as a result of Windows Update; either a rollback or possibly replacement with a newer driver (rollahead).

The Cause

Windows continually, albeit episodically, quests to assure that for each device, the ‘best’ driver is installed. One is probably already aware of such a notion when one attempts to ‘upgrade’ a device driver (via Device Manager) and it comes back saying the best driver is already installed. The metric of ‘best’, termed driver ‘rank’, is some combination of driver date, version, and other factors described here.

However, multiple candidate drivers may share the same rank in which case the most recent date trumps. This quest for ‘best’ is also episodic, so as not to disrupt ongoing programmatic control of a device. Upon power-up or reboot, the Windows PnP Manager scans (‘enumerates’) all attached devices, also doing so upon event of a device attachment (e.g. plug-in of USB device). Upon enumeration, the best driver is determined and assigned.

As explained above, this will typically be the driver with the newer date. For instance, Zadig's date stamp for libusbK might be 11/30/2014 for version 3.0.7.0 resulting in rank 00FF0001. If the user has ever installed other drivers for this device, e.g. drivers from manufacturer, or the device manufacturer’s drivers are hooked by Windows Update (some are, some aren't), then there is risk of unwanted rollback. As mentioned, this risk generally holds for driver dates greater than libusbK’s.

The workaround

Remove competing (typically newer-dated) device drivers, via pnputil.

See Microsoft's How Devices and Driver Packages are Uninstalled under section Deleting a Driver Package from the Driver Store which boils down to issuing the command:

pnputil /delete-driver <example.inf> /uninstall

However, one needs to know which .inf to cite in the <example.inf> placeholder as this may not typically be an explicit manufacturer’s .inf, but rather an installation-synthesized oem####.inf.

To identify that .inf, one can use DeviceManager → [device] → Properties → Events to examine driver events and identify which oem####.inf is the manufacturer-tied one. Or if the driver to delete is the one presently installed: DeviceManager → [device] → Properties → Details → Property:Inf name.

Upon issuing pnputil /delete-driver, both the .inf file in C:\Windows\INF, and the driver folder in C:\Windows\System32\DriverStore\FileRepository\ are deleted.

But what if one alternately needs to switch between libusbK and the (newer) manufacturer’s drivers, e.g. per usage of the manufacturer’s application software? Then one is evidently stuck with manually monitoring for rollback and managing installation/uninstallation of device drivers, which is less than ideal...

Also note that you can’t simply edit the date in the .inf file, since it is bound via digital signature in the accompanying .cat file (see here or here), although perhaps deliberately deleting the .cat file to force the prompt for ‘install anyway’ might be a workaround.

Possible Prevention

Block (Windows Update) driver installation for particular device, per this arcticle (Caution: We have not tried this!). Necessary only if device manufacturer’s drivers are hooked by Windows Update.

Process and Diagnostic Details

  • One can check for device entry in the Windows Registry using RegEdit: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Enum\USB\
    • Look up entry under VID_PID_ Entry (VID: Vendor ID; PID: Product ID)
    • Does service indicate WinUSB or libusbK?
    • The mfg (Manufacturer) entry should show the synthesized oem###.inf, corresponding to (same date) oem###.inf under C:\Windows\INF\
  • One can check in Driver Store C:\Windows\System32\DriverStore\FileRepository\ for a folder, with naming indicating the manufacturer and device, corresponding to prior installation of manufacturer’s driver.
  • Comprehensive Windows driver installation log at: C:\Windows\INF\setupapi.dev.log. Example excerpt showing involuntary rollback:
>>>  [Device Install (Hardware initiated) - USB\VID_2457&PID_104B\7&13b69c22&0&3]
>>>  Section start 2020/10/02 14:13:19.318
     utl: {Select Drivers - USB\VID_2457&PID_104B\7&13b69c22&0&3} 14:13:19.364
     utl:      Driver Node:
     utl:           Status         - Selected
     utl:           Driver INF     - oem37.inf (C:\WINDOWS\System32\DriverStore\FileRepository\ooi_flamenir.inf_amd64_c49d37bc221e3c4a\ooi_flamenir.inf)
     utl:           Class GUID     - {bad36dab-a3d2-4a0e-8b2e-da36202187d4}
     utl:           Driver Version - 04/11/2016,1.2.0.0
     utl:           Configuration  - USB\VID_2457&PID_104B
     utl:           Driver Rank    - 00FF0001
     utl:           Signer Score   - WHQL (0D000005)
     utl:      Driver Node:
     utl:           Status         - Outranked
     utl:           Driver INF     - oem48.inf (C:\WINDOWS\System32\DriverStore\FileRepository\ocean_optics_flame-nir128.inf_amd64_9d418d0d07e56955\ocean_optics_flame-nir128.inf)
     utl:           Class GUID     - {ecfb0cfd-74c4-4f52-bbf7-343461cd72ac}
     utl:           Driver Version - 11/30/2014,3.0.7.0
     utl:           Configuration  - USB\VID_2457&PID_104B [LUsbK_Device.NTamd64]
     utl:           Driver Rank    - 00FF0001
     utl:           Signer Score   - Authenticode (0F000000)