KDB-X Python installation guide

This page explains how to install KDB-X Python on your machine.

License

KDB-X Python is released under a dual license covering the files within the KDB-X Python repository as outlined here.

Acceptance of license terms:

By downloading, installing, or using KDB-X Python, you acknowledge and agree that you have read, understood, and accept the license link and will adhere to its terms.

Pre-requisites

Before you start, make sure you have:

• Python (versions 3.9-3.14)
• pip

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

Supported environments

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

• Linux (manylinux2014_x86_64, manylinux2014_aarch64) with CPython 3.9-3.14
• macOS (macosx_10_15_x86_64, macosx_10_15_arm64) with CPython 3.9-3.14
• Windows (win_amd64) with CPython 3.9-3.14

We provide assistance to user-built installations of KDB-X Python only on a best-effort basis.

1. Install KDB-X Python

You can install KDB-X Python from three sources:

Installing in air-gapped environments

If you are installing in a location without internet connection you may find this section useful.

Install KDB-X Python from PyPIInstall KDB-X Python from AnacondaInstall KDB-X Python from GitHubInstall KDB-X Python from UVInstall KDB-X Python from pipx

Ensure you have a recent version of pip:

pip install --upgrade pip

Then install the latest version of KDB-X Python with the following command:

pip install --upgrade pykx

For Linux x86 and arm-based architectures, you can install KDB-X Python from the kx channel on Anaconda as follows:

conda install -c kx KDB-X Python

Type y when prompted to accept the installation.

Clone the pykx repository:

git clone https://github.com/kxsystems/pykx

Enter the cloned repository and install KDB-X Python using pip:

cd pykx
pip install .

Ensure you have uv installed, instructions can be found here.

Then install the latest version of KDB-X Python with the following command:

uv pip install pykx

Ensure you have pipx installed, installation guide can be found here.

Then install KDB-X Python using the flag to install dependencies:

pipx install pykx --include-deps

This will create a virtual environment to run KDB-X Python in, make sure you activate this to access the package.

At this point you have partial access to KDB-X Python. To gain access to all KDB-X Python 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 KDB-X Python functionalities, you need to download and install a KDB-X license. To obtain a license, go to the KX Developer Center.

2.a Install an existing license in Python

Follow the steps below to install a license for KDB-X Python:

1. Start your Python session:

   $ python

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

   >>> import pykx as kx
   
   Thank you for installing KDB-X Python!
   
   We have been unable to locate your license for KDB-X Python. Running KDB-X Python in unlicensed mode has reduced functionality.
   Would you like to install a license? [Y/n]:

3. Indicate whether you have access to an existing KDB-X Python enabled license or not, type Y if you have a license:

   Do you have access to an existing license for KDB-X Python that you would like to use? [N/y]:

4. Choose the desired method to activate your license by typing 1 or 2 as appropriate:

   Please select the method you wish to use to activate your license:
   [1] Provide the location of your license file
   [2] Paste the license key

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

   12

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

   Specify the license type:

   Please confirm the license type:
   [1] kc.lic - The default
   [2] k4.lic - Used in some scenarios

   Then paste your license key and hit enter:

   Provide your kc.lic license key (base64 encoded string) :

6. Validate the correct installation of your license:

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

2.b Install license with environment variables

For environment-specific flexibility, there are two ways to install your license: by using a file or by copying text. Click on the tabs below, read the instructions, and choose the method you wish to follow:

Using a fileUsing text

1. Download your license file.

2. Set an environment variable pointing to the folder with the license file. (Learn how to set environment variables from here).

   • Variable Name: QLIC
   • Variable Value: /user/path/to/folder

1. Copy the base64 encoded contents of your license key provided.

2. On your computer, set an environment variable with the contents of your kc.lic license key named KDB_LICENSE_B64. Or use KDB_K4LICENSE_B64 if you have an older k4.lic license key. (Learn how to set environment variables from here).

   • Variable Name: KDB_LICENSE_B64 / KDB_K4LICENSE_B64
   • Variable Value: <copied license key>

To validate if you successfully installed your license with environment variables, start Python and import KDB-X Python as follows:

$ python
>>> import pykx as kx
>>> kx.q.til(5)
pykx.LongVector(pykx.q('0 1 2 3 4'))

Tip: automatic license renewal setup

When your license nears its expiry date, you can set KDB-X Python to automatically renew it. To do this, modify the environment variable KDB_LICENSE_B64 or KDB_K4LICENSE_B64 with your new license information. When KDB-X Python initializes with the expired license, it will attempt to overwrite it with the new value:

$python
>>> import pykx as kx
Initialisation failed with error: exp
Your license has been updated using the following information:
Environment variable: 'KDB_K4LICENSE_B64'
License write location: /user/path/to/license/k4.lic

3. Verify KDB-X Python installation

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

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

This command should display the installed version of KDB-X Python.

Dependencies

Expand for Required and Optional KDB-X Python dependencies

Required

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

• pandas>=1.2; python_version>'3.8'
• numpy>=1.22; python_version<'3.11'
• numpy>=1.23; python_version=='3.11'
• numpy>=1.26; 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 KDB-X Python uses these libraries:

  • NumPy: converts data from pykx objects to NumPy equivalent Array/Recarray style objects; direct calls to NumPy functions such as numpy.max with pykx 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 pykx objects to ensure that the offsets are accurately applied.
  • toml: for configuration parsing and management, with config-KDB-X Python as outlined here.
  • dill: used in the serialization and deserialization of Python objects when interfacing between q and Python processes using remote functions or real-time capture functionality.

Optional

Optional Python dependencies:

• pyarrow >=3.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]
• 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 Python uses these libraries:

• PyArrow: converts pykx objects to and from their PyArrow equivalent table/array objects.
• find-libpython: provides the libpython.{so|dll|dylib} file required by KDB-X 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 KDB-X Python equivalents.

Optional non-Python dependencies:

• libssl for TLS on IPC connections.
• libpthread on Linux/MacOS when using the PYKX_THREADING environment variable.

Troubleshooting and Support

If you encounter any issues during the installation process, refer to the following sources for assistance:

• Visit our troubleshooting guide.
• Ask a question on the KX community at learninghub.kx.com.
• Use Stack Overflow and tag pykx or kdb depending on the subject.
• Go to support.

Asset Information

Platform	Mode	File	Version
Linux ARM	KDB-X	libq.so	5.0.20260501
Linux x86	KDB-X	libq.so	5.0.20260501
Mac ARM	KDB-X	libq.dylib	5.0.20260501
Mac x86	KDB-X	libq.dylib	5.0.20260501
Windows	KDB-X	q.dll/q.lib	5.0.20260501
Linux ARM	Unlicensed	libe.so	2023.11.22
Linux x86	Unlicensed	libe.so	2023.11.22
Mac ARM	Unlicensed	libe.so	2023.11.22
Mac x86	Unlicensed	libe.so	2023.11.22
Windows	Unlicensed	e.dll/e.lib	2024.08.21

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 provided by KDB-X Python.

Do I need a q executable?

For the majority of functionality provided by KDB-X Python you do not explicitly need access to a q executable. Users within a Python process who do not have a q executable will be 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 with KDB-X Python data

If however you need to make use of the Real-Time Capture functionality you will need access to a q executable. Fundamentally the capture and persistence of real-time data and the application of analytics on this streaming data is supported via deployment of code on q processes.

Configuring KDB-X Python to use an existing executable

By default, when initializing a q process within Real-Time Capture workflows, KDB-X Python attempts to call q directly. However, this approach can be unreliable when the Python subprocess module is used to launch the process. To ensure consistency, configure the environment to explicitly reference the full path to your q 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

Installing an executable

Go to KDB-X and follow the instructions.

Installing in an air-gapped environment

Installing Python libraries in air-gapped environments requires users to first download the Python wheel files for the libraries you need to install.

Build using the same environment as you're installing

When downloading the .whl files and dependencies make sure you are using the same OS and Python version as you will be when installing in your isolated environment.

Prepare the installation package from an internet-enabled system in one of the following ways:

1. Download the .whl file for the OS, library version and Python version you are intending to use on the air-gapped environment. These files can be sourced from here.

2. Generate the .whl file from a git clone of the KDB-X Python repository. An example of this is as follows:

   $ git clone https://github.com/kxsystems/pykx
   $ cd pykx
   $ pip install build
   # The below will install the `.whl` to a `dist/` folder
   $ python -m build .

   After downloading the *.whl file locally, you can retrieve and save its required dependencies using the following command:

   $ pip download dist/*.whl

Copy the content of your dist/ folder to an external storage device (USB-key etc.) and upload the .whl files to your air-gapped device.

Install the wheels which for simplicity are stored at a location /opt/airgap/wheels

pip install --no-cache /opt/airgap/wheels/*

Verify KDB-X Python can use the executable

Verifying that KDB-X Python has access to the executable can be done through execution of the function kx.util.start_q_subprocess and requires either your configuration file or environment variables to include PYKX_Q_EXECUTABLE. This is outlined here.

>>> import pykx as kx
>>> server = kx.util.start_q_subprocess(5052)
>>> conn = kx.SyncQConnection(port=5052)     # Connect to subprocess
>>> conn('1+1')
pykx.LongAtom(pykx.q('2'))
>>> server.kill()

Next steps

That's it! You can now start using KDB-X Python in your Python projects:

• Quickstart guide
• Updating/Upgrading your license