Family Purge Documentation
Complete guide to installing, configuring, and using Family Purge to strip bloat from Revit families - both loaded in your active project and saved as .rfa files on disk.
Supported Revit Versions
- Revit 2022
- Revit 2023
- Revit 2024
- Revit 2025
- Revit 2026
- Revit 2027
Installation
Make sure all running instances of Autodesk Revit are closed before starting the installation.
Quick Start Guide
Follow these steps to clean the families in your current Revit project:
Open Family Purge
With your project open, go to the Add-Ins tab and click Family Purge on the AUTOM8LABS panel. The dialog opens with a sidebar - Purge Model, Purge Folder, Settings, and Help.
Select Families
The Purge Model tab lists every editable family in the project. By default the list is filtered to unused families only. Tick the families you want to clean, or adjust the filter to see everything.
Choose Cleaners
On the Settings tab, toggle which cleaners run - nested families, unused types, materials and assets, CAD imports, and images are on by default; fill patterns, line patterns, and object styles are Advanced and off by default.
Purge
Hit Purge. Each family is opened, cleaned, and reloaded back into the project, with Pause, Resume, and Cancel available at the next family boundary. HTML and CSV reports show exactly what each cleaner removed.
Run Purge Model on a project copy first to see what gets removed. The HTML and CSV reports tell you exactly which cleaners fired on each family and how much disk space was reclaimed.
Purge Model
The Purge Model tab is for families that are already loaded into your active project. It lists every editable family in the document, lets you pick which ones to clean, then opens each in the family editor, runs the configured cleaners, and reloads it back into the project - overwriting the original.
Purge Model tab - the list of loaded families with category, type count and instance count
GIF placeholder · purge-model-list.gif
Family list
The list is filtered to families Revit can actually open - in-place and system families are excluded, and rare orphans without a category are skipped.
Each row shows the family name, category, type count, and instance count. A search box at the top filters by name as you type.
Default filter: unused families only
By default the list shows only families whose instance count is zero and whose category isn't pinned by a runtime swap. Toggle the Show all loaded families switch to widen the list to every editable family.
Family symbols whose categories are referenced by a family parameter (e.g. runtime-swap placeholders) are kept even when they appear unused, because they will be needed when the host family is loaded again.
Running a purge
For each family you tick, Family Purge opens the family in the editor, runs every enabled cleaner (each in its own transaction), then loads the cleaned family back into the project - overwriting the original (and any types using it).
A live progress panel reports current family, percentage done, and elapsed / remaining time. You can pause or cancel mid-run. Cancel takes effect at the next family boundary - the current family always finishes cleanly.
Purge run in progress - current family, percentage done, elapsed / remaining time, pause and cancel controls
GIF placeholder · purge-model-run.gif
Purge Folder
The Purge Folder tab targets .rfa files on disk - your firm library, an OEM content drop, a vendor download. No active project required. Family Purge opens each file in turn, runs the configured cleaners, and writes the cleaned family to an output folder.
Purge Folder tab - source folder picker, options (subfolders, skip backups, preserve structure) and output folder
GIF placeholder · purge-folder-config.gif
Options
- Source folders - one or more folders containing
.rfafiles. Add as many as you like - Include subfolders - walk the tree recursively
- Skip backup files - ignore
*.0001.rfaand*_backup.rfa - Preserve folder structure - mirror the input tree under the output folder, so an input at
Lib\Doors\Single.rfawrites toOutput\Doors\Single.rfa - Output folder - destination for the cleaned families. Originals are not touched. Recent folders are remembered for quick reuse
Pause / Resume / Cancel
The Purge Folder progress panel has the same controls as Purge Model. Pause and Cancel take effect at the next file boundary - the family currently being processed always finishes cleanly, so partially-written .rfa output is never produced.
Cleaners
Each family is processed in independent passes, each in its own transaction. Toggle these on the Settings tab under Cleaning Options. Five cleaners are on by default; three are advanced and off by default.
| Cleaner | Default | What it does |
|---|---|---|
| Nested families | On | Recursively descends into nested families, cleans each one, reloads it back into its parent. Category-mismatched nested families are deleted. |
| Unused family types | On | Removes loaded types that no instance and no family parameter references. |
| Materials & assets | On | Walks every element to collect used materials and the three asset types (appearance, structural, thermal). Deletes unreferenced materials and assets. Runs twice - the second pass catches assets orphaned by the first. |
| CAD imports | On | Strips DWG, DXF, SAT, SKP, and DGN imports. Typically the largest source of family bloat by file size. |
| Images & PDFs | On | Strips raster images and imported PDFs. |
| Advanced - Fill patterns | Off | Walks material and filled-region references to build a "used" set, deletes the rest. Solid is always preserved. |
| Advanced - Line patterns | Off | Walks graphics-style and category line-pattern references to build a "used" set, deletes the rest. |
| Advanced - Object styles | Off | Deletes subcategories that no curve or element references. |
Fill patterns, line patterns, and object styles can change the visual appearance of a family in subtle ways - a fill type you didn't realise was referenced by an annotation gets removed and the annotation falls back to Solid. Leave these off until you have verified the results on a copy of a family you don't mind testing on.
Why each pass uses its own transaction
If the materials-and-assets cleaner fails halfway because Revit refuses to delete a particular asset, the transactions for nested families, unused types, and CAD imports have already committed - their work isn't lost. The reporting layer flags the failed pass and continues with the next cleaner.
Failure Handling
Revit's family-load, family-edit, and transaction operations can throw modal warnings and errors that block unattended runs. Family Purge attaches an application-level failure handler that intercepts every warning before Revit can show a dialog:
- Dismiss all warnings during processing - on by default. Warnings (e.g. "duplicate type names will be renumbered") are silently swallowed
- Dismiss all errors during processing - on by default. Errors with a resolve option (e.g. "delete the offending element") are auto-resolved
- PurgeLog - every dismissed warning and auto-resolved error is logged to a per-run PurgeLog with a timestamp, family name, severity, and message
Both toggles live under Settings → Warning / Error Handling. If you would rather see the dialogs and intervene by hand, untick both options before starting a run. The PurgeLog still records the dialogs that fire so you can audit the run after.
Revit's auto-resolve picks the first resolution option Revit offers. For most warnings that means "do nothing" - but for some errors it means "delete the offending element". Read the PurgeLog after every unattended run to verify nothing critical was sacrificed.
Settings
The Settings tab covers everything that controls how a purge run behaves. Settings auto-save the moment you change them - no Save button to click.
Settings tab - cleaning options, warning / error handling, diagnostics and report settings
GIF placeholder · settings-tab.gif
Cleaning Options
Toggle each cleaner on or off - see the Cleaners reference for what each does.
Warning / Error Handling
- Dismiss all warnings during processing - on by default
- Dismiss all errors during processing - on by default
See Failure Handling for the full picture.
Diagnostics
- Advanced debug logging - off by default. When ticked, logs every family open / clean / save / close as it runs. Use when sending crash traces to support; leave off otherwise to keep log files small.
Report Settings
- Generate CSV report
- Generate HTML report
- Output folder - where reports land. Defaults to the per-user Family Purge reports folder; change to a project or network folder if you want reports archived centrally.
Reports & Logs
Family Purge writes three kinds of artefacts per run.
Per-family reports
Each family processed produces a report covering:
- File size before / after (and the delta in MB)
- Which cleaners fired and how many elements each removed
- Any errors encountered
Reports are HTML and/or CSV (toggleable on the Settings tab) and land in the configured output folder. The default is per-user; set a project or network folder in Settings if you want reports archived centrally.
Sample per-family HTML report showing before / after size and per-cleaner element counts
Screenshot placeholder · report-html.png
PurgeLog
A separate PurgeLog audit file records every suppressed warning and auto-resolved error from Revit's failure handler. This is your audit trail - it tells you exactly what was dismissed under the hood during an unattended run. Open the PurgeLog after every Purge Folder run to confirm nothing critical was auto-resolved away.
Rolling diagnostic log
Family Purge writes a thread-safe rolling log of every operation. By default this only contains warnings and errors; enabling Advanced debug logging in Settings adds a per-family trace - useful when a specific family is causing Revit to crash, since the trace tells you which file was being processed at the moment of failure.
If you need to send logs to support, you'll find them in your local app data folder (under AUTOM8LABS\FamilyPurge\Log\) - just attach the file for the affected date.
Licensing
A licence key is required to run the Purge workflows. Manage your licence from Help tab → Manage Licence.
Family Purge is a per-seat subscription - choose the billing cadence that suits you:
| Plan | Price | Best for |
|---|---|---|
| Monthly | £20/seat/month | Pay per seat, billed monthly. Cancel anytime. |
| Annual | £200/seat/year | Pay per seat, billed yearly. Best value for ongoing use. |
See the pricing page for the full feature comparison and self-serve checkout. Trial keys are available on request - contact us to discuss.
Updates
Family Purge checks for new versions on launch.
- New version available - a notification dialog appears with release notes and a Download button. You can dismiss with Remind Later.
- Version no longer supported - if a build's minimum supported version is bumped past your installed build, a critical update dialog appears on launch prompting you to download the new build. Your licence stays cached so you do not need to re-enter it after updating.
Frequently Asked Questions
Purge Model targets families that are already loaded into your active Revit project. It opens each family in the family editor, cleans it, and reloads it back into the project - overwriting the original.
Purge Folder targets .rfa files on disk. It opens each file in turn, cleans it, and writes the cleaned family to an output folder - originals untouched (unless you point output at the source folder). No project required.
No. Family Purge removes unreferenced elements - types nothing uses, materials nothing references, CAD imports, images. The family's geometry (extrusions, sweeps, voids, reference planes, parameters, formulas) is never modified. If a cleaner can't prove an element is unreferenced, the element is left alone.
For Purge Model, CTRL+Z reverts the family reloads in the project before you save. For Purge Folder, run with the output set to a separate folder - your originals remain untouched and you can A/B compare before swapping them in. Both workflows produce reports showing exactly what was removed so you can audit before keeping the cleaned files.
It depends entirely on what's in your families. Families with embedded CAD imports (a common source of bloat) often drop by 70-90%. Clean families with just a few unused types might drop by 5-10%. Run Family Purge on a copy of your library first and read the per-family HTML report to see the actual reduction.
Fill patterns, line patterns, and object styles can be referenced indirectly - through nested filled regions, schedule cells, or annotation override sets - in ways the cleaner can't always prove. Removing one that's actually still referenced will cause the consumer to silently fall back to a default (Solid for fill patterns). The five default-on cleaners use authoritative reference graphs. The three Advanced cleaners are best-effort. Leave them off unless you have tested.
Yes, by default. The application-level failure handler dismisses Revit's warnings during family-load and family-edit operations so unattended runs do not stall. Every dismissed warning is logged to the PurgeLog with timestamp, family name, and severity - check the log after every run to audit what was swallowed. If you'd rather see the dialogs, untick both warning and error toggles on the Settings tab.
Changelog
Initial Release
- Purge Model workflow - clean families loaded in the active project
- Purge Folder workflow - batch-process
.rfafiles with Pause / Resume / Cancel - Eight cleaners - nested families, unused types, materials & assets, CAD imports, images & PDFs (default on); fill patterns, line patterns, object styles (Advanced, off by default)
- Application-level failure handler with PurgeLog audit
- Per-family HTML and CSV reports