Migrating from an older version¶
Upgrading Understand is mostly transparent — install the new build and keep working. A few things change on first open, and if you script Understand there are API changes to plan for.
Opening an older .und project¶
When you open a project created by an older build whose database format differs, Understand cannot reuse the stored analysis, so it re-analyzes the project automatically on open. Concretely:
- The database's format version is compared with the current build's. If they differ, all stored parse data is discarded and a full re-analysis runs. (Empty databases are treated the same way and analyzed on open.)
- If only one language's parse format changed, Understand re-parses just that language's files and keeps the rest, so the update is faster.
The source code must still be reachable
Re-analysis reads your source files again. Before opening an old project on a new build, make sure the source is present at the paths the project expects. If the source has moved or is on a different machine, see A teammate can't open my project / paths broke.
Command line
A .und opened headless behaves the same way. To force a rebuild explicitly, run
und analyze <project>.und — see The und command line.
Settings¶
Your settings live in a per-user settings folder, not inside the project, so preferences carry across an upgrade in place. You do not normally need to re-enter anything.
Changing the settings folder forces a re-analyze
If you move the settings folder (Preferences → Advanced), Understand deletes all existing parse information and every project is re-analyzed the next time it is opened. Open projects are closed first. Only change this when you intend to accept a full rebuild.
Scripts and plugins¶
Python API — review the 8.0 breaking changes¶
Understand 8.0 changed a few Python API behaviors (the Metric class, plugin-author classes renamed
with a Context suffix, and a new reference kind). If you maintain 7.x scripts, read
Breaking API changes in 8.0 before porting, and confirm against the API
reference shipped with your build (Help → Python API Documentation).
A handful of individual methods are also marked deprecated across versions (for example
add_annotation_file, map, option, and simplename); their replacements are noted inline in the
API reference. See Deprecated tools & features.
Perl scripts — plan to port them¶
The Perl API is deprecated as of 2026 and will be removed in a future release. Existing .pl
scripts and Perl CodeCheck checks (.upl) still run today, but new work should target Python. See
Which API should I use? for the porting path.