Which plugin do you have?
Look at the Pirros tab in the Revit ribbon. A single Pirros button that opens a docked panel with Browse, Updates, Sync and Settings tabs means you have Pirros in Revit (docked panel). Separate Sync, Download, Settings, Pirros and Live Link buttons mean you have the classic plugin. Don't go by the version number alone: on Revit 2020–2023 the classic plugin can show a 4.x version number. Follow the matching section below. Not sure which one your firm should be on? See Pirros in Revit vs the Classic Plugin.
Before you start
Syncing sends content from Revit to Pirros. To bring content into your Project, see Get Details and Families into Your Revit Project.
By default, only Admins can sync or upload. Members can request content, flag it, or build stashes. Syncing needs both the Create Details and Edit Details permissions (Create Typical Details and Edit Typical Details when the model is linked to Typical). Syncing families also needs Create Families and Edit Families (Create Typical Families and Edit Typical Families for Typical), and your firm needs the Families product. Firms with custom roles can grant these permissions. Without the detail permissions, both plugins show "You do not have permission to sync project details. Please contact your administrator to gain access to this feature." (or "…sync typical details…" for Typical).
Syncing never happens automatically. You choose when to sync.
You need an internet connection for the whole sync.
Work from a model that contains content you downloaded from Pirros. Each detail carries a Pirros ID. With an ID, a sync creates a new version of the existing detail. Without one, Pirros creates a new detail, which can mean a duplicate.
What's the same in both versions
Pirros matches by Pirros ID: found means a new version, not found means a new item.
The change message you enter becomes part of the item's version history, so make it specific. "Revised waterproofing layer per RFI-042" beats "Updated". A Detail uploaded for the first time doesn't carry a change message; the message goes with updated Details and with every family upload.
Sync a Detail and its parent sheet together, with the same change message, to keep history aligned. Both plugins help with this: when a synced view sits on a sheet that's already in Pirros for this project, that sheet is synced with it, using the same change message.
Views that a synced view references (for example through a section or callout) and that aren't in Pirros yet are uploaded as new Details in the same sync.
A Family change can flag every Detail that uses that Family, and a sheet-number change flags every Detail on that sheet. A long list after a model-wide change is expected.
Don't change the model's Project assignment after it has been synced unless you mean to re-upload everything under the new project. Pirros treats all Details as new uploads, which creates duplicates.
Only drafting views, detail views, legends, schedules and sheets can be synced. A sheet is listed only if it holds at least one drafting, detail or legend view, or a schedule. Plans, sections, elevations and 3D views aren't listed.
Duplicating a tracked view in Revit gives the copy no Pirros ID, so it syncs as a new item.
If your workspace is set to purge revision clouds, the Details list shows a ticked, greyed-out Purge Revision Clouds box, and revision clouds are left out of what's uploaded. This is set in your workspace's upload settings on the Pirros website.
Option A: Pirros in Revit (v4.x, docked panel)
1. Open the panel and confirm your project
On the Pirros tab in the Revit ribbon, click the Pirros button. The panel docks to the right.
Sign in if prompted. Check the linked project in the panel header. You can change it in Settings. If the model isn't linked yet, the Sync tab shows Link a project to sync. with an Open Settings button.
2. Open the Sync tab
The Sync tab (Sync to Pirros) lists the content in your model that can be synced — details, sheets, loadable families, system families and groups — whether or not it's in Pirros yet. Switch between Details and Families at the top. Table headers stay in place as you scroll.
Use Filter By to choose what's listed:
Recommended (the default): content that isn't in Pirros yet, plus content that changed since it was last synced.
Not Linked: content that isn't in Pirros yet (no Pirros ID). Use it to upload content for the first time.
Recently Changed Views (Recently Changed Families on Families): content already in Pirros that changed since it was last synced.
All Views (All Families): everything.
On Details, turn on Show Views Not on Sheets to include views that aren't placed on a sheet; it's off by default. On Families, Show System Families and Show Families Without Instances are on by default. The In Sync column shows In Sync, Out of Sync or Renamed; content that isn't in Pirros yet shows Out of Sync and no Pirros ID. To find something, use the Search by name or Pirros ID box.
3. Choose what to push
Select the items you want to send back to Pirros.
If your workspace's upload settings leave out loadable or system families, the Sync tab says how many items are hidden by Upload settings (the link opens those settings on the website). Content that can't be synced for other reasons isn't listed.
4. Add a change message and sync
Enter a change message describing what changed, in the Change message (optional) box.
Click Sync n selected, where n is the number of items you selected. Items already in Pirros are versioned in place in your library; items that aren't in Pirros yet are added as new.
A sync can't be cancelled from the panel. You can switch to another tab while it runs; the result is still shown when you come back.
5. Check the result
The plugin reports whether the upload succeeded or partly failed, and which items didn't make it: Upload complete, Upload failed, or how many uploaded and how many failed, with each failed item and the reason. Items you've just synced no longer show up again as recently changed.
If Pirros finds duplicate or unrecognized Pirros IDs in the model when you sync, it clears them and stops before uploading; follow the message to refresh the list and sync again.
6. Upload a family from the Family Editor
With a Family open in the Family Editor, you can upload it directly from the pane:
Save the family first. An unsaved family can't be uploaded (Family must be saved before uploading.).
Link the family document to a project on the Settings tab. The family needs its own link; the link on your project model doesn't carry over.
Open the Sync tab and switch to Families. The open family is the only row.
Select it, add a change message and click Sync 1 selected.
If a type catalog (a .txt file with the same name) sits next to the saved .rfa, its types are included in the upload.
Option B: Classic plugin (v3.x)
1. Sign in and set your project
In Revit, click the Pirros tab, then Settings, then Login, and sign in. You'll see Successfully Logged In. After that, the classic plugin signs you in automatically when Revit starts.
Click Settings again and open Project Settings.
If you see a Workspace field, choose the workspace. Then pick the project in the Project list. For your firm's standard library, pick Typical, listed first; linking to Typical needs the Create Typical Details or Edit Typical Details permission.
To create a project, click + New Project, enter the Project Name and Project Number, and click Create. If a project with that number already exists in the workspace, the model links to it. If not, Pirros creates it for you. You don't need to upload from the web app first.
Click Link.
If you click Sync before the model is linked, the plugin asks you to link it first (Project Link Required) and opens Project Settings.
2. Open Sync
Click Sync in the Pirros tab. The Sync Details/Families window opens, with a Details tab and, if you can sync families, a Families tab.
3. Filter the views
To upload content for the first time, set Filter By to Not Linked. These views have no Pirros ID yet.
To update existing content, use Recently Changed Views.
Recommended, the default, shows both: content with no Pirros ID and content that changed since it was last synced. All Views shows everything.
Turn on Show Views Not on Sheets to include details that aren't placed on a sheet.
On the Families tab, the same filter offers Recently Changed Families and All Families. Show Families Without Instances and Show System Families are on by default.
4. Select what to upload
Check the details, schedules, legends and sheets you want. For families, newer classic plugin versions leave out loadable or system families when your workspace's upload settings turn them off; other versions list them all.
5. Add a change message and submit
Enter a Change Message, then click Confirm. Wait for the Finished confirmation before you close Revit or start another sync. If a family fails to upload, no message appears: it stays out of sync and shows up again under Recently Changed Families.
6. Upload a family from the Family Editor
Save the family first. An unsaved family can't be uploaded (Family must be saved before uploading.).
With the family open in the Family Editor, click Sync. The family needs its own project link: if it isn't linked, you'll see Project Link Required and Project Settings opens.
The Upload Family window shows the family's types; types from a type catalog (a .txt file with the same name next to the .rfa) are marked (Type Catalog). Add a Change Message and click Submit.
Wait for Upload complete.
This needs the Create Families permission (Create Typical Families when the family is linked to Typical) and the Families product.
Side by side
| Pirros in Revit (v4.x) | Classic plugin |
Where you work | Sync tab in the docked panel | Sync dialog from the ribbon |
Set the project | Settings, shown in panel header | Settings, then Project Settings: pick the project (or Typical) or + New Project, then Link |
Find what to push | Filter By: Recommended, Not Linked, Recently Changed Views, All Views | Filter By: Recommended, Not Linked, Recently Changed Views, All Views |
Change message | Entered in the tab | Entered in the dialog |
Finish | Sync n selected, with success or partial-failure report | Confirm, wait for Finished |
From the Family Editor | Sync tab, Families | Sync, then Upload Family, then Submit |
Who can do it | Admins by default (Create Details + Edit Details) | Admins by default (Create Details + Edit Details) |
Frequently Asked Questions
Q: I'm a member, not an admin. Can I sync?
A: Not with the default Member role. Ask your admin to sync, or flag the detail and describe what should change.
Q: Why do I see hundreds of items to sync after one change?
A: A family update flags every detail that uses it, and a sheet renumber flags every detail on that sheet. Review the list and select only what you want. The default Recommended filter also lists everything that isn't in Pirros yet; choose Recently Changed Views to see only content that changed.
Q: Will syncing overwrite someone else's changes?
A: A sync creates a new version, and earlier versions stay in the item's History tab. Coordinate with your team on shared models.
Q: Can I undo a sync?
A: There's no undo button, but version history is kept. Contact your admin or Pirros support to restore a previous version.
Q: I edited a copy of a detail that wasn't downloaded from Pirros, and the sync created a duplicate. Why?
A: The detail had no Pirros ID. Download from Pirros first, then edit that copy.
Q: Can I add content without opening Revit?
A: Yes. Upload a Revit file from the Source Files page in the web app. See Uploading Projects and Source Files.
