FolderView Plus keeps compatibility paths for folder.view, folder.view2, and folder.view3, but migration should still begin with an export and a review. Do not remove the previous plugin or its data until the FolderView Plus layout has been verified.
FolderView Plus supports:
- Legacy full and single-folder exports from FolderView2 and FolderView3.
- Older type-wrapped export shapes recognized by the import parser.
- Legacy Docker assignment labels:
folder.view,folder.view2,folder.view3, andfolderview.plus. - Existing folder-level legacy regex values at runtime, during import/export, and in backups.
- Legacy custom CSS and JavaScript override directories.
Compatibility does not mean every older visual customization will match the current UI without review. Stable selectors and the deprecation policy are documented in Support Policy.
- Export the Docker and VM folder configuration from the existing installation.
- Copy the export files off the Unraid flash device.
- Back up the previous plugin configuration directory.
- Record any custom CSS, JavaScript, icons, labels, regex rules, and unusual nested layouts.
- Install FolderView Plus.
- Keep the old data until the migration and runtime pages have been verified.
If FolderView Plus starts with empty or missing current configuration, its compatibility layer can discover eligible FolderView2 data. FolderView3 requires the explicit full migration below; it is no longer adopted automatically through the older folder-only path. Keep the original full export and configuration directory until verification is complete.
Version 2026.10.15.07 restores the full migration controls in Advanced Settings → Recovery → Additional tools. Choose Detect installed FolderView3 for local configuration or Preview FolderView3 export for a complete version-1 backup. Basic's Docker/VM Import and Recovery's Import Environment also route a detected full FolderView3 envelope into this workflow. The Setup Assistant accepts per-type exports and directs complete backups to Recovery.
A full migration replaces both folder maps and saved type preferences, including existing Plus rules, privacy choices, groups, health/performance options, future-folder defaults and backup schedules. It retains the active Theme Workspace profile and adds inactive imported profiles. Review the warnings and counts, then confirm Apply verified migration. Cancellation writes nothing. Apply creates a global rollback checkpoint and per-type backups, checks both source and destination against the preview under the mutation lock, writes the target and reads it back before reporting success. Settings and Recovery data then refresh; reload any already-open Docker, VM or Dashboard pages.
In Advanced Settings, open Recovery and use the FolderView3 migration preview to inspect an installed configuration or a full environment export. The preview reports Docker and VM folder order separately. Saved order-docker.json and order-vm.json snapshots take priority over the order of folder records; missing or invalid snapshots fall back to configuration order. Duplicate and unknown references are skipped with warnings. Positions of unassigned containers or VMs among folders on the native Unraid page are not imported.
Appearance imports preserve the Docker, VM, and Dashboard scopes named in custom CSS filenames, including files targeting multiple pages. Styles under .disabled directories become separate inactive appearance profiles, so they cannot be activated with the main imported profile by accident. Unscoped CSS and generated theme files are excluded. Theme source metadata is reported but does not enable managed updates automatically; scan the original source in Appearance to manage future updates.
All imported appearance profiles start inactive. Custom preset names and reusable values become additional inactive profiles. Notes, style-toggle preferences and page preset/value assignments are retained in the imported profile's legacyMetadata recovery field; this data can be recovered from a native environment export. Preview each profile before activation because FolderView3 selectors and variables can differ from FolderView Plus. Theme update-source metadata never enables managed updates automatically. Native Docker autostart enablement and waits remain a separate opt-in choice, offered only when source entries are available. A normal full export does not contain native autostart or native organizer registry data; older exports may also lack the plugin's startup settings, which leaves startup ownership unmanaged.
Migrated folders use the verified legacy ownership policy: explicit assignments anywhere take priority over valid Docker labels, followed by regex rules in original source folder order. Saved folder order controls display/startup placement separately. Bulk actions, conflict reports, Docker, VMs, Dashboard and Docker startup share this policy. Native Plus folders and advanced rules retain their existing behavior. Missing VM UUID hints and hidden preview preferences remain available for identity reconciliation when members return. Existing folders receive their effective inherited legacy defaults; explicit false and zero values remain intact.
Legacy overflow 0/default, 1/expand, and 2/scroll become default, expand_row, and scroll. Folder update highlighting is converted to folder_update_highlight. Unsupported Dashboard animation/update highlighting, Dashboard disabled/direct-WebUI context modes and color locking are disclosed in preview. Imported icon references and User Scripts are retained, but their files are absent from full exports. Verify them locally before removing the old plugin; run only one folder-rendering plugin at a time after migration.
Malformed required sections, unsupported versions, duplicate JSON keys or ambiguous folder names are rejected before writes. Intentional empty maps are supported. Safe limits are 5 MiB per full export, 5,000 folders per type, 5,000 members/hidden members/identity hints/action targets per folder, 200 actions per folder, 2,000 startup sequence entries, 160 UTF-8 bytes per folder name, 255 bytes per member name and 1,024 bytes per regex. Appearance permits at most 32 total profiles, 128 stylesheet files/2 MiB aggregate input and 64 KiB per compiled profile layer. Inputs beyond a supported limit are rejected rather than silently truncated. Unsafe or unscoped CSS is excluded with warnings. Correct rejected input in a copy and keep the original for recovery.
If apply fails normally, captured configuration and assets are restored automatically and recovery evidence is retained. A process kill or power loss cannot provide a multi-file atomic commit: after restart, use the pre-migration global checkpoint in Recovery and verify both types and appearance together. Do not publish a raw backup or migration report as a sanitized support bundle.
The Setup Assistant can include Docker and VM imports in a guided plan. Import is optional for a fresh setup. A migration route only requires an enabled import when the selected route is specifically intended to migrate existing data.
For each import:
- Select the matching Docker or VM export.
- Wait for schema and compatibility validation.
- Enable that import for the setup plan.
- Review the detected folders, rules, and settings.
- Continue to Review and apply only when the plan is correct.
Docker exports cannot be applied to VMs, and VM exports cannot be applied to Docker.
The standalone import dialog uses three plain-language modes:
Adds missing folders and updates matching folders. It does not delete a destination folder merely because that folder is absent from the export. This is the recommended choice for most migrations.
Creates folders that do not exist and leaves existing destination folders unchanged. Use this when the current configuration must remain authoritative.
Makes the destination match the export. Existing destination folders absent from the selected export can be deleted. Use this only when the export is intended to be the complete source of truth.
Changing the mode recalculates the preview. The optional changed-folder table identifies creates, updates, deletes, and affected fields. Preview only performs the calculation without saving. A live import creates an automatic backup before committing the selected operations.
Current exports contain schema and folder identity metadata. Legacy exports may rely more heavily on names and hierarchy paths.
- Existing folders are matched conservatively.
- Nested folders are ordered with parents before descendants.
- Legacy nested IDs can be remapped by a matching parent/name path.
- Ambiguous path collisions are reported as conflicts instead of being guessed.
- Sparse or unresolved icon paths fall back safely rather than invalidating an otherwise usable import.
Resolve duplicate names at the same parent level before migration when possible. After import, inspect parent relationships and member assignments before running bulk actions.
Existing folder-level regex values remain supported, but Advanced Auto-Rules are the current automation model.
- Empty legacy regex controls are hidden for new folders.
- A folder with a legacy regex shows a compatibility summary and current match/conflict counts.
Convert to Auto-Rulecreates an Include / Name regex rule at the end of the global rule list.- Existing higher-priority Advanced rules keep their precedence.
- Conversion creates a backup and updates rule preferences plus the folder record as one guarded workflow.
- An invalid legacy pattern is not converted automatically; repair it first.
Convert one rule, test its matches, and verify the target folder before converting a large set. Imported legacy regex continues to run until explicitly converted.
Legacy override roots remain readable:
/boot/config/plugins/folder.view/styles/boot/config/plugins/folder.view2/styles/boot/config/plugins/folder.view3/styles/boot/config/plugins/folder.view/scripts/boot/config/plugins/folder.view2/scripts/boot/config/plugins/folder.view3/scripts
Move maintained overrides into:
/boot/config/plugins/folderview.plus/styles/boot/config/plugins/folderview.plus/scripts
Keep the existing *.docker.*, *.vm.*, or *.dashboard.* suffix conventions. Disable an override by appending .disabled. Test without overrides first if the current interface clips, displays stale controls, or fails to initialize.
An imported folder can retain a valid custom or built-in icon reference. Unavailable or unreasonable icon data falls back safely. The large built-in third-party library is supplied by the separate verified icon asset pack; it is not embedded into every configuration export.
Copy user-uploaded icon data or restore the complete FolderView Plus configuration directory when moving between USB devices. See Installation and Upgrades for asset-pack recovery.
After migration, verify:
- Docker folder count, hierarchy, names, icons, order, and pinned state.
- VM folder count, hierarchy, names, icons, and order.
- Direct members and collapsed-preview visibility.
- Dashboard Docker and VM folder rendering.
- Advanced Auto-Rules and remaining legacy regex matches.
- Custom folder actions and their selected members.
- Docker start-order plan.
- Privacy masks and performance profile.
- Backups, scheduled backup settings, and Diagnostics health.
Start and stop one test container and one test VM when available. Confirm the folder preview and native expanded row reconcile without a page refresh.
If the migration is wrong:
- Stop applying new changes.
- Open
Advanced -> Recovery. - Compare the pre-import safety snapshot with the current state.
- Use Undo or restore the selected non-empty snapshot.
- If plugin-local recovery is unavailable, import the external export using the appropriate behavior mode.
- Export a sanitized support bundle before further repair if the failure is not understood.
Do not manually merge JSON fragments from different revisions. FolderView Plus maintains metadata revisions and recovery copies around durable writes; using the supported workflows preserves those relationships.