Power BI project files: reports saved as text you can track
Power BI project files are a save format in Power BI Desktop that stores a report and its semantic model as plain text in folders, not as one binary file. Because the content is text, a team can track each change, compare versions and work in parallel. However, the format has limits. This guide covers the structure, the workflow and the pitfalls.
- Text files in folders
- Ready for Git
- Save as from Desktop
Last updated
What are Power BI project files?
A standard report is a single PBIX file. Nobody can read its contents without Desktop, so two versions are hard to compare. A project changes that, because Desktop writes the definitions out as text.
Microsoft Learn lists the benefits. Text opens in an editor such as Visual Studio Code. The folder layout shows what a report contains. Source control systems such as Git can store it, and automated deployment can build on it.
Nothing about the report itself changes. Pages, visuals and measures work as before. Only the way Desktop stores them differs, and you can switch back.
What Desktop writes into a PBIP folder
Save a report named Sales as a project and these items appear side by side.
| Item | What it holds | Note |
|---|---|---|
| Sales.pbip | A pointer to the report folder | Open this file to load the project |
| Sales.Report folder | The report definition | Pages, visuals and layout |
| Sales.SemanticModel folder | The model definition | Tables, measures and relationships |
| definition.pbir | The link from the report to its model | Sits inside the report folder |
| definition.pbism | The core definition of the semantic model | Sits inside the model folder |
| .gitignore | A list of files that Git should skip | Covers local settings and the data cache |
How to save a report as Power BI project files
The conversion takes place in Desktop, and it works in both directions.
Open the report
First, open the PBIX file in Power BI Desktop and check that it refreshes cleanly.
Choose Save as
Then select File, Save as and pick the Power BI project type from the list.
Pick a short folder path
Next, save close to the drive root, because Windows limits path length and project folders nest deeply.
Commit the folder
Finally, add the folder to your Git repository. After that, each save shows up as readable changes.
How do Power BI project files reach the service?
Microsoft describes three routes. Fabric Git integration connects a workspace to a repository and syncs content. Fabric APIs let a pipeline deploy definitions from code. Finally, the Publish button in Desktop still works as it always did.
Editing outside Desktop is possible as well. When a text file changes while the project is open, Desktop detects it and offers to apply the change. So a developer can adjust a measure in an editor and see it in the report.
Some files deserve respect, however. Microsoft advises against editing certain files outside Desktop, for example the report layout and diagram layout files. Also, leave automatic date tables alone.
Which limits should you know before switching to PBIP?
Sensitivity labels come first. Microsoft states that projects do not support them, so labeled reports need a different plan. Desktop for Power BI Report Server does not support projects either.
Storage has rules too. You cannot save a project straight to OneDrive or SharePoint. Also, long folder paths cause errors, which is why a short root folder helps.
Text details matter in Git. Desktop writes files as UTF-8 without a byte order mark and with CRLF line endings. Therefore configure the line ending setting in Git, or every file may show as changed.
PBIP questions from report teams
Can we convert Power BI project files back to PBIX?
Yes. Open the project in Power BI Desktop, choose File and Save as, and pick the PBIX type. Microsoft notes that conversion in either direction happens through Desktop only, not through a script. So a team can try the project format on one report and return to a single file if it does not suit them.
Do Power BI project files contain our data?
The definitions are text, but Desktop also keeps a local data cache so the report opens with data. The gitignore file in the project tells Git to skip that cache and the local settings file. Therefore data stays out of the repository when you keep that file in place. Check it before the first commit, because removing it would expose data to everyone with repository access.
Do we need Git to use the format?
No. A project is just a folder, so it works without source control. However, Git is where the benefit shows. It records who changed what, lets two people work on separate branches and makes a review possible before a change reaches production. Without it, you gain readable files but little else.
How is this different from Fabric Git integration?
They solve different halves of one problem. A project is how Desktop saves work on your machine. Fabric Git integration connects a workspace in the service to a repository. Together, an author commits a project from Desktop, and the workspace then syncs from the same repository. Each also works alone, so a team can adopt one before the other.
Can you set up source control for our reports?
Yes. Power BI Agency moves report teams onto projects and Git, with branch rules and a release routine that fits your size. The work happens online in your own tenant and repository. We are our consultants within Sataware Technologies and independent of Microsoft. Book the free 30-minute assessment, or call (480) 485-7373.
Let's build your first dashboard together.
Tell us what you report on today. A consultant replies within 2 hours with next steps.
Trusted partners
Microsoft Solutions Partner · AWS Partner
Cloud & AI Platforms
Azure SQL, Microsoft Fabric and the data pipelines behind your reports.
AI Business Solutions
Power BI reporting on your Dynamics 365, Business Central and Power Platform data.
Security
Row-level security and Entra ID sign-in on every report and workspace.
Amazon Web Services
Power BI on your AWS data, with connectors for Redshift, Athena and S3.