PBIR vs PBIR-Legacy

Power BI

PBIR saves a report as a folder with a file for each page, visual and bookmark. PBIR-Legacy is the older single report.json. PBIR is now the default.

The two formats

PBIR-Legacy keeps the whole report definition in one file, report.json, at the root of the report folder. It does not support editing outside Power BI Desktop.

PBIR replaces it with a definition folder, where each page, visual and bookmark is its own file. Microsoft documents the format, and other tools may change it.

The version in definition.pbir decides what is allowed. Version 1.0 means PBIR-Legacy only. Version 4.0 or above allows either format.

Source: Power BI Desktop project report folder.

What a PBIR report folder holds

  • definition/pages/pages.json, then a folder per page with its page.json.
  • definition/pages/[page]/visuals/[visual]/visual.json, and mobile.json when the visual has a mobile layout.
  • definition/bookmarks/, with a file per bookmark and bookmarks.json.
  • definition/report.json and definition/version.json. This report.json sits inside definition. The legacy one sits at the root of the report folder.

Source: Power BI Desktop project report folder.

Which one you have today

Microsoft Learn says PBIR is generally available and is the default report format. Fabric Git integration and the Fabric REST APIs export reports as PBIR.

Source: Power BI Desktop project report folder.

Automatic conversion, and the backups it keeps

PBIR-LegacyPBIR

When you edit and save a PBIR-Legacy report, Power BI converts it to PBIR without asking.

  • Power BI Desktop

    Power BI Desktop keeps a backup for 30 days, in %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups for the Microsoft Store version, or %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups for the installer version.

  • Power BI service

    For a report converted in the Power BI service, the service keeps a PBIR-Legacy backup for 28 days. To restore it, open Report settings from the workspace and select Restore as PBIR-Legacy.

NoteTo keep a report in PBIR-Legacy, do not edit it in the service, or use a Power BI Desktop release from before September 2026.

Source: Power BI Desktop project report folder.

Will an older .pbix still open?

A forum answer accepted as the solution says yes: a .pbix saved in PBIR-Legacy still opens, and is converted to PBIR when you open and save it.

The other way round does not work. Microsoft Learn says a file created or saved in a newer release of Power BI Desktop does not open in an older one.

Microsoft's update notes for January 2026 planned PBIR on by default in the service first, then in Power BI Desktop, with general availability planned for Q3 2026. They give no date for the switch in Desktop.

Source: Will archived PBIX files still open after PBIR becomes the only format?, Previous monthly updates to Power BI Desktop and the Power BI service.

Names and limits

  • Each page, visual and bookmark starts with a 20-character identifier as its name, such as 90c2e07d8e84e7d5c026.
  • A name may contain only letters, digits, underscores and hyphens. After renaming a file or folder, restart Power BI Desktop.
  • A report can have up to 1,000 pages, and a page up to 1,000 visuals. All report files together can be up to 300 MB. The Power BI service enforces these limits.

Source: Power BI Desktop project report folder.

If a PBIR report will not open

Open the file the message names in VS Code and read its schema validation messages. Two messages you may see:

Source: Power BI Desktop project report folder.

Check a project in your browser

The Power BI Report Doctor reads a PBIP folder or .zip and lists the file and line to fix. Nothing is uploaded.

Other guides

Sources

What you put into the tools never leaves your browser. We count page views and keep them for 90 days. Accept and we also remember this browser, so a return visit is not counted as new. Privacy policy