Install & Compatibility
Where this runs
tested against v1.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.646s · 27.7MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 4.2s · import 0.579s · 30MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TardisClient
✓ from tardis_client import TardisClient
✗ from tardis_dev import TardisClient
TardisClient is specific to the deprecated 'tardis-client' package. The replacement 'tardis-dev' uses a top-level `replay` function instead.
Channel
✓ from tardis_client import Channel
✗ from tardis_dev.client import Channel
While 'Channel' exists in both, its usage pattern and containing package for replay functions differ in the new 'tardis-dev' package. For 'tardis-dev', 'Channel' is imported directly from 'tardis_dev'.
This quickstart demonstrates how to use the deprecated `tardis-client` to replay historical market data for BitMEX. It fetches trades for 'XBTUSD' and 'ETHUSD', and Level 2 order book data for 'XBTUSD' for a specific date range. An API key is typically required for full access to historical data.
import asyncio
import os
from tardis_client import TardisClient, Channel
async def replay_data():
api_key = os.environ.get('TARDIS_API_KEY', '')
# Note: For full historical access, an API key is required.
# Without an API key, only the first day of each month is accessible.
# The cache_dir is optional; default is os.tmpdir/.tardis-cache.
tardis_client = TardisClient(api_key=api_key, cache_dir="./tardis_cache")
print("Replaying BitMEX trades and order book for 2019-06-01...")
messages = tardis_client.replay(
exchange="bitmex",
from_date="2019-06-01",
to_date="2019-06-02", # Non-inclusive end date
filters=[
Channel(name="trade", symbols=["XBTUSD", "ETHUSD"]),
Channel("orderBookL2", ["XBTUSD"])
],
)
message_count = 0
async for local_timestamp, message in messages:
# local_timestamp is a Python datetime object
# message is the raw message object from the exchange real-time stream
if message_count < 5: # Print first 5 messages as an example
print(f"[{local_timestamp}] {message['symbol']}: {message['data_type']}")
message_count += 1
print(f"\nFinished replaying. Total messages received: {message_count}")
# Optionally clear the cache
# tardis_client.clear_cache()
if __name__ == "__main__":
# Set your API key as an environment variable or pass it directly
# os.environ['TARDIS_API_KEY'] = 'YOUR_TARDIS_API_KEY'
asyncio.run(replay_data())
Debug
Known issues
breakingThe `tardis-client` package is deprecated and frozen. No new features will be added, and future Python development continues under the `tardis-dev` package. Existing users should migrate.fixUninstall `tardis-client` (`pip uninstall tardis-client`) and install the new client (`pip install tardis-dev`). Update your import statements and usage patterns according to the migration guide: `https://docs.tardis.dev/python-client/migration-notice`.
affects: All versions of `tardis-client` (1.x.x)
gotchaAccess to full historical data requires a Tardis.dev API key. Without one, only the first day of each month is accessible.fixObtain an API key from Tardis.dev and pass it to the `TardisClient` constructor (or set the `TARDIS_API_KEY` environment variable). For `tardis-dev`, pass it directly to `replay()` or `download_datasets()`.
affects: All versions
gotchaPerforming blocking I/O operations (e.g., synchronous file writes) within the `asyncio` event loop used by `tardis-client` can cause `ConnectionResetError` or `EOFError` due to the event loop being blocked, leading to network connection timeouts.fixEnsure all I/O operations (especially file writes during data processing) are non-blocking or use asynchronous libraries (e.g., `aiofiles`) to avoid blocking the event loop. Clear the local `.tardis-cache` if issues persist.
affects: All versions
gotchaThe local file cache (`<os.tmpdir>/.tardis-cache` by default) can grow significantly, consuming disk space, especially during large historical data backfills.fixRegularly clear the cache using `tardis_client.clear_cache()` or configure a specific `cache_dir` that can be managed manually. The newer `tardis-machine` (Node.js component, not this Python client) offers `autoCleanup: true` for clearing cache after replay.
affects: All versions
Errors
Common errors & fixes
ConnectionResetError: [Errno 54] Connection reset by peer OR EOFError: Read up to 0 bytes from peer
These errors often occur when the Python `asyncio` event loop is blocked by synchronous (blocking) I/O operations, such as writing to files, preventing the network connection from being properly maintained.
fixReplace blocking file operations with their asynchronous equivalents (e.g., using `aiofiles`) or ensure I/O is offloaded to a separate thread/process to keep the `asyncio` event loop responsive. Clear the `.tardis-cache` directory.
HTTP status 401 Unauthorized
The API key provided is either missing, invalid, or does not have sufficient permissions for the requested data. For full historical data, an API key is always required.
fixEnsure you have a valid Tardis.dev API key. Pass it correctly to the `TardisClient` constructor using the `api_key` argument, or set it as the `TARDIS_API_KEY` environment variable. Verify the API key's permissions on the Tardis.dev website.
Upgrade
Version history
1.4.2latest on PyPI · released Mar 26, 2026
Audit
Dependencies
No dependency data recorded yet.