PBIP and PBIR Explained: Power BI Project Files in 2026

PBIX is the single-file format most people know. It bundles the report, the semantic model and the cached data in one binary file.

PBIP, a Power BI Project, is the same content saved as a folder of plain-text files. In Desktop, File > Save as and choose the Power BI project (.pbip) type. You can convert both ways through Save as: a PBIX can become a PBIP, and a PBIP can be saved back as a PBIX. Microsoft notes this conversion only happens through Desktop, not programmatically.

PBIR, the Power BI enhanced report format, is how the report part of a project is stored: a definition folder with a separate JSON file for each page, visual and bookmark. Its predecessor, PBIR-Legacy, kept the whole report in one large report.json that wasn't documented for external editing. PBIR is generally available and is now the default report format.

Saving as PBIP produces a root folder like this. The .pbip file is only a pointer: opening it opens the report and, through the report's reference, the model. Microsoft points out you can also open the report folder's definition.pbir directly, which is why a Git-synced workspace doesn't need a .pbip file at all.

Desktop also writes a .gitignore if there isn't one, excluding .pbi/localSettings.json and .pbi/cache.abf, which hold per-user settings and the cached data.

The PBIR definition folder has a fixed shape. report.json holds report-level settings such as the theme collection and report filters. version.json is required and declares the PBIR version. pages/pages.json lists page order and the active page. Each page has its own folder containing page.json (page size, background, page-level filters) and a visuals folder with one subfolder per visual, each holding a visual.json (position, formatting, query) and optionally a mobile.json for the phone layout. Bookmarks get their own folder in the same way.

Folder names default to the object's internal name, a 20-character identifier such as 90c2e07d8e84e7d5c026. You can rename them to readable names if they only use letters, digits, underscores and hyphens, then restart Desktop. Names that break that rule are ignored, which is the classic cause of "my page disappeared after I renamed the folder".

Every file starts with a $schema URL pointing at a public JSON schema, which gives you validation and autocomplete in VS Code and versions the file format.

definition.pbir is the one required file in the report folder. It holds the report's core settings and, importantly, which semantic model it uses.

A byPath reference points at a model folder by relative path (for example ../Sales.SemanticModel). Desktop opens that model in full edit mode alongside the report.

A byConnection reference points at a published semantic model in a Fabric workspace through a connection string, so the report opens as a live-connected thin report and the model isn't editable. Deployments through the Fabric REST API must use byConnection.

The version property decides the formats allowed: version 1.0 means the report must be PBIR-Legacy (report.json), version 4.0 or higher allows either PBIR-Legacy or PBIR.

Microsoft's documentation now states that PBIR is generally available and the default report format. You can still open PBIR-Legacy reports in Desktop and the service, but when you edit and save one, Power BI silently converts it to PBIR.

Power BI keeps a backup before converting. Desktop keeps it for 30 days under TempSaves\Backups in your user profile; the service keeps a PBIR-Legacy backup for 28 days, restorable from the report's settings with Restore as PBIR-Legacy. If you need to stay on PBIR-Legacy for now, Microsoft's guidance is not to edit the report in the service, or to use a Desktop release from before September 2026.

Fabric Git integration and the Fabric REST APIs export report definitions as PBIR, so anyone on Git integration is already looking at PBIR files.

PBIR is publicly documented and supports modification from other applications. Practical things teams do with it: copy a page or visual between reports by copying folders; apply a batch change to every visual with a script, such as hiding visual-level filters; find and replace a measure name across reports; and keep a standard header visual identical on every page.

When you save a PBIR file while the project is open, Desktop detects it and shows an Apply external changes banner. Save your work in Desktop first, because applying external changes overwrites unsaved edits.

Errors come in two kinds. Blocking errors, such as invalid JSON or a missing required property, stop the load and name the file to fix. Non-blocking errors, such as an invalid active page name, are corrected automatically and flagged for review.

House rules that avoid trouble: save files as UTF-8 without BOM; let Git handle CRLF line endings (Desktop writes CRLF) with autocrlf; keep the project path short, since Windows' default 260-character path limit applies to deep project folders; and don't edit the files Microsoft lists as unsupported, such as report.json in PBIR-Legacy, mobileState.json and semanticModelDiagramLayout.json.

One data-privacy note: visual.json and bookmark files can contain data values, for example a filter on Company = Contoso stores "Contoso". Review diffs before pushing a project to a shared repository.

Custom themes, images and private custom visuals live in StaticResources/RegisteredResources. Each file must be registered in the report's resource list; once registered, you can replace the file and Desktop loads the new version after a restart. Microsoft calls out exactly the scenarios this enables: authoring themes outside Desktop against the public schema, switching between light and dark themes, or swapping logo images across many reports in one batch change.

Page backgrounds work the same way. A page's background image is a registered resource, and the page.json background setting references it by name with an image scaling value such as Fill.

The service enforces PBIR size limits: 1,000 pages per report, 1,000 visuals per page, 1,000 resource package files per report, and 300 MB for all resource files and for all report files.

Power BI Projects aren't supported in the Power BI Desktop build optimised for Power BI Report Server. Sensitivity labels aren't supported with projects. You can't save a PBIP directly to OneDrive or SharePoint; save to a local folder (a locally synced folder works but can cause sync problems).

Visual-level automatic filters are written to visual.json only after the filter pane has been expanded at least once while editing.

Because PBIR is documented, tools can write a project that Desktop opens directly. The VizForge Design Studio does this from a page design: it writes a project with the .pbip pointer, a PBIR report whose page.json uses your design as the page background (scaling Fill), your theme as a registered resource, and one visual.json per visual slot, positioned to the pixel on your panels with transparent backgrounds. A small sample semantic model in TMDL is included so the project opens without a data source; point the visuals at your own model when you're ready.

The result opens in Power BI Desktop as a finished layout with empty visuals waiting for fields, which is the slowest part of report building done for you.