matlab.toml

R2026b

Configure MATLAB project

Since R2026b

expand all in page

Configure your MATLAB® project using a matlab.toml file.

When you edit your project settings and configuration using the user interface, the project logs this information in the matlab.toml file. You might need to read and edit the matlab.toml file when comparing versions or resolving conflicts.

You can also create and configure a project from scratch using the TOML syntax.

  1. In the Files Panel, in the folder you want to create a project in, create a text file named matlab.toml.

    This action creates an unnamed project. All files in the folder are included in the project.

  2. Open the matlab.toml file as a text file. In the Files panel, right-click matlab.toml and select Open as Text. Double-clicking the matlab.toml file opens the project in the panel instead.

  3. Configure the project using the properties listed in Properties. All properties are optional.

This TOML code defines a project named My Project, where the two folders utilities and src are on the MATLAB search path. The setup.m file runs on project startup and the cleanup.m file runs on project shutdown. The project also has one shortcut topLevel in the MyShortcuts group.

name = "My Project"

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

[project]
startup-files = [
    "helper_scripts/setup.m",
]
shutdown-files = [
    "helper_scripts/cleanup.m",
]

[project.shortcuts."MyShortcuts"]
"topLevel" = {path = "src/topLevel.slx"}

Tip

Use the file separator / to ensure portability across all platforms.

Properties

expand all

All properties in the matlab.toml file are optional. The properties are grouped in tables. See details of each table below.

You can only define a TOML table once. For example, the matlab.toml file should contain only one [project] table. If you already defined [project], move all related properties to the existing table.

root table

Project name, specified as a TOML string.

Example:

name = "MyProject"

[folders]

[folders] is a TOML table that defines which folders are on the project path.

Folders added to the project path, specified as a TOML string array.

Example:

path = [
    "utilities",
    "src",
]

Folders identified as test folders, specified as a TOML string array. The project uses test folders to identify and run tests in the project.

Example:

test = [
    "tests",
]

[dependencies]

[dependencies] is a TOML table that defines all dependencies that the project requires.

A package dependency is defined by the package name and the required version, specified as a TOML string.

For more information about package versions, see VersionRange.

Example:

AudioSystem = ">=1.5"

If you have a package id, you can specify the package dependency by the package name, the required version, and the package id, specified as a TOML table.

Example:

AudioSystem = {version = ">=1.0", id = "c934c08e-5ada-4c11-a807-3a997ba41a38"}

A project dependency is defined by the project path, specified as a TOML table.

Example:

signalProcessing = {path = "../signal-processing"}

You can also specify whether the project path is a relative or absolute path.

Example:

signalProcessing = {path = "../signal-processing", absolute = true}

[project]

[project] is a TOML table that defines project settings such as project startup and shutdown files.

Project summary, specified as a TOML string.

Example:

summary = "This is my summary. It is a very long summary."

Project startup folder, specified as a TOML string.

When you define the project startup folder, when the project opens, it changes the current folder to the project startup folder. If you do not define the project startup folder, the default is the project root folder.

Example:

startup-folder = "src"

Project startup files, specified as a TOML string array.

This property contains the relative file paths of files that the project runs when opened.

Example:

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

Project shutdown files, specified as a TOML string array.

This property contains the relative file paths of files that the project runs when closed.

Example:

shutdown-files = [
    "helper_scripts/cleanup.m",
]

Project custom tasks, specified as a TOML string array.

Example:

custom-tasks = [
    "utilities/validateResults.m",
]

[project.dependency-analyzer]

[project.dependency-analyzer] is a TOML subtable that defines Dependency Analyzer configuration such as where to store the dependency cache file.

Location to store the dependency cache file, specified as a TOML string.

Example:

cache-file = "dependencycache.graphml"

[project.shortcuts]

[project.shortcuts] is a TOML subtable that defines project shortcuts.

Project shortcuts defined by their group, name, and relative path, specified as TOML tables. The group is optional.

Example:

[project.shortcuts."MyShortcuts"]
"topLevel" = {path = "src/topLevel.slx"}

You can also define shortcuts without a group.

Example:

[project.shortcuts]
"topLevel" = {path = "src/topLevel.slx"}

You can also specify an icon to associate with the shortcut.

Example:

This TOML code creates a shortcut named "Requirements" inside a group named "MyShortcuts" and associates it with an icon in the shortcut_icons folder. The shortcut runs the openRequirementsDocument function in the src folder.

[project.shortcuts."MyShortcuts"]
Requirements = {path = "src/openRequirementsDocument.m", icon = "shortcut_icons/myIcon.png"}

Note

The shortcut icon:

  • Must be in the project root folder.

  • Must be stored as a path to the PNG or GIF icon file.

[project.labels]

Project labels, defined by their category name and patterns, specified as a TOML string array. For more information about patterns, see Match Files and Folders Using Patterns.

Example:

[project.labels.Classification]
Test = [
    "**/unittests/",
    "tests/tAnswerIsCorrect.m",
    "tests/tCurrentQuestion.m",
    "tests/tNewTimesTable.m",
]

[[project.profile]]

[[project.profile]] is an array of TOML tables that defines all the export profiles in your project.

Name of export profile, specified as a TOML string.

Example:

name = "myFilter"

Labeled files to include in shared project, specified as an array of TOML tables.

Example:

included-files = [
    {category = "SourceFiles", label = "cpp"},
]

Labeled files to exclude from shared project, specified as an array of TOML tables.

Example:

excluded-files = [
    {category = "General", label = "Test"},
    {category = "Metadata", label = "Ownership"},
]

Labels to exclude from shared project, specified as an array of TOML tables.

Example:

excluded-labels = [
    {category = "Metadata", label = "Ownership"},
]

[[package]]

Name of the package, specified as a TOML string. The name must be a valid MATLAB identifier.

You must specify this property for the [[package]] table to be valid.

Version number of the package, specified as a TOML string.

You must specify this property for the [[package]] table to be valid.

Universally unique identifier (UUID) of the package, specified as a TOML string.

You must specify this property for the [[package]] table to be valid.

Relative path for package root folder, specified as a TOML string.

You must specify this property for the [[package]] table to be valid.

Displayed package name, specified as a TOML string. Unlike the name property, which must be a valid MATLAB identifier, the display-name property is not used in code and does not need to be a valid MATLAB identifier. It can include spaces, special characters, and Unicode characters to enhance readability and provide a better understanding of the package's purpose.

Summary of the package, specified as a TOML string. The summary field serves as a concise description of a MATLAB package.

Relative or absolute path to the package image file, specified as a TOML string.

Relative path to the package getting started file, specified as a TOML string. The file must be under the package root.

Name of the MATLAB toolbox output file (.mltbx file), specified as a TOML string.

The name of the resulting MATLAB toolbox file is the name of the toolbox appended with the .mltbx extension. For example, toolboxname.mltbx.

Name of the folder containing the package output files, specified as a TOML string.

The folder name must be relative to the project root or an absolute path.

Option to embed a Berkeley Software Distribution (BSD) license in the MLTBX metadata, specified as true or false.

Compatible MATLAB versions, specified as a TOML string.

Specify a MATLAB version as the full name of a MATLAB release (for example, "R2024b"), a range of MATLAB releases (for example, "R2024b - R2025b"), or as a semantic version range (for example, ">R2024b"). An empty release-compatibility property means that the package is compatible with all releases.

Platforms that the package supports, specified as a TOML string array.

List of MathWorks product names that the package depends on, specified as a TOML string array.

MATLAB executable files (.m, .mex, .mlx, .mlapp, .p) to add during package installation, specified as a TOML table array.

Example:

apps = [
  {app-file = "packageRoot\pathToYourApp"},
]

Package provider, specified as a TOML table array.

Example:

provider = {name = "providerName", organization = "providerOrganization", email = "provider@email", url = "providerURL"}

Additional required software packages to be downloaded and installed during package installation, specified as a TOML table array.

Example:

required-additional-software = {name = "addOnName", platform = "addOnPlatform", download-url = "addOnDLUrl", license-url = "addOnLicenseUrl"}

[package.folders]

Relative path to public MATLAB member folders, specified as a TOML string array.

Folders containing Java code to add the Java class path, specified as a TOML string array.

Other matlab.toml Tables

Properties related to other products such as Simulink® and MATLAB Test are grouped in separate tables.

[simulink] : See matlab.toml[simulink] (Simulink)

Version History

Introduced in R2026b

See Also

(Simulink)

Topics

External Websites