A Power BI Project saves your report and semantic model as plain text files in folders instead of one binary .pbix file. That lets you use Git, pull requests and automated checks, just like software teams do. Microsoft's September 2026 Message Center notice (MC1465770) announced general availability of developer mode and the PBIP format, with PBIR as the default report format.
The three formats in plain words
| Name | What it stores | Why it helps |
|---|---|---|
| PBIP | The project folder that holds both the report and the semantic model | Opens in Desktop; Git-ready |
| PBIR | The report: every page, visual and bookmark in its own JSON file | Small, readable diffs; fewer merge conflicts; each file has a public JSON schema |
| TMDL | The semantic model: tables, measures, relationships, roles as readable text | One file per table; easy to review line by line |
PBIR is not replacing PBIX. PBIX stays the main file format, and PBIX files now store their report data in PBIR format inside. PBIR-Legacy (the old single report.json) is still supported, but a report edited in current tools is upgraded to PBIR automatically.
What a project folder looks like
SalesProject/
├── Sales.Report/
├── Sales.SemanticModel/
├── .gitignore
└── Sales.pbip- The
.pbipfile is a pointer. Opening it opens the report and model together. It is optional: you can also opendefinition.pbirinside the report folder. - Desktop creates a
.gitignoreif none exists. It skips.pbi/localSettings.jsonand.pbi/cache.abf, which are local-only files such as the data cache. - One folder can hold several reports and models.
TMDL in five rules
- Indentation is structure. One tab per level. Wrong indentation is a parse error.
- Declare an object with its type and name, such as
table Ordersorcolumn 'Net Amount'. - Properties use a colon, such as
dataType: decimal. - A measure's formula follows an equals sign and may run over several indented lines.
- Descriptions use
///on the line directly above the object. Wrap names that contain spaces, dots, equals signs or colons in single quotes.
/// Sales fact table
table Orders
column 'Net Amount'
dataType: decimal
sourceColumn: NetAmount
summarizeBy: sum
measure 'Total Net' = SUM ( Orders[Net Amount] )
formatString: $ #,##0In a project, each table gets its own file in a tables folder. Other objects sit in model.tmdl, relationships.tmdl, expressions.tmdl, dataSources.tmdl, functions.tmdl (your user-defined functions from Lesson 1), and folders for roles, perspectives and cultures. A ref line keeps item order stable so unrelated changes do not show up in diffs.
Inside Desktop you can also edit the model as code in TMDL view, which is generally available. Use Preview to see a diff before you click Apply. TMDL view on the web is still in preview.
Step by step: from one file to a safe release
Part A: save as a project (Power BI Desktop)
- Open your report and choose File > Save as > Power BI Project (.pbip).
- Pick a short folder path. On Windows the default path limit is 260 characters.
- Do not save straight into OneDrive or SharePoint. Saving into a locally synced folder can cause sync problems.
Part B: put it in Git (VS Code)
- Open the project folder in VS Code and choose Source Control > Initialize Repository.
- Make the first commit with a clear message.
- Set Git's
autocrlfoption, because Desktop writes Windows line endings. - For each change, create a branch, save in Desktop, commit, and open a pull request.
If you edit project files outside Desktop, keep them as UTF-8 without BOM. Desktop notices outside saves and offers to apply them in one click. Reading is fully supported; writing works but, in rare cases, can leave the model inconsistent.
Part C: connect a workspace (Fabric portal)
- Connect a Fabric workspace to one branch of an Azure DevOps or GitHub repository. A workspace connects to a single branch.
- Give each developer a separate workspace on their own branch. Changes made directly in a shared workspace affect everyone using it. The other option is to work locally in Desktop and VS Code.
- Remember that Update always brings in the whole branch up to its latest commit. You cannot pick single items.
Part D: add quality gates (Azure DevOps)
- Turn on branch policies for
mainso nobody commits to it directly and every change needs a pull request. - Add a build pipeline to that policy. Microsoft's sample runs two jobs: Tabular Editor's Best Practice Analyzer checks the semantic model, and PBI Inspector checks the report.
- If a rule at a high severity fails, the pull request cannot be completed.
Microsoft notes that Tabular Editor and PBI Inspector are community tools it does not support. The approach also works with other tools.
Part E: deploy to Test and Prod
- Option 1, deployment pipelines: promote content from Dev to Test to Prod in Fabric. You can automate it with the Power BI REST APIs or the open-source Power BI automation tools extension for Azure DevOps.
- Option 2,
fabric-cicd: a Microsoft-backed open-source Python library that publishes semantic models and reports from a PBIP repo into a workspace. It orders items by dependency (models before reports) and swaps environment values from aparameter.ymlfile, for example different workspace or lakehouse IDs for dev and prod. In Microsoft's sample pipelines, the branch name picks the environment. - For automated runs, use a service principal with at least the Contributor role on the target workspaces. Your tenant admin must enable service principals for Fabric APIs.
Why PBIR helps in daily work
- Because every visual and page is its own file, Git shows exactly what changed and merges cleanly.
- You can copy visuals, pages or bookmarks between reports.
- You can run batch changes by script, such as setting a default page on every report.
- VS Code can check your edits against the public JSON schema, and Desktop validates changed files when it opens the project.
Watch-outs
- Sensitivity labels and report page synonyms (the linguistic schema) are not supported in projects.
- Files with undocumented formats, such as
mobileState.jsonanddiagramLayout.json, should not be edited by hand. - Desktop-optimized-for-Report-Server does not support PBIP.
- Converting between PBIX and PBIP only works through Save as in Desktop, not by script.
- Row-level security role members and incremental refresh partitions cannot be read or set through the Fabric REST API.
- Desktop publish also uploads the local data cache. Git integration and the Fabric APIs deploy only metadata, so refresh the model after the first deployment.
- The first deployment of a model that has data sources needs credentials set by hand in the Fabric portal. Later deployments reuse them.
- Check each item's status on the Git integration page. Some Power BI items there are labelled preview.
- Admins: the tenant setting that converted reports to PBIR is being removed, because PBIR is no longer opt-in.
Official sources
- Power BI Desktop projects (PBIP)
- Power BI enhanced report format (PBIR)
- TMDL overview and TMDL view in Power BI Desktop
- Fabric Git integration: introduction and Manage branches
- PBIP and Azure DevOps build pipelines for validation
- Deploy PBIP projects with fabric-cicd
- Automate deployment pipelines
- Power BI blog: PBIR becomes the default report format
- Message Center notice MC1465770, General Availability of Power BI developer mode (mirror of the Microsoft 365 notice)