Distinguish Between Packages Using Package Identifiers

The MATLAB^® Package Manager uses three pieces of information to identify and distinguish packages: a name, a version, and a universally unique identifier (UUID). Two packages created by different authors might have the same name but can be differentiated by their UUID. Similarly, an author might upload a new version of their package to a repository that also contains an older version. These two packages might have the same name and UUID but can be differentiated by their version. When an author updates an existing package and renames the package, the UUID does not change. So, MATLAB can identify an updated package with a different name.

What Is a Package Identifier?

A package identifier uniquely identifies a specific package and version using the format Name@Version@UUID with these components:

• Name — Name of the package

• Version — Package version, expressed using semantic version syntax

• UUID — Universally unique identifier for the package

For example, the identifier MyPackage@1.2.3@17487be8-15e8-447b-9319-83516fc31f08 refers to version 1.2.3 of the package MyPackage. The UUID ensures that a package can still be distinguished from different packages with the same name and version.

Package identifiers can exclude the UUID or both the version and UUID. Here are several examples of valid package identifiers:

MyPackage@1.2.3@17487be8-15e8-447b-9319-83516fc31f08
MyPackage@1.2.3
MyPackage

Package Name

A package name is the common way to refer to a package. When you create a package using mpmcreate, you must specify a name for the package. Package names are case sensitive and follow the same rules as other MATLAB identifiers, such as variables. Package names do not have to be unique. You can have multiple packages with the same name installed on your system as long as they have different UUIDs. A repository can hold multiple packages of the same name as long as they have different versions or UUIDs.

When updating an existing package, you can change the name of the package. When doing so, it is recommended that you add the previous name to the FormerNames property of the package. When searching for packages by name, such as with mpmsearch, MATLAB Package Manager checks both Names and FormerNamesproperties of packages. For more information, see Change Package Name.

Packages also include a DisplayName property. Unlike the name, which must be a valid MATLAB identifier, the DisplayName 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.

Package Version

A package version differentiates between updates to an existing package. When you create a package, you can specify a package version. If no version is specified during creation, then the default version is 1.0.0. When you make changes to an existing package, increase the version number based on the magnitude of the change.

Only one version of a package can be installed on your system at a time. However, a package repository can hold multiple versions of the same package. When installing a new package, the MATLAB Package Manager installs the latest version available unless otherwise specified.

Semantic Version Syntax

Version syntax follows the Semantic Versioning 2.0.0 format: <major>.<minor>.<patch> where each version number must be a non-negative integer, for example 1.2.3. Pre-release status is optional and is specified by adding -<pre-release> to the end of the version range, for example 1.2.3-alpha. A specific build is optional and specified by adding +<build>.

Here are several examples of valid semantic version syntax:

1.0.0
1.2.3-alpha
1.2.3-alpha+exp
3.5.1+latest

Package UUID

A package ID is represented by a universally unique identifier (UUID). When you create a package, the MATLAB Package Manager automatically generates a new UUID. The UUID helps to differentiate packages, even when they have the same name.

Package IDs remain consistent across versions of a package. When you update a package, you can change its version and even its name, and MATLAB can still recognize the package as long as the UUID remains the same.

What Is a Package Specifier?

A package specifier specifies a range of versions for given package. Specifying a range of package versions is useful when you want to search for packages within an acceptable range, such as by using the mpminstall or mpmlist functions, or when you want to add a range of acceptable versions for a package dependency. Package specifiers have a similar format to package identifiers but include a way to express a range of versions rather than one specific version. The format for package specifiers is Name@VersionRange@UUID with these components:

• Name — Name of the package

• Version range — Package version or version range, expressed using semantic version syntax

• UUID — Universally unique identifier for the package

Version range can refer to a range of versions by including the <, <=, >, or >= operators in front of a version number. For example, >2.1.13 specifies all versions later than 2.1.13. Specify more than one range separated by white space to further limit matches. For example, >2.1.13 <=2.1.15 includes versions 2.1.14 and 2.1.15, but not 2.1.13 or 2.1.16. Use the || operator to designate multiple acceptable version ranges. For example, <2.1.13 || >2.1.15 includes versions earlier than 2.1.13 and later than 2.1.15, but not 2.1.14.

Just as with package identifiers, package specifiers can exclude the UUID or both the version range and the UUID. Here are several examples of valid package specifiers:

MyPackage@>=1.2.3@17487be8-15e8-447b-9319-83516fc31f08
MyPackage@>=1.2.3
MyPackage

Version Syntax for MATLAB Releases

If you want to set the ReleaseCompatibility property of a package in order to specify a compatible MATLAB version or range of versions, you specify the MATLAB release using a different versioning format. MATLAB release do not follow the Semantic Versioning 2.0.0 standard. For MATLAB releases versions consists of three dot-separated numbers in the format: <release year>.<first or second release>.<update number>.

• The first number is equal to the last two digits of the release year.

• The second number is 1 for a releases and 2 for b releases.

• The third number corresponds to the update version.

For example, R2024b would have a version of 24.2.0. The first update for R2025a would have a version of 25.1.1. Optionally specify a prerelease status by adding -prerelease to the end of the version range, for example the prerelease version of R2025b would be 25.2.0-prerelease.