Install, connect, and diagnose

The problem

A working bbg-fetch setup has three independent layers: Python imports, a local Bloomberg Desktop API session, and entitlements for the requested security and field. This guide verifies each layer separately so an import success is not mistaken for data access.

Prerequisites and supported environment

The package metadata supports Python 3.10 and newer and classifies the live platform as Microsoft Windows. The repository CI independently builds the wheel, imports the package, runs tests, and builds the docs on Python 3.12; CI cannot validate a Bloomberg session or entitlement.

For live data, Bloomberg Professional must be running and logged in on the same machine. The request layer opens //blp/refdata on localhost:8194. It does not accept or store Bloomberg credentials. Entitlements belong to the logged-in Bloomberg user and can differ by security, field, bulk dataset, and analytics function.

Install the two packages

Bloomberg distributes blpapi separately; it is deliberately not a bbg-fetch runtime dependency. In a fresh virtual environment:

python -m pip install --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/ blpapi
python -m pip install bbg-fetch

Behind a corporate proxy, use an organisation-approved browser or package mirror to obtain a compatible wheel from Bloomberg’s official index, then install that local file:

python -m pip install C:\path\to\blpapi-wheel.whl

Do not use an unofficial blpapi package source. Bloomberg’s current platform and download guidance is available from its API Library.

Verify without opening a Bloomberg session

From a repository clone, run the authoritative terminal-free example:

python examples/quickstart_no_terminal.py

It imports blpapi and bbg_fetch, calls the public bbg_fetch.recover_option_forward computation on deterministic synthetic data, and prints Bloomberg connection: NOT TESTED. Its source is included on First success without a Terminal and is exercised by CI. This verifies imports and a public calculation only; it neither connects nor proves an entitlement.

Run one redacted live diagnostic

With Bloomberg Professional open and logged in, request one field for one publicly identifiable instrument. Record shape and schema, never returned values. The authoritative root script is examples/diagnose_terminal.py:

python examples/diagnose_terminal.py

Choose another entitled security or scalar field without editing the script:

python examples/diagnose_terminal.py --ticker "IBM US Equity" --field "SECURITY_NAME"

The expected contract is a one-row DataFrame indexed by the requested ticker with one normalized column, px_last. A successful run reports PASS, the dimensions, the normalized column name, and the index metadata. No licensed value is printed. A no-data result is classified separately because an invalid identifier, invalid field, or missing entitlement can have the same observable shape.

The script classifies import, session, timeout, no-data/field/security/ entitlement, and unexpected failures; it always closes the shared session.

Classify failures

ModuleNotFoundError: blpapi

The Bloomberg wheel is absent from this Python environment. Reinstall it from Bloomberg’s index or an approved local wheel. Installing bbg-fetch alone does not install it.

ConnectionError while starting the session

The package could not start the local session or open //blp/refdata. Confirm that Bloomberg Professional is running and logged in, then check local policy around localhost:8194. Import success does not test this.

TimeoutError after 60 seconds

The internal response collector waited 60 seconds without a final response. Any partial messages are attached to the exception as partial_messages for local diagnosis. Retry a one-security/one-field request before investigating large request sizes or connectivity.

Security or field warning, NaN, or an empty DataFrame

These are not uniquely diagnostic. Verify the full market-sector ticker, field mnemonic, date or expiry, request type, and user entitlement in the Terminal. bdp preserves the requested ticker row and expected field column with NaN when no scalar value arrives; bds can return a completely empty DataFrame.

Proxy or TLS installation error

This affects package download, not the localhost Desktop API session. Use the approved wheel path above or ask the organisation’s package/Bloomberg administrator; do not disable TLS verification or commit proxy secrets.

What can be checked without a Terminal

You can verify Python compatibility, wheel installation, imports, package version, top-level symbol presence, ticker string helpers, and the synthetic put-call-parity calculation. You cannot verify session startup, field validity, security resolution, freshness, or entitlement without the local Terminal context.

Failure-report checklist

A useful issue contains the bbg-fetch and Python versions, operating system, exception type, request shape (counts and field names), and whether the one-field diagnostic passed. Exclude credentials, proprietary values, screenshots containing licensed data, and raw responses.