Install & Compatibility
Where this runs
tested against v0.14.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
py 3.10
✕ build_error
✓ 59s
py 3.11
✕ build_error
✓ 55.6s
py 3.12
✕ build_error
✓ 55.4s
py 3.13
✕ build_error
✓ 57.4s
py 3.9
✕ build_error
✕ build_error
1203MB installed
● package 1203MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FabricDataFrame
✓ from sempy.fabric import FabricDataFrame
✗ from sempy.dataframe import FabricDataFrame
FabricDataFrame is part of the 'fabric' submodule, not directly under 'sempy'.
list_workspaces
✓ from sempy.fabric import list_workspaces
✗ import sempy.list_workspaces
Functions interacting with Fabric entities are typically found in the 'sempy.fabric' module.
read_table
✓ from sempy.fabric import read_table
✗ from sempy.data import read_table
Data reading functions for Fabric are in 'sempy.fabric'.
This quickstart demonstrates how to create a `FabricDataFrame` from a standard pandas DataFrame. It then attempts to use `sempy.fabric.list_workspaces()` to show interaction with Microsoft Fabric. Note that most `sempy.fabric` functions require execution within a Microsoft Fabric notebook environment with an authenticated session to function correctly.
import pandas as pd
from sempy.fabric import FabricDataFrame, list_workspaces
# Create a sample pandas DataFrame
df_pd = pd.DataFrame({
'ID': [1, 2, 3],
'Value': [100, 200, 150]
})
# Convert a pandas DataFrame to a FabricDataFrame
df_sempy = FabricDataFrame(df_pd)
print("--- FabricDataFrame created ---")
print(df_sempy.head())
print(f"Type: {type(df_sempy)}\n")
# Attempt to list Fabric workspaces
# This function (and most of sempy.fabric) requires an active Microsoft Fabric notebook environment
# and an authenticated session to execute successfully.
print("--- Attempting to list Fabric workspaces ---")
try:
workspaces = list_workspaces()
print(f"Successfully listed {len(workspaces)} workspaces.")
if workspaces:
print(f"First workspace: {workspaces[0]['display_name']}")
except Exception as e:
print(f"Failed to list workspaces. This is expected if not running in a Fabric notebook or without proper authentication.\nError: {e}")
Debug
Known issues
gotchaSemPy is primarily designed for and best utilized within Microsoft Fabric notebooks. Running its Fabric-specific functionalities (e.g., `sempy.fabric` functions) outside of this environment will typically fail due to authentication or environment dependencies.fixRun your SemPy code in a Microsoft Fabric notebook for full functionality. Ensure your environment has the necessary authentication configured if attempting to use outside Fabric.
affects: All versions
gotchaThe library primarily interacts with Power BI semantic models and their underlying data. It's not a general-purpose data manipulation library for arbitrary data sources, although it can work with pandas DataFrames as an entry point.fixUnderstand that SemPy's strength lies in its integration with Power BI semantic models. For general data tasks, consider using pandas directly or other libraries.
affects: All versions
breakingAs a pre-1.0 library (version 0.x.x), SemPy's API might experience breaking changes between minor versions. Always check the official documentation or release notes when upgrading.fixPin your `semantic-link-sempy` version in your `requirements.txt` (`semantic-link-sempy==0.14.0`) and thoroughly test your code after any upgrades.
affects: All 0.x.x versions
gotchaSemPy requires Python 3.10 or newer. Using older Python versions will result in installation or runtime errors.fixEnsure your Python environment is version 3.10 or higher. Upgrade your Python interpreter if necessary.
affects: <0.14.0 (requires >=3.10)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sempy'
The 'sempy' library is not installed in the current Python environment or is not accessible in the Python path.
fixpip install semantic-link-sempy
AttributeError: module 'sempy' has no attribute 'list_workspaces'
Functions like 'list_workspaces' are located within specific submodules of 'sempy', such as 'sempy.fabric', not directly under the top-level 'sempy' module.
fixfrom sempy.fabric import list_workspaces # or use sempy.fabric.list_workspaces(...)
Error: Could not connect to Power BI. Please ensure you are logged in to Fabric.
The current Microsoft Fabric session lacks the necessary authentication or permissions to connect to Power BI services or access the specified resources.
fixEnsure you are signed in to Microsoft Fabric with an account that has appropriate permissions for the Power BI workspace and dataset you are trying to access. Rerun the cell after verifying authentication.
AttributeError: 'function' object has no attribute 'to_pandas'
The 'to_pandas()' method is meant to be called on a 'fabric.DataFrame' object returned by a function, not on the function itself.
fixCall the function first to obtain the DataFrame, then apply 'to_pandas()'. For example: sempy.fabric.list_workspaces().to_pandas()
Upgrade
Version history
0.14.2latest on PyPI · released Jul 21, 2026
Audit
Dependencies
pandasrequiredCore data structure (FabricDataFrame extends pandas.DataFrame)
numpyrequiredNumerical operations, commonly used with pandas
pyarrowrequiredEfficient data transfer and serialization
msalrequiredMicrosoft Authentication Library for Python (for authentication to Fabric)
azure-identityrequiredAzure authentication client library (used for Fabric connectivity)