matlab.toml

R2026b

Configure MATLAB project

Since R2026b

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

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

name — Project name

TOML string

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.

path — Folders on project path

TOML string array

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

Example:

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

test — Test folders

TOML string array

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.

"requiredPackage" — Package dependency

TOML string | TOML table

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"}

"requiredProject" — Project dependency

TOML table

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.

summary — Project summary

TOML string

Project summary, specified as a TOML string.

Example:

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

startup-folder — Project startup folder

TOML string

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"

startup-files — Project startup files

TOML string array

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",
]

shutdown-files — Project shutdown files

TOML string array

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",
]

custom-tasks — Project custom tasks

TOML string array

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.

cache-file — Location to store dependency cache file

TOML string

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 — Project shortcuts

TOML tables

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 — Project labels

TOML string array

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 — Name of export profile

TOML string

Name of export profile, specified as a TOML string.

Example:

name = "myFilter"

included-files — Labeled files to include

array of TOML tables

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

Example:

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

excluded-files — Labeled files to exclude

array of TOML tables

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"},
]

excluded-labels — Labels to exclude

array of TOML tables

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

Example:

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

[[package]]

name — Package name

TOML string

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 — Package version number

TOML string

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

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

id — Package identifier

TOML string

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

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

package-root — Package root folder

TOML string

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

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

display-name — Package display name

TOML string

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 — Package summary

TOML string

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

preview-image-file — Path to image file

TOML string

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

getting-started-file — Path to getting started file

TOML string

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

output-file-name — Name of MATLAB toolbox output file

TOML string

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.

output-folder — Name of output folder

TOML string

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.

use-license-bsd — Option to embed a BSD license

true | false

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

release-compatibility — Compatible MATLAB versions

TOML string

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.

supported-platforms — Platforms that package supports

{“windows”,”macos”,”linux”} (default) | TOML string array

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

product-dependencies — MathWorks^® product names that package depends on

TOML string array

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

apps — Package apps

TOML table 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"},
]

provider — Package provider

TOML table array

Package provider, specified as a TOML table array.

Example:

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

required-additional-software — Additional required software packages

TOML table array

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]

path — Path to public MATLAB member folders

TOML string array

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

java — Folders containing Java^® path

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