---

name: matlab-migrate-settings description: Diff MATLAB settings between releases AND update any .m file that configures MATLAB settings to use the correct setting paths for the target release. Use when upgrading MATLAB releases and startup scripts or preference files need path/type updates for the new release. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.1"

MATLAB Settings Migration

Diff MATLAB settings between two releases and automatically update any .m file that configures MATLAB settings (via .PersonalValue or .TemporaryValue assignments) so that setting paths point to the correct locations in the target release. Works with startup scripts, team preference files, test setup scripts, deployment configs, or any code that programmatically sets MATLAB settings.

When To Use

• Upgrading MATLAB releases and existing .m scripts set PersonalValue or TemporaryValue on settings whose paths changed between releases
• Setting paths moved, were renamed, or had their value types changed between the source and target release
• Migrating startup scripts, team preference files, test setup, or deployment configs to a newer (or older) MATLAB release

When Not To Use

• The .m file does not set any MATLAB settings (s.PersonalValue / s.TemporaryValue assignments)
• You want to change MATLAB preferences interactively (use the Preferences dialog instead)
• You need to migrate Simulink or toolbox-specific settings (this skill covers core MATLAB settings only)

Arguments

• <script-path> — (required) Path to any .m file that sets PersonalValue/TemporaryValue on MATLAB settings
• [from:R20XXy] or [from:/path/to/MATLAB/R20XXy] — (optional) Source release the script was written for. Accepts either a release name (e.g., R2025b) which is resolved to the platform default install location, or a full path to a MATLAB installation root. If omitted, auto-detected from script content.
• [to:R20XXy] or [to:/path/to/MATLAB/R20XXy] — (optional) Target release to migrate to. Accepts either a release name or a full path to a MATLAB installation root. If omitted, defaults to the latest installed MATLAB release on this machine.

Examples:

/matlab-settings-migrate ~/startup.m
/matlab-settings-migrate ~/startup.m from:R2025b to:R2026a
/matlab-settings-migrate ~/startup.m to:R2025a
/matlab-settings-migrate ./test/setup_prefs.m from:/opt/matlab/R2025b to:/opt/matlab/R2026a
/matlab-settings-migrate ~/team_settings.m from:/network/apps/MATLAB/R2024b to:R2026a

Default behavior (no from/to): Detect the source release from the script, then migrate to the newest installed MATLAB release. If you want to migrate to an older release (downgrade), specify to: explicitly.

Argument parsing

Parse the arguments string to extract:

1. The script path (first argument that looks like a file path)
2. Optional from: value — either a release name (R20XXy) or a full path (/path/to/MATLAB/R20XXy)
3. Optional to: value — either a release name (R20XXy) or a full path (/path/to/MATLAB/R20XXy)

Path resolution: If the value after from: or to: starts with /, ~, or a drive letter (e.g., C:\), treat it as a full path to a MATLAB installation root. Otherwise, treat it as a release name and resolve it to a full path using the platform-specific default install location (determined in Phase 0).

If only the script path is provided, run Phase 0 (auto-discovery).

Phase 0: Auto-detect MATLAB installations (skip if both roots provided)

If from: or to: are missing, auto-detect installed MATLAB releases. Read references/auto-detect-installations.md for the full procedure (platform detection, folder scanning, source/target resolution). Key behavior:

• Detect platform via uname -s → determines default install directory
• List installed releases by scanning the default directory for R20* folders
• Source release: detected from script content (filename hints, comments, or key matching against SO/DLLs)
• Target release: defaults to the latest installed release (unless to: was explicit)
• Downgrade requires explicit to: — default always goes to the latest

How to execute

Performance constraint: Minimize tool calls. Target ≤6 total bash/read invocations for the entire migration. Batch aggressively — never check settings one-by-one in separate commands. Phase 1 setup (find libs, extract strings, diff) and Phase 2 (read startup script) are independent and MUST run in parallel.

Phase 1: Build the settings change map

Produce the full change map (renamed, moved, removed, added) between releases.

Step 1: Validate paths and determine source format

Check for .hpp source files first (available on some Linux installs):

OLD_HPP=<old-matlab-root>/toolbox/matlab/settings/matlab_factory_settings
NEW_HPP=<new-matlab-root>/toolbox/matlab/settings/matlab_factory_settings

If .hpp files exist in both, use the HPP path (Step 2A). If .hpp files do NOT exist (common on Windows where they are compiled to DLLs), use the DLL path (Step 2B).

To locate the shared library (extension depends on platform detected in Phase 0):

# Linux: .so | macOS: .dylib | Windows: .dll
find "<matlab-root>/bin" -path "*factory_settings*" -name "mwmatlab_factory_settings.*" 2>/dev/null
# Typical paths:
#   Linux:   <root>/bin/glnxa64/factory_settings/compute/settings/matlab/mwmatlab_factory_settings.so
#   macOS:   <root>/bin/maci64/factory_settings/compute/settings/matlab/mwmatlab_factory_settings.dylib
#   Windows: <root>/bin/win64/factory_settings/compute/settings/matlab/mwmatlab_factory_settings.dll

Step 2A: HPP path (plain-text source available)

File-level diff

Compare which .hpp files exist in each release:

ls "$OLD_HPP"/*.hpp | xargs -I{} basename {} | sort > /tmp/hpp_old.txt
ls "$NEW_HPP"/*.hpp | xargs -I{} basename {} | sort > /tmp/hpp_new.txt
comm -23 /tmp/hpp_old.txt /tmp/hpp_new.txt   # files only in OLD (removed)
comm -13 /tmp/hpp_old.txt /tmp/hpp_new.txt   # files only in NEW (added)

For any NEWLY added .hpp file, read it and list all settings it defines. For any REMOVED .hpp file, read it from OLD and list all settings.

Extract all setting names with namespace context

For EACH .hpp file that exists in BOTH releases, extract addSetting and addGroup lines:

grep -n "addSetting\|addGroup" "$OLD_HPP/factorysettings_XXXX.hpp"
grep -n "addSetting\|addGroup" "$NEW_HPP/factorysettings_XXXX.hpp"

The group hierarchy gives you the full setting path:

• matlabFactoryGroup.addGroup("editor") → matlab.editor
• editor.addGroup("spelling") → matlab.editor.spelling
• spelling.addSetting("CheckSpelling") → matlab.editor.spelling.CheckSpelling

Diff setting names within each file

For each shared .hpp file:

1. Identify settings REMOVED (in old, not in new)
2. Identify settings ADDED (in new, not in old)
3. For removed+added pairs in the same namespace, determine if it's a RENAME (same group, different key name) vs. truly removed/added

Extract type and validation for changed settings

For every setting that is renamed, moved, or split, extract the full addSetting block (not just the name line) from BOTH releases — capture FactoryValue, ValidationFcn, and any ValueValidator:

grep -B 5 -A 8 'spelling.addSetting("CheckSpelling"' "$NEW_HPP/factorysettings_editor.hpp"

See references/settings-internals.md for reading types from these fields and for the type-transition mapping rules (same type, type changed, type narrowed). Confirm the result against the target runtime before translating a value — class(o.FactoryValue) is authoritative where the hpp is ambiguous.

Classify and determine moves

For settings that appear removed from one file and added to another file, classify as MOVED.

Optional — verify renames via JS panel source

If a rename is ambiguous from hpp alone, confirm by reading the JS panel source files.

Step 2B: DLL path (compiled binary — Windows/macOS/Linux without source)

When .hpp source files are not available, extract setting names and type information directly from the compiled factory settings library using strings. Read references/dll-path-extraction.md for the full procedure — it covers string table extraction, batch context verification, rename classification decision tree, and type extraction. Key principles:

• SO/DLL stores group names and key names as separate adjacent strings, NOT dotted paths — do NOT grep full paths
• Use grep -B40 -A5 for group context; the IMMEDIATE parent group (last lowercase name above the key) gives the runtime path
• String presence ≠ setting existence — confirm keys are in valid addSetting position, not just present as dead strings
• Before classifying as "Removed", search the entire target SO/DLL for partial key name matches (renames can cross groups)
• For type changes, use -A15 context to find ValidStringValues — never stringify boolean literals

Phase 2: Parse the user's script

Step 7: Read the script and identify all settings references

Read <script-path> and find every line that references a setting path. Users may use ANY variable name for the settings root — not just s. Common patterns:

1. Direct assignment — s.matlab.editor.spelling.CheckSpelling.PersonalValue = false;
2. Any variable name — prefs, mySettings, settings_root, etc.
3. Variable from settings — prefs = settings; then prefs.matlab...
4. Inside try-catch — nested fallbacks for cross-release compatibility; migrate every branch
5. Version-conditional — if isMATLABReleaseOlderThan("R2026a") ... else ... end; migrate both branches

Detection strategy:

1. Find the settings variable: look for = settings; or = matlab.settings.SettingsGroup or any variable used with .matlab. followed by known setting paths.
2. Extract the variable name (everything before .matlab.).
3. Extract the full setting path (everything between the variable and .PersonalValue, .TemporaryValue, or .FactoryValue).

Build a list of (line_number, variable_name, full_setting_path, assigned_value) tuples.

Step 8: Positively verify EACH script setting in the target release

This is the critical correctness gate. Do NOT rely solely on the diff/change map from Phase 1. For EVERY setting key extracted from the user's script, positively confirm it exists in the target release by grepping the target's hpp files or DLL.

HPP path (preferred — fast and definitive):

# Batch-verify ALL keys from the script in ONE command against target hpp files:
for key in Key1 Key2 Key3 ...; do
  echo "=== $key ==="; grep -r "addSetting(\"$key\"" "$NEW_HPP"/ || echo "NOT FOUND"
done

If addSetting("KeyName") is NOT found in any target hpp file, the setting does NOT exist in the target — regardless of what the Phase 1 diff said.

DLL path (when hpp unavailable): Use the addSetting context verification from Phase 1 Step 2B — the key must appear in valid definition position below its parent group.

Runtime confirmation (authoritative — required before classifying anything as Removed). Grep proves only that a string is present; hasSetting proves a setting is defined at a given path. Batch it over the script's keys:

s = settings;
s.matlab.<group>.hasSetting('<Key>')   % 1 = exists here, 0 = not here

Step 9: Classify each setting based on verification results

For each setting from the user's script, classify using BOTH the Phase 1 change map AND the Step 8 verification:

1. Unchanged — key found via addSetting in target at the same full path → no action
2. Renamed — key NOT found at old path, but Phase 1 change map identifies a rename → update key name
3. Moved — key found in target but under a di