Skip to content

Installation

This guide covers how to install qldata and its dependencies.

Requirements

  • Python 3.10+ (3.10, 3.11, or 3.12 recommended)
  • pip or another Python package manager

Installation Options

The default installation includes all core dependencies plus support for Binance, Bybit, and DuckDB storage:

pip install qldata

This installs:

  • Core data processing: pandas, numpy, pyarrow
  • Exchange adapters: python-binance, pybit
  • Database storage: duckdb
  • Live streaming: websockets, aiohttp
  • Utilities: tenacity (retry logic)

Minimal Installation

For lightweight deployments or when you only need core functionality:

pip install qldata[minimal]

This installs only:

  • pandas>=2.0.0
  • numpy>=1.24.0
  • python-dateutil>=2.8.0

Exchange-Specific Installation

Install support for specific exchanges only:

pip install qldata[binance]

Includes: python-binance, websockets

pip install qldata[bybit]

Includes: pybit

pip install qldata[exchanges]

Includes: python-binance, pybit, websockets

Feature-Specific Installation

pip install qldata[storage]

Includes: pyarrow, duckdb

pip install qldata[stream]

Includes: websockets, aiohttp

pip install qldata[all]

Includes all optional dependencies

Development Installation

For contributors and developers:

pip install qldata[dev]

This includes:

  • Testing: pytest, pytest-cov, pytest-asyncio
  • Linting: black, ruff, mypy
  • Documentation: mkdocs-material, mkdocstrings

Verify Installation

After installation, verify everything works:

import qldata as qd

# Check version
print(f"qldata version: {qd.__version__}")

# Quick test - fetch symbol info (no API key required)
try:
    info = qd.get_symbol_info("BTCUSDT", source="binance", category="spot")
    print(f"✓ Successfully connected to Binance")
    print(f"  Symbol: {info.symbol}")
    print(f"  Status: {info.status}")
except Exception as e:
    print(f"✗ Connection error: {e}")

Expected output:

qldata version: 0.3.0
✓ Successfully connected to Binance
  Symbol: BTCUSDT
  Status: TRADING

Configuration

Environment Variables

qldata uses the following optional environment variables:

Variable Description Default
QLDATA_DATA_DIR Directory for cached data ~/.qldata
QLDATA_CACHE_ENABLED Enable/disable caching true
QLDATA_VALIDATION_ENABLED Enable/disable data validation true
BINANCE_API_KEY Binance API key (for private endpoints) None
BINANCE_API_SECRET Binance API secret None
BYBIT_API_KEY Bybit API key (for private endpoints) None
BYBIT_API_SECRET Bybit API secret None

API Keys Not Required for Public Data

For most use cases (market data, historical bars, public trades), API keys are not required. Keys are only needed for private endpoints like account balances or order placement.

Python Configuration

You can also configure qldata programmatically:

import qldata as qd

# Configure at runtime
qd.config(
    data_dir="./my_data",
    cache_enabled=True,
    validation_enabled=True
)

# Check current configuration
print(f"Data directory: {qd.get_data_dir()}")
print(f"Cache enabled: {qd.is_cache_enabled()}")
print(f"Validation enabled: {qd.is_validation_enabled()}")

Troubleshooting

Common Issues

ImportError: No module named 'binance'

You have the minimal installation. Install Binance support: 

pip install qldata[binance]

ImportError: No module named 'pybit'

You have the minimal installation. Install Bybit support: 

pip install qldata[bybit]

SSL Certificate Errors

Some networks block WebSocket connections. Try:

  1. Check your firewall/VPN settings
  2. Update certifi: pip install --upgrade certifi
  3. If in China, consider using proxy settings
Connection Timeout Errors

Exchange APIs may be slow or rate-limited:

  1. Check your internet connection
  2. Try a different exchange (Binance vs Bybit)
  3. Wait a few minutes if rate-limited

Getting Help

Next Steps

Ready to start using qldata?