pbixray Python Library

pbixray is an open source Python library for parsing Power BI .pbix files directly from Python, without Power BI Desktop or a live Analysis Services connection.

It is designed for developers who need to inspect semantic models, extract metadata, read Power Query logic, and work with the internals of PBIX files programmatically. The same API also supports Excel .xlsx files that contain embedded PowerPivot models.

pbixray is read-only: it returns pandas DataFrames and requires no network access and no Power BI or Excel install. File type (PBIX vs XLSX) is auto-detected from the file contents — the same API works either way.

Install

pip install pbixray

Quick Start

from pbixray import PBIXRay

model = PBIXRay("path/to/your_report.pbix")

print(model.tables)
print(model.metadata)
print(model.power_query)
print(model.dax_measures)
print(model.relationships)

Supported Inputs

• Power BI .pbix files
• Excel .xlsx files with embedded PowerPivot models

Large Models (on-disk loading)

By default the entire decompressed data model is held in memory. For models whose uncompressed size approaches or exceeds available RAM, pass on_disk=True: the decompressed data is streamed to a temporary file and memory-mapped, so only the pages a requested table actually touches are faulted in. Use temp_dir to control where the spill file is created (it defaults to the system temp directory).

# Spill to disk + mmap instead of holding everything in RAM.
with PBIXRay("path/to/large.pbix", on_disk=True, temp_dir="/fast/scratch") as model:
    df = model.get_table("Sales")
# leaving the `with` block releases the mapping and removes the temp file

PBIXRay is also a context manager. Calling model.close() (or exiting the with block) deterministically releases the memory map and the metadata connection. When on_disk=False (the default) behavior is unchanged. Metadata (DAX, tmschema_*, etc.) is loaded lazily on first access, so simply opening a file is cheap.

Core Properties

These properties expose the most useful parts of a model as Python values or pandas DataFrames.

Common Examples

List tables

print(model.tables)

Read Power Query / M code

power_query = model.power_query
print(power_query[["TableName", "Expression"]])

Inspect measures

measures = model.dax_measures
print(measures[["TableName", "Name", "Expression"]])

Inspect calculated columns

columns = model.dax_columns
print(columns[["TableName", "ColumnName", "Expression"]])

Inspect relationships

relationships = model.relationships
print(
    relationships[
        [
            "FromTableName",
            "FromColumnName",
            "ToTableName",
            "ToColumnName",
            "Cardinality",
            "IsActive",
        ]
    ]
)

Inspect row-level security

rls = model.rls
print(rls[["RoleName", "TableName", "FilterExpression"]])

Read a table’s contents

sales = model.get_table("Sales")
print(sales.head())

To decode only a subset of columns from a wide table (decoding the others is skipped), pass columns:

sales = model.get_table("Sales", columns=["ProductKey", "Sales"])

Dictionary decode runs on a native Huffman kernel (xmhuffman) and fans out across cores automatically for large dictionaries.

Data Model Details

pbixray can be used both as a quick inspection tool and as a lower-level metadata extraction library.

Use it to:

• enumerate tables and columns in a semantic model
• inspect DAX calculated tables, measures, and calculated columns
• extract Power Query and M parameter definitions
• audit relationships, referential settings, and cross-filtering behavior
• review row-level security rules
• measure model size and storage statistics

Tabular Model Schema Endpoints

pbixray also exposes direct equivalents of all 38 Analysis Services $System.TMSCHEMA_* DMVs by reading the embedded SQLite metadata database inside the PBIX. These endpoints are PBIX-only — on XLSX files they return empty DataFrames.

TMSCHEMA examples

# List all columns with table names and hidden flags
print(model.tmschema_columns[["TableName", "Name", "DataType", "IsHidden"]])

# Inspect incremental refresh policies
print(model.tmschema_refresh_policies)

# Inspect security role memberships
print(model.tmschema_role_memberships)

PBIX vs XLSX Capability Matrix

Both PBIX and XLSX (PowerPivot) files use the same API, but coverage differs. “Empty” below means a zero-row DataFrame — never None and never an exception.

Notes and Gotchas

• RowNumber is dropped from get_table() output — it is a VertiPaq internal storage position, not user data.
• Row order is storage order, not insertion order. VertiPaq sorts rows by lowest-cardinality columns first for RLE compression. Two calls are stable, but order will differ from a CSV exported from Excel. For row equivalence, compare as multisets: df.sort_values(list(df.columns)).reset_index(drop=True).
• Unknown table name → empty DataFrame, not an exception. Validate against model.tables if you need to detect bad names.
• model.tables returns a numpy array, not a Python list. It iterates fine, but model.tables == [...] won’t work as a plain equality check.
• XLSX calculated columns can have a display name different from the internal storage name (e.g. Category ↔ CalculatedColumn1). pbixray resolves these so schema.ColumnName and get_table() use the display name.
• No streaming. get_table() materializes the whole table into a DataFrame, so large fact tables can be memory-heavy. Use on_disk=True and the columns argument to keep memory in check.

Out of Scope

pbixray is a read-only data-model extractor. It does not:

• write, modify, or repack PBIX/XLSX files
• evaluate DAX — measure and calculated-column expressions are returned as source text only
• run a query engine (no DAX/MDX/M evaluation against the model)
• connect to Power BI Service, Analysis Services, datasets, gateways, or workspaces
• refresh the model
• parse the report layer (visuals, pages, bookmarks, themes) — data model only
• support .pbit, .pbids, or .pbip formats — only .pbix and .xlsx with an embedded PowerPivot model

Requirements

• Python 3.8+ (tested through 3.13)
• Runtime dependencies: xpress8, xpress9, xmhuffman, kaitaistruct, numpy, pandas, apsw
• No Power BI Desktop required
• Works on macOS, Linux, and Windows

Links

• GitHub — hugoberry/pbixray
• PyPI — pbixray
• Interactive Demo