# Installation

## Prerequisites

PyFTDI relies on PyUSB, which requires a native dependency: libusb 1.x.

The actual command to install depends on your OS and/or your distribution, see below

### Debian/Ubuntu Linux

    apt-get install libusb-1.0

On Linux, you also need to create a udev configuration file to allow user-space processes to access to the FTDI devices. There are many ways to configure udev, here is a typical setup:

    # /etc/udev/rules.d/11-ftdi.rules

    # FT232AM/FT232BM/FT232R
    SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6001", GROUP="plugdev", MODE="0664"
    # FT2232C/FT2232D/FT2232H
    SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", GROUP="plugdev", MODE="0664"
    # FT4232/FT4232H
    SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6011", GROUP="plugdev", MODE="0664"
    # FT232H
    SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6014", GROUP="plugdev", MODE="0664"
    # FT230X/FT231X/FT234X
    SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6015", GROUP="plugdev", MODE="0664"
    # FT4232HA
    SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6048", GROUP="plugdev", MODE="0664"

Note

Accessing FTDI devices with custom VID/PID

You need to add a line for each device with a custom VID / PID pair you declare, see Custom USB vendor and product IDs for details.

You need to unplug / plug back the FTDI device once this file has been created so that udev loads the rules for the matching device, or alternatively, inform the `udev` daemon about the changes:

    sudo udevadm control --reload-rules
    sudo udevadm trigger

With this setup, be sure to add users that want to run PyFtdi to the plugdev group, e.g.

    sudo adduser $USER plugdev

Remember that you need to log out / log in to get the above command effective, or start a subshell to try testing PyFtdi:

    newgrp plugdev

### Homebrew macOS

    brew install libusb

### Windows

Windows is not officially supported (i.e. not tested) but some users have reported successful installations. Windows requires a specific libusb backend installation.

#### Zadig

The probably easiest way to deal with libusb on Windows is to use Zadig

1. Start up the Zadig utility

2. Select `Options/List All Devices`, then select the FTDI devices you want to communicate with. Its names depends on your hardware, i.e. the name stored in the FTDI EEPROM.

> - With FTDI devices with multiple channels, such as FT2232 (2 channels) and FT4232 (4 channels), you must install the driver for the composite parent, not for the individual interfaces. If you install the driver for each interface, each interface will be presented as a unique FTDI device and you may have difficulties to select a specific FTDI device port once the installation is completed. To make the composite parents to appear in the device list, uncheck the `Options/Ignore Hubs or Composite Parents` menu item.

> - Be sure to select the parent device, i.e. the device name should not end with (Interface N), where N is the channel number.

>   - for example Dual RS232-HS represents the composite parent, while Dual RS232-HS (Interface 0) represents a single channel of the FTDI device. Always select the former.

3. Select `libusb-win32` (not `WinUSB`) in the driver list.

4. Click on `Replace Driver`

See also Libusb on Windows

## Python

### Python dependencies

Dependencies should be automatically installed with PIP.

> - pyusb >= 1.0.0, != 1.2.0

> - pyserial >= 3.0

Do not install PyUSB from GitHub development branch (`master`, …). Always prefer a stable, tagged release.

PyUSB 1.2.0 also broke the backward compatibility of the Device API, so it will not work with PyFtdi.

### Installing with PIP

PIP should automatically install the missing dependencies.

    pip3 install pyftdi

### Installing from source

If you prefer to install from source, check out a fresh copy from PyFtdi github repository.

    git clone https://github.com/eblot/pyftdi.git
    cd pyftdi
    # note: 'pip3' may simply be 'pip' on some hosts
    pip3 install -r requirements.txt
    python3 setup.py install

### Generating the documentation

Follow Installing from source then:

    pip3 install setuptools wheel sphinx sphinx_autodoc_typehints
    # Shpinx Read the Doc theme seems to never get a release w/ fixed issues
    pip3 install -U -e git+https://github.com/readthedocs/sphinx_rtd_theme.git@2b8717a3647cc650625c566259e00305f7fb60aa#egg=sphinx_rtd_theme
    sphinx-build -b html pyftdi/doc .

The documentation may be accessed from the generated `index.html` entry file.

### Post-installation sanity check

Open a shell, or a CMD on Windows

    python3  # or 'python' on Windows
    from pyftdi.ftdi import Ftdi
    Ftdi.show_devices()

should list all the FTDI devices available on your host.

Alternatively, you can invoke `ftdi_urls.py` script that lists all detected FTDI devices. See the Tools chapter for details.

> - Example with 1 FT232H device with a serial number and 1 FT2232 device with no serial number, connected to the host:

>       Available interfaces:
>         ftdi://ftdi:232h:FT1PWZ0Q/1   (C232HD-DDHSP-0)
>         ftdi://ftdi:2232/1            (Dual RS232-HS)
>         ftdi://ftdi:2232/2            (Dual RS232-HS)

Note that FTDI devices with custom VID/PID are not listed with this simple command, please refer to the PyFtdi API to add custom identifiers, i.e. see `pyftdi.ftdi.Ftdi.add_custom_vendor()` and `pyftdi.ftdi.Ftdi.add_custom_product()` APIs.

## Custom USB vendor and product IDs

PyFtdi only recognizes FTDI official vendor and product IDs.

If you have an FTDI device with an EEPROM with customized IDs, you need to tell PyFtdi to support those custom USB identifiers.

### Custom PID

To support a custom product ID (16-bit integer) with the official FTDI ID, add the following code before any call to an FTDI `open()` method.

    from pyftdi.ftdi import Ftdi

    Ftdi.add_custom_product(Ftdi.DEFAULT_VENDOR, product_id)

### Custom VID

To support a custom vendor ID and product ID (16-bit integers), add the following code before any call to an FTDI `open()` method.

    from pyftdi.ftdi import Ftdi

    Ftdi.add_custom_vendor(vendor_id)
    Ftdi.add_custom_product(vendor_id, product_id)

You may also specify an arbitrary string to each method if you want to specify a URL by custom vendor and product names instead of their numerical values:

    from pyftdi.ftdi import Ftdi

    Ftdi.add_custom_vendor(0x1234, 'myvendor')
    Ftdi.add_custom_product(0x1234, 0x5678, 'myproduct')

    f1 = Ftdi.create_from_url('ftdi://0x1234:0x5678/1')
    f2 = Ftdi.create_from_url('ftdi://myvendor:myproduct/2')

Note

Remember that on OSes that require per-device access permissions such as Linux, you also need to add the custom VID/PID entry to the configuration file, see Linux installation `udev` rule file.