Matlab Configure Toml Project

matlab.toml Projects

matlab.toml is a TOML-based configuration file for MATLAB projects. It defines project structure, dependencies, lifecycle scripts, shortcuts, labels, packaging, deployment, and Simulink settings. Every section is optional — the schema mandates no top-level field — but always set name, which supplies the project's display name.

matlab.toml must be placed at the project root folder — the same folder that would contain a .git/ folder or be the top-level working folder for the project.

For MATLAB R2026b and later, prefer matlab.toml for new projects. Existing .prj projects remain supported and can be converted in either direction with:

matlab.project.convertDefinitionFiles(pwd, "Toml")

Opening a project with openProject, buildtool, or runtests activates its configuration. The project's [folders].path entries then control the MATLAB path, so do not spread addpath calls through source and test files.

• Use matlab-use-package-manager for MATLAB packages.

• Use matlab-package-toolbox to author and build .mltbx MATLAB packages.

• @references/format-reference.md — complete field documentation with examples, plus the validation rules that govern the whole file

• @references/deployment-reference.md — the [compiler] deployment targets

When to Use

• The user mentions matlab.toml, or "project" in a MATLAB context (creating, editing, or inspecting a MATLAB project's configuration).

• Setting up MATLAB path folders, test folders, lifecycle scripts, shortcuts, package dependencies, reference projects, file labels, export profiles, MATLAB package metadata, deployment targets, or Simulink project settings.

• Auditing an existing matlab.toml for schema violations before they cause silent failures.

When NOT to Use

• The user wants to drive project state through the MATLAB object API directly (matlab.project.createProject, proj.addPath, etc.) rather than author or edit the file — that is a legitimate but different task; this skill's workflows assume the file is the artifact being produced.

• The task is editing a .prj-format project definition. Do not carry .prj keys or concepts over into matlab.toml — the schemas are not equivalent. A reference project may still target a .prj project.

• The task only concerns [compiler.*] deployment target internals in depth — read @references/deployment-reference.md directly rather than following the Creation/Editing workflows below, which are file-level, not per-target.

Key Functions

Creation Workflow

When a user wants to create a new matlab.toml (no existing file), follow this scan-first approach:

1. Ask for the project name. This is the only required field.

2. Scan the current folder for existing structure:

   • Find subfolders containing .m, .mlx, .slx, or .mlapp files. Propose these as [folders].path entries.

   • Identify folders whose names contain "test" (e.g., tests/, test/, unitTests/). Propose these as [folders].test entries.

   • Look for scripts matching *startup* or *setup* patterns — propose as startup-files.

   • Look for scripts matching *shutdown* or *cleanup* or *teardown* patterns — propose as shutdown-files.

   • Exclude hidden folders (.git, .svn, etc.) and common output folders (derived/, results/, build/).

3. Generate a draft starting minimal — name, folders, and any discovered lifecycle scripts. Present it to the user.

4. Ask about optional sections as needed, not as a checklist:

   • MATLAB packages (not MathWorks products) and reference projects

   • Shortcuts to frequently-used scripts

   • File labels and export profiles (only if used in code or explicitly requested)

   • MATLAB package metadata ([[package]]) if the project ships as an .mltbx

   • Deployment targets ([compiler.*]) if the project builds a standalone app, library, or language package

   • Simulink settings (if .slx files are present)

5. After generating the TOML file, ask the user if they want the folders listed in [folders] to be created on disk (for nonexistent folders in new projects).

Start minimal and let the user add sections incrementally. One focused question at a time is better than a long questionnaire.

Editing Workflow

When a matlab.toml already exists and the user wants to modify it:

1. Read the existing matlab.toml to understand the current configuration.

2. Map the user's request to schema sections. Identify which section(s) need changes — refer to @references/format-reference.md for valid fields and formats.

3. Make targeted edits. Modify only the sections the user asked about. Do not restructure, reformat, or reorder untouched sections. Preserve any user comments (# lines) in the file.

4. Validate against the schema yourself. openProject does not report schema violations — unknown keys, missing files, and wrong value types all load silently and are simply ignored. A successful openProject is not evidence the file is correct, so check every key against @references/format-reference.md rather than relying on MATLAB errors and warnings:

   • Dependency values must use one of the three supported formats (package version string, package version with ID, or reference-project path).

   • Array-of-tables ([[project.profile]], [[package]], [[matlab.test.test-suite]], [[compiler.*]]) syntax must be correct.

   • No unknown keys. Every table except [user] is closed. Do not invent keys or carry over keys from .prj files.

   • Path keys must resolve. Most path values must point at files that exist and live inside the project root. Few paths (startup-folder, dependency path) can be outside the project root. Output paths (cache folders, build output) do not need to exist. The reference annotates each key. Confirming a path means listing the folder and seeing the entry — a truncated, filtered, or head-limited listing that fails to show it is not a confirmation, and neither is a ls of a guessed name that returns nothing.

   • Required fields must be present: id and package-root in [[package]], name in [[compiler.standalone]], path in project-path dependencies and shortcuts, version in version-with-ID dependencies, and both category and label in every label filter.

5. Present the change — show the user what will be modified before writing the file.

Conventions

• Author the TOML directly. Do not produce matlab.toml by driving matlab.project.createProject and reading back what MATLAB wrote — write the file yourself, with the sections in the order given above.

• Tables are closed. Every table except [user] rejects unrecognized keys. Never invent a key or carry one over from a .prj file; check every key against @references/format-reference.md.

• openProject is not a validator. A file that opens cleanly may still contain silently-ignored schema violations — the only way to be sure a key is correct is to look it up.

• Path values must be confirmed, not guessed. Listing a folder and seeing the entry is a confirmation; a truncated, filtered, or head-limited listing that fails to show it is not, and neither is an ls of a guessed name that returns nothing.

• MathWorks products are never [dependencies] entries. [dependencies] accepts any key, so a product name loads silently and wrongly. Record product requirements elsewhere (e.g. [project].summary, [[package]].product-dependencies, or a comment).

• Preserve what the user didn't ask you to touch. Comments and section order in an existing file survive an edit unless the user's request required changing them.

Quick Reference

[[package]] can include MATLAB code, Simulink models, apps, documentation, and other project content in the resulting MATLAB package. Use matlab-package-toolbox for the authoring and build workflow, or matlab-use-package-manager to install a completed package.

Package Dependencies and Reference Projects

Each key under [dependencies] names either a MATLAB package or a reference project. MathWorks products are not packages and must not be listed here.

Package dependency: version string — for a MATLAB package:

mytoolbox = "3.*"

Package dependency: version with ID — when the package ID is available:

motor = {version = "*", id = "9b9e5bc2-a583-4d79-98c5-d2b9af135697"}

Reference project — for a project at a filesystem path (absolute is optional and defaults to relative):

shared-utils = {path = "../shared_utils_lib"}

The referenced project can use either a legacy .prj definition or a matlab.toml definition. The key is a display label chosen by the user and is unrelated to the folder on disk. Confirm path by listing the candidate parent folder — never derive it from the dependency name or from the other project's name.

Examples

Minimal

name = "My Project"

Typical

name = "Signal Analyzer"

[folders]
path = [
    "src",
    "utilities",
]
test = [
    "tests",
]

[dependencies]
signal-processing = "2.*"

[project]
startup-files = [
    "setup/initialize.m",
]

[project.shortcuts]
"Run Analysis" = {path = "scripts/analyze.m"}

Copyright 2026 The MathWorks, Inc.