[](https://github.com/underloam/xbbg/actions/workflows/ci-rust.yml)
[](https://discord.gg/P34uMwgCjC)
**Python** [](https://pypi.org/project/xbbg/) [](https://anaconda.org/conda-forge/xbbg) [](https://pypi.org/project/xbbg/) [](https://pepy.tech/projects/xbbg) [](https://pepy.tech/projects/xbbg)
**JavaScript** [](https://www.npmjs.com/package/@xbbg/core) [](https://www.npmjs.com/package/@xbbg/core) [](https://www.npmjs.com/package/@xbbg/core)
**Rust** [](https://crates.io/crates/xbbg_core) [](https://crates.io/crates/xbbg_core) [](https://crates.io/crates/xbbg_core)
**Links:** [Documentation](https://xbbg.org/) · [Quickstart](#quickstart) · [Configuration](#configuration-and-engines) · [Examples notebook](py-xbbg/examples/xbbg_jupyter_examples.ipynb) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)
---
Latest release: xbbg==1.6.0 (release: [notes](https://github.com/underloam/xbbg/releases/tag/v1.6.0))
> This `main` branch is the Rust-powered v1 release. For the legacy pure-Python line, use [`release/0.x`](https://github.com/underloam/xbbg/tree/release/0.x).
> **Important:** xbbg is an independent open-source project. It is not affiliated with, endorsed by, sponsored by, or approved by Bloomberg Finance L.P. or its affiliates. Bloomberg, Bloomberg Terminal, B-PIPE, BQL, and related names are trademarks or service marks of their respective owners. xbbg does not grant access to Bloomberg services, data, software, licenses, credentials, or entitlements; users must obtain and use those separately under their own Bloomberg agreements and applicable policies.
## Contents
- [What is xbbg?](#what-is-xbbg)
- [Why xbbg?](#why-xbbg)
- [Installation](#installation)
- [Quickstart](#quickstart)
- [Exchange auctions and imbalance](#exchange-auctions-and-imbalance)
- [JavaScript and Node](#javascript-and-node)
- [Configuration and engines](#configuration-and-engines)
- [Common API surface](#common-api-surface)
- [Entitlement IDs](#entitlement-ids)
- [Delayed data](#delayed-data)
- [Output backends](#output-backends)
- [Async usage](#async-usage)
- [Subscriptions: raw, tick mode, and all fields](#subscriptions-raw-tick-mode-and-all-fields)
- [MCP server](#mcp-server)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Project links](#project-links)
## What is xbbg?
xbbg is a Bloomberg client with Python as the primary surface and companion JavaScript/Node bindings, all backed by a shared Rust engine for request execution, response parsing, Arrow-shaped data movement, async workers, typed errors, and diagnostics.
Use xbbg when you already have Bloomberg access and want higher-level helpers for common request patterns, plus an escape hatch for lower-level Bloomberg service requests.
Core scope:
- request helpers for BDP, BDS, BDH, intraday bars, ticks, BQL, BEQS, BSRCH, BQR, BTA, YAS, and related analytics
- local Bloomberg Desktop API / DAPI by default
- configuration for managed Bloomberg environments, including B-PIPE/SAPI, ZFP leased lines, TLS, failover hosts, SOCKS5, and SDK logging
- sync and async Python APIs backed by the same engine
- output as Narwhals, native xbbg Arrow carriers, PyArrow, pandas, Polars, DuckDB, and other optional Narwhals-backed libraries
- JavaScript/Node bindings in [`js-xbbg`](js-xbbg/README.md)
## Why xbbg?
xbbg's project goal is direct: be the most complete, technically advanced, and performance-focused open-source Bloomberg client for Python workflows, while staying independent of Bloomberg and requiring users to bring their own authorized Bloomberg access.
The short version: if all you need is a tiny one-off `bdp()` wrapper, several packages can work. xbbg is built for the path where that notebook later grows into intraday data, BQL, streaming, B-PIPE/SAPI, ZFP, async services, typed errors, diagnostics, and non-pandas data pipelines.
| Capability | xbbg | raw `blpapi` | pdblp / blp | bbg-fetch | polars-bloomberg |
| --- | --- | --- | --- | --- | --- |
| BDP/BDS/BDH helpers | yes | manual SDK code | yes | yes | partial |
| Intraday bars and ticks | yes | manual SDK code | limited / no | no | partial |
| Streaming subscriptions | yes | manual SDK code | no | no | no |
| BQL, BEQS, BSRCH, BQR, YAS, BTA | broad helper coverage | manual SDK code | limited | limited | partial |
| DAPI, SAPI/B-PIPE, ZFP, TLS, failover, SOCKS5 | configurable engine support | manual SDK code | limited | limited | limited |
| Async worker pools and isolated subscription sessions | yes | application-owned | no | no | no |
| Rust request/parsing engine with Arrow-shaped output | yes | no | no | no | no |
| Output backends beyond pandas | Narwhals, native, PyArrow, pandas, Polars, DuckDB | application-owned | pandas-first | pandas-first | Polars-first |
| Typed errors, diagnostics, field cache, testing helpers | yes | application-owned | limited | limited | limited |
| Usable install footprint (Windows x64, Python 3.14) | xbbg 1.6.0 + narwhals 2.27.1, no `blpapi` = 19.127 MiB | blpapi 3.26.8.1 = 14.702 MiB | pdblp 0.1.8 + pandas 3.0.5 + numpy 2.5.3 + blpapi 3.26.8.1 = 130.816 MiB / blp 0.0.4 + pandas 3.0.5 + numpy 2.5.3 + blpapi 3.26.8.1 = 131.002 MiB | bbg-fetch 3.2.0 + pandas 3.0.5 + numpy 2.5.3 + blpapi 3.26.8.1 = 130.863 MiB | polars-bloomberg 0.6.0 + polars 1.44.2 + blpapi 3.26.8.1 = 191.118 MiB |
## Installation
```cmd
pip install xbbg
```
Conda users can install the conda-forge build:
```cmd
conda install -c conda-forge xbbg
```
`blpapi` is **not** required as a Python dependency. xbbg only needs Bloomberg's shared runtime library
(`blpapi3_64.dll` on Windows, `libblpapi3_64.so` on macOS/Linux), which can come from Bloomberg
Terminal/DAPI, a managed Bloomberg C++ SDK install, or Bloomberg's official `blpapi` wheel. Installing
the wheel is just the easiest discovery path for many users:
```cmd
pip install blpapi --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/
```
Supported Python versions: **3.11 through 3.15**.
Requirements and notes:
- You need an authorized Bloomberg environment: local Terminal/DAPI, SAPI/B-PIPE, or ZFP, depending on your setup.
- If you build from source, stage the Bloomberg C++ SDK with `bash ./scripts/sdktool.sh` on macOS/Linux or `.\\scripts\\sdktool.ps1` on Windows PowerShell.
- If you manage the SDK yourself, set `BLPAPI_ROOT` or use `xbbg.set_sdk_path(...)`.
- On Windows Terminal installs, xbbg automatically probes DAPI runtime roots such as `C:\blp\DAPI` and `C:\Program Files (x86)\Bloomberg\Blp\DAPI` before requiring manual configuration.
- Linux wheels are `manylinux_2_28` (x86_64): any distro with glibc ≥ 2.28 works — RHEL/Alma/Rocky 8+, Debian 10+, Ubuntu 20.04+, Amazon Linux 2023.
- Optional dataframe conversions are installed separately: `xbbg[pyarrow]`, `xbbg[pandas]`, `xbbg[polars]`, or `xbbg[duckdb]`.
Verify the install:
```python
import xbbg
print(xbbg.__version__)
print(xbbg.get_sdk_info())
```
## Quickstart
```python
from xbbg import blp
# Reference data
prices = blp.bdp(["AAPL US Equity", "MSFT US Equity"], "PX_LAST")
# Historical data
hist = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31")
# Intraday bars
bars = blp.bdib("TSLA US Equity", dt="2024-01-15", interval=5)
```
Common request patterns:
```python
from xbbg import blp, ovr
# Multiple fields
info = blp.bdp("NVDA US Equity", ["Security_Name", "GICS_Sector_Name", "PX_LAST"])
# Bloomberg-style overrides
vwap = blp.bdp("AAPL US Equity", "Eqy_Weighted_Avg_Px", VWAP_Dt="20240115")
adj = blp.bdp("AAPL US Equity", "CRNCY_ADJ_PX_LAST", overrides=ovr(EQY_FUND_CRNCY="EUR"))
per_sec = blp.bdp(
["AAPL US Equity", "MSFT US Equity"],
"CRNCY_ADJ_PX_LAST",
overrides=ovr(
{
"EQY_FUND_CRNCY": "USD",
"AAPL US Equity": ovr(EQY_FUND_CRNCY="EUR"),
"MSFT US Equity": ovr(EQY_FUND_CRNCY="JPY"),
}
),
)
# Bulk data
holders = blp.bds("AAPL US Equity", "DVD_Hist_All", DVD_Start_Dt="20240101")
# BQL omits clientContext.appName unless an engine default or per-call value is set.
result = blp.bql("get(px_last) for('AAPL US Equity')")
# Override the engine BQL application context for this request.
# The application name below is synthetic; replace it with one authorized for your environment.
authorized_result = blp.bql(
"get(px_last) for('AAPL US Equity')",
app_name="example-authorized-bql-app",
)
# Field lookup
fields = blp.bflds(search_spec="vwap")
# Equity screening and constituents
screen = blp.beqs(screen="MyScreen", asof="2024-01-01")
members = blp.index_members("SPX Index", asof="2024-01-02")
# Workflow helpers
active = blp.active_futures("ESA Index", "2024-01-15")
surface = blp.vol_surface("SPX Index", start_date="2024-01-02", end_date="2024-01-05")
resolved = blp.resolve_isins(["US0378331005", "INVALIDISIN000"])
```
ETF NAV / iNAV workflows live in `xbbg.ext` and resolve Bloomberg's authoritative
`ETF_NAV_TICKER` / `ETF_INAV_TICKER` relationships instead of guessing ticker suffixes:
```python
from xbbg import ext
# Relationship discovery: QQQ US Equity -> QQQNV Index / QXV Index,
# AT1 LN Equity -> null daily NAV / AT1IN Index (independently nullable)
rel = ext.etf_nav_relationships(["QQQ US Equity", "AT1 LN Equity"])
# Daily NAV/iNAV history: mapped Index targets price with PX_LAST; AT1's
# missing daily NAV falls back to the fund's FUND_NET_ASSET_VAL — see the
# nav_source_ticker / nav_source_field columns on every row
hist = ext.etf_nav_history(
["QQQ US Equity", "AT1 LN Equity"],
start_date="2026-06-01",
end_date="2026-07-01",
)
# Real-time iNAV: validates every mapping first, then subscribes to the
# resolved iNAV topics (here QXV Index) with LAST_PRICE by default
sub = await ext.asubscribe_etf_inav("QQQ US Equity")
async for table in sub:
print(table.to_pylist())
break
await sub.unsubscribe()
```
For longer walkthroughs and example output shapes, use the [examples notebook](py-xbbg/examples/xbbg_jupyter_examples.ipynb) or [xbbg.org](https://xbbg.org/).
## Exchange auctions and imbalance
Bloomberg publishes auction imbalance data (buy/sell imbalance, paired shares, indicative and theoretical prices, auction state) and auction results only on the listing where the auction runs. Composite tickers such as `SPY US Equity` return none of it from reference data and only part of it in streams, and a pricing-source suffix on an equity ISIN (`/isin/