KDB-X Python Install

This page explains how to setup Python for KDB-X.

Prerequisites

Before you start, make sure you have:

Recommended: a virtual environment with packages such as venv from the standard library.

Supported environments

KX only supports versions of KDB-X built by KX (installed from wheel files) for:

  • Linux (manylinux_2_17_x86_64, linux-arm64) with CPython 3.8 - 3.13
  • macOS (macosx_10_10_arm) with CPython 3.8 - 3.13
  • Windows (win_amd64) with CPython 3.8 - 3.13

1. Install KDB-X Python

You can install KDB-X Python from two sources:

Recommended: a virtual environment with packages such as venv from the standard library.

Install from PyPI

  1. Ensure you have a recent version of pip:

    Python

    Copy
    Copy
    pip install --upgrade pip

  2. Then install the latest version with the following command:

    Python

    Copy
    pip install --pre pykx

To gain access to all KDB-X features, follow the steps in the next section, otherwise go straight to 3. Verify KDB-X Python Installation.

2. Install a KDB-X license

To use all features, you must have a KDB-X license.

Install license in Python

Follow the steps below:

  1. Start your Python session:

    Python

    Copy
     $ python

  2. Import the library. When prompted to accept the installation, type Y or press Enter:

    Python

    Copy
     >>> import pykx as kx

     Thank you for installing PyKX!

     We have been unable to locate your license for PyKX. Running PyKX in unlicensed mode has reduced functionality.
     Would you like to install a license? [Y/n]:

  3. Indicate whether you have access to an existing enabled license or not, type N or press Enter to continue with accessing a new license:

    Python

    Copy
     Do you have access to an existing license for PyKX that you would like to use? [N/y]:

  4. Choose whether you wish to install a personal or commercial license, type Y or press Enter to choose a personal license

    Python

    Copy
     Is the intended use of this software for:
         [1] Personal use (Default)
         [2] Commercial use
     Enter your choice here [1/2]:

  5. When asked if you would like to apply for a license, type Y or press Enter. Select Personal license.

  6. Complete the form to receive your welcome email.

  7. Choose the desired method to activate your license by typing 1, 2, or 3 as appropriate.

    Python

    Copy
     Select the method you wish to use to activate your license:
         [1] Download the license file provided in your welcome email and input the file path (Default)
         [2] Input the activation key (base64 encoded string) provided in your welcome email
         [3] Proceed with unlicensed mode
     Enter your choice here [1/2/3]:

  8. Depending on your choice (1, 2, or 3), complete the installation by following the final step as below:

    For 1

    For 2

    For 3

    bash

    Copy
    Provide the download location of your license (for example, ~/path/to/kc.lic).         

    bash

    Copy
    Provide your activation key (base64 encoded string) provided with your welcome email:
                        

    bash

    Copy
    No further actions needed.
                        

  9. Validate the correct installation of your license.

    Python

    Copy
     >>> kx.q.til(10)
     pykx.LongVector(pykx.q('0 1 2 3 4 5 6 7 8 9'))

3. Verify KDB-X Python installation

To verify if you successfully installed KDB-X Python on your system, run:

PowerShell

Copy
python -c"import pykx as kx;print(pykx.__version__)"

This command should display the installed version.

Dependencies

Required and optional KDB-X Python dependencies:

Required

Optional

KDB-X Python depends on the following third-party Python packages:

  • pandas>=1.2, <2.0; python_version=='3.8'

  • pandas>=1.2, <=2.2.3; python_version>'3.8'

  • numpy~=1.22, <2.0; python_version=='3.11'

  • numpy~=1.23, <2.0; python_version=='3.11'

  • numpy~=1.26, <2.0; python_version=='3.12'

  • pytz>=2022.1

  • toml~=0.10.2

  • dill>=0.2.0

  • requests>=2.25.0

Note

All are installed automatically by pip when you install KDB-X Python.

Here's a breakdown of how these libraries are used:

  • NumPy: converts data from KDB-X Python objects to NumPy equivalent Array/Recarray style objects; direct calls to NumPy functions such as `numpy.max` with KDB-X Python objects relies on the NumPy Python API.

  • Pandas: converts KDB-X Python data to Pandas Series/DataFrame equivalent objects or to PyArrow data formats. Pandas is used as an intermediary data format.

  • pytz: converts data with timezone information to KDB-X Python objects to ensure that the offsets are accurately applied.

  • toml: for configuration parsing and management, with .pykx-config as outlined in configuration.

  • dill: use in the serialization and deserialization of Python objects when interfacing between kdb+ and Python processes using remote functions or real-time capture) functionality.

Optional Python dependencies:

  • pyarrow >=3.0.0, <19.0.0: install pyarrow extra, for example pip install pykx[pyarrow].

  • find-libpython ~=0.2: install debug extra, for example pip install pykx [debug].

  • ast2json ~=0.3: install with dashboards extra, for example pip install pykx [dashboards].

  • dill >=0.2: install via pip, with remote extra, for example pip install pykx [remote].

  • beautifulsoup4 >=4.10.0: install with help extra, for example pip install pykx [help].

  • markdown2 >=2.5.0: install with help extra, for example pip install pykx [help].

  • psutil >=5.0.0: install via pip, with streaming extra, for example pip install pykx [streaming].

  • torch >2.1: install via pip, with torch extra, for example pip install pykx[torch]

Here's a breakdown of how KDB-X uses these libraries:

  • PyArrow: converts KDB-X Python objects to and from their PyArrow equivalent table/array objects.

  • find-libpython: provides the libpython.{so|dll|dylib} file required by Python under q.

  • ast2json: required for KX Dashboards Direct integration.

  • psutil: facilitates the stopping and killing of a q process on a specified port allowing for orphaned q processes to be stopped, functionality defined here.

  • torch: required for conversions between torch.Tensor objects and their Python equivalents.

Optional non-Python dependencies:

  • libssl for TLS on IPC connections.

  • libpthread on Linux/MacOS when using the PYKX_THREADING environment variable.

Optional: Installing a q executable

The following section is optional and primarily required if you are looking to make use of the Real-Time Capture functionality.

Do I need a q executable?

For the majority of functionality you do not explicitly need access to a q executable. If you are in a Python process but do not have a q executable, you are able to complete tasks such as the following:

  • Convert data to/from Python types

  • Run analytics on in-memory and on-disk databases

  • Create databases

  • Query remote q processes via IPC

  • Execute numpy functions KDB-X data

If however you need to make use of the Real-Time Capture. functionality, you need access to a q executable.

Configuring KDB-X Python to use an existing executable

By default when attempting to start a q process for use within the Real-Time Capture workflows KDB-X Python attempts to call q directly. However, the following setup can be used to point more explicitly at your executable. If you already have a q executable, KDB-X Python can use this when initializing the Real-Time Capture APIs through the setting of the following in your configuration file or as environment variables:

Variable

Explanation

PYKX_Q_EXECUTABLE

Specifies the location of the q executable which should be called. Typically this will be QHOME/[lmw]64/q[.exe]

QHOME

The directory to which q was installed

Next steps

That's it! You can now start using KDB-X Python in your Python projects by visiting our tutorial.