Almanac
Microsoft/power-biPower Platform

Consultant KB for Microsoft Power BI: semantic models, DAX and modelling, Power Query and dataflows, reports and visuals, the service and workspaces, capacity and performance, embedding and integration, governance and security, ALM and deployment, and licensing, plus cross-cutting decision guides. Scoped to Power BI, with Microsoft Fabric covered where it touches Power BI directly. Implementation notes, configuration decisions and the gotchas that bite on real projects. Populated by the daily author agent from the Power BI release plans, docs repo and product blog, plus the author's own consultant notes.

power-bi/09-alm-and-deployment/feature-pbip-and-project-files.md
feature-pbip-and-project-files.mdv1 · history
CurrentApplies to ServiceUpdated last monthSource Microsoft Learn ↗

What it does

A save format for Power BI Desktop that writes the report and semantic model out as plain text files in a folder structure instead of a single binary .pbix. The semantic model is serialised as TMDL, the report as PBIR, and the whole thing is meant to sit in a Git repo and be read by humans.

Key facts

  • PBIP is still in preview and has to be turned on under File > Options and settings > Options > Preview features before the save option appears.
  • Saving a project produces <name>.Report/ and <name>.SemanticModel/ folders, a <name>.pbip pointer file and a .gitignore. Desktop only writes the .gitignore if one doesn't already exist in that folder or a parent repo.
  • The default .gitignore excludes **/.pbi/localSettings.json and **/.pbi/cache.abf — the cached data, in other words. What lands in Git is metadata, not the imported rows.
  • TMDL is a YAML-shaped text syntax with full parity to the Tabular Object Model, using indentation to express parent-child structure and one file per model object. Model folders break down into tables, roles, cultures and perspectives, with root files for the database, model, relationships, expressions, data sources and DAX user-defined functions.
  • You can open a project from the .pbip or from definition.pbir inside a report folder. Multiple reports and models can share one project folder, so a per-report .pbip file isn't required.
  • Model metadata can be generated or rewritten programmatically with TOM — deserialise, edit, serialise back. This is what makes batch changes across measures or report pages practical.
  • Editing files outside Desktop is supported in principle, and Tabular Editor and VS Code are named in the docs. Some files can break Desktop's ability to open the project, and Desktop will point at the offending file when it can.
  • Some file schemas remain undocumented during preview and Microsoft reserves the right to change them.

When to use / skip

Use PBIP wherever the semantic model is treated as a product — an enterprise model with several developers, a review process, and someone who cares what changed between releases. Measure-level diffs and pull requests over TMDL are genuinely useful and they're the only way to get a meaningful code review of a Power BI model.

The report side is less mature than the model side. If your reason for adopting PBIP is "we want to review visual changes in a PR", set expectations low — PBIR diffs are legible but reviewing a layout change as text is not a pleasant job. And it's still preview, so anyone with a policy against preview features in production is going to make you argue for it.

Configuration decisions

  • Whether the whole estate moves to PBIP or only the enterprise models. A mixed estate is normal; an undocumented mixed estate is not.
  • Which tool owns the model definition — Desktop, Tabular Editor, or a script. Two tools writing the same TMDL with different conventions produces noisy diffs.
  • Whether the .gitignore stays as written. Committing cache.abf puts client data in the repo, so this one is a security decision, not a tidiness one.
  • Repo layout: one folder per solution, or a shared model folder with several report folders pointing at it.
  • How PBIP relates to the workspace Git connection, since both produce serialised item definitions and you want one shape, not two.

Gotchas

  • The .gitignore is only created when one doesn't already exist upstream. Drop a project into an existing repo with its own .gitignore and the data cache can end up committed.
  • Hand-editing files Desktop doesn't expect will stop the project opening. Recovery is a text-editing job, not a Power BI job, and it happens on someone's deadline.
  • Preview means the file schema can move. A model authored on a newer Desktop build can confuse an older one.
  • Saving as PBIP doesn't retroactively give you history. The first commit is a single enormous diff and everything before it is still lost inside .pbix files.
  • A semantic model that's had a write operation through XMLA can't be downloaded back as a .pbix, so "we'll just export it later and save as PBIP" isn't always available.

Consultant notes

  • Position TMDL as the win, not PBIP generally. Being able to see that someone changed a measure's filter argument is the thing that sells this to a delivery manager.
  • If the client is nervous about preview, the honest framing is that the format is in wide production use and Microsoft is still reserving the right to change undocumented files. Say both halves.
  • Bundle the adoption with a naming and formatting convention for DAX. Text diffs expose inconsistency ruthlessly and it's better to fix that up front.
  • Keep the original .pbix during migration. It costs nothing and it's the fallback when a project folder won't open.

Check whether PBIP has left preview and whether the undocumented file schemas have been published — both were still open at the last review

Was this accurate?
Related
Editing PBIP Files Externally09-alm-and-deploymentExternal tools09-alm-and-deploymentXMLA endpoint09-alm-and-deploymentPower BI KB — Features & Changelog_rootSensitivity labels08-governance-and-securityStar schema modelling02-dax-and-modelling