qutePandas | Setup Guide

📦 Prerequisites

Before you begin, ensure you have the following:

Python 3.8 or higher installed
pip (Python package installer)
An email address to register for a kdb+ license
Basic familiarity with command line/terminal

1 Obtain a kdb+ License

What is kdb+?

kdb+ is a high-performance time-series database that powers qutePandas. To use qutePandas, you need a free kdb+ license from KX Systems.

How to get your license:

Visit the KX Personal License Download Page:
https://kx.com/kdb-personal-edition-download/
Fill out the registration form with your details:
- Full name
- Email address (you'll receive the license here)
- Company/Organization (can be "Personal" or "Student")
- Country
Accept the terms and conditions
Click "Download"
Check your email inbox for a message from KX Systems
Download the license file (kc.lic or k4.lic) from the email

📧 Note: The license is typically sent within a few minutes. Check your spam folder if you don't see it in your inbox.

⚠️ Important: The license file is usually named kc.lic or k4.lic. Do not rename this file!

2 Install Dependencies

qutePandas relies on several high-performance libraries including PyKX, Pandas, NumPy, and PyArrow.

Installation steps:

Open your terminal or command prompt
Run the following command to install all required libraries:

pip install pykx pandas numpy pyarrow

💡 Tip: If you're using a virtual environment (recommended), make sure to activate it before running the pip install command.

Verify PyKX installation:

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

You should see a version number like 2.0.0 or higher.

3 Store Your License File

qutePandas needs to know where your kdb+ license is located. There are three recommended locations where you can store it:

Option 1: Project-Level (Recommended for Development)

Store the license in your project directory. This is ideal when working on a specific project.

Step-by-step:

Locate the kc.lic file you downloaded from your email (likely in your Downloads folder)
Navigate to your project root directory in terminal
Create a kdb_lic folder
Move the license file into this folder

macOS/Linux:

cd /path/to/your/project
                    mkdir kdb_lic
                    mv ~/Downloads/kc.lic kdb_lic/

Windows (Command Prompt):

cd C:\path\to\your\project
                    mkdir kdb_lic
                    move %USERPROFILE%\Downloads\kc.lic kdb_lic\

Windows (PowerShell):

cd C:\path\to\your\project
                    New-Item -ItemType Directory -Name kdb_lic
                    Move-Item $env:USERPROFILE\Downloads\kc.lic kdb_lic\

Your project structure should look like:

your_project/
├── kdb_lic/
│   └── kc.lic
├── your_script.py
└── ...

Option 2: User Home Directory (Recommended for Global Access)

Store the license in your home directory to use it across all your Python projects.

Step-by-step:

Locate the kc.lic file from your Downloads
Create a .qutepandas folder in your home directory
Move the license file into this folder

macOS/Linux:

mkdir -p ~/.qutepandas
                    mv ~/Downloads/kc.lic ~/.qutepandas/

Windows (Command Prompt):

mkdir %USERPROFILE%\.qutepandas
                    move %USERPROFILE%\Downloads\kc.lic %USERPROFILE%\.qutepandas\

Windows (PowerShell):

New-Item -ItemType Directory -Path $env:USERPROFILE\.qutepandas
                    Move-Item $env:USERPROFILE\Downloads\kc.lic $env:USERPROFILE\.qutepandas\

Option 3: Environment Variable (Advanced)

Set the QLIC environment variable to point to any directory containing your license.

macOS/Linux (add to ~/.bashrc or ~/.zshrc):

export QLIC=/path/to/your/license/directory

Windows (System Properties → Environment Variables):

Variable: QLIC
                    Value: C:\path\to\your\license\directory

✅ Recommendation: For most users, Option 2 (User Home Directory) is the best choice as it makes the license available to all your Python projects without cluttering individual project folders.

4 Install qutePandas

Now that PyKX and your license are set up, install qutePandas:

pip install qutePandas

📦 Note: If qutePandas is not yet published to PyPI, you can install it from the source:

pip install git+https://github.com/yourusername/qutePandas.git

Or clone and install locally:

git clone https://github.com/yourusername/qutePandas.git
                        cd qutePandas
                        pip install -e .

5 Verify Your Installation

Let's make sure everything is working correctly!

Quick Test Script

Create a new Python file (e.g., test_qutepandas.py) and add:

import qutePandas as qpd
                    import pandas as pd

                    qpd.connect()
                    print("✅ Successfully connected to kdb+!")

                    df = pd.DataFrame({
                    'name': ['Alice', 'Bob', 'Charlie'],
                    'age': [25, 30, 35],
                    'city': ['New York', 'London', 'Tokyo']
                    })

                    q_df = qpd.DataFrame(df)
                    print("✅ DataFrame created successfully!")

                    result = qpd.dropna(q_df, return_type='p')
                    print("✅ Operations working correctly!")
                    print("\nResult:")
                    print(result)

Run the script:

python test_qutepandas.py

Expected output:

✅ Successfully connected to kdb+!
                    ✅ DataFrame created successfully!
                    ✅ Operations working correctly!

                    Result:
                    name age city
                    0 Alice 25 New York
                    1 Bob 30 London
                    2 Charlie 35 Tokyo

🎉 Congratulations! If you see this output, qutePandas is installed and working correctly!

🔧 Troubleshooting Common Issues

Issue 1: "License Exception" Error

pykx.exceptions.LicenseException: A valid q license must be in a known location

Solution:

Verify your license file is named kc.lic or k4.lic
Check that the license is in one of these locations:
- ~/.qutepandas/kc.lic
- ./kdb_lic/kc.lic (in your project)
- Directory specified by QLIC environment variable
Manually set the license path before importing:
import os os.environ['QLIC'] = '/path/to/your/license/directory' import qutePandas as qpd

Issue 2: "ModuleNotFoundError: No module named 'pykx'"

Solution:

Make sure PyKX is installed: pip install pykx
If using a virtual environment, ensure it's activated
Try upgrading pip: pip install --upgrade pip

Issue 3: Connection Timeout

Solution:

Check your firewall settings
Ensure no other kdb+ processes are running on the default port
Try restarting your Python kernel/session

Issue 4: Import Errors on Windows

Solution:

Install Visual C++ Redistributable if not already installed
Ensure Python is added to your PATH
Try running your terminal/IDE as administrator

Complete Setup Guide

📋 Table of Contents

Option 1: Project-Level (Recommended for Development)

Option 2: User Home Directory (Recommended for Global Access)

Option 3: Environment Variable (Advanced)

Quick Test Script

Issue 1: "License Exception" Error

Issue 2: "ModuleNotFoundError: No module named 'pykx'"

Issue 3: Connection Timeout

Issue 4: Import Errors on Windows