mpminstall

R2026b

Install package

Since R2024b

Syntax

pkg = mpminstall(packageFolder)

pkg = mpminstall(packageSpecifier)

pkg = mpminstall(pkgArray)

pkg = mpminstall(___,Name=Value)

Description

pkg = mpminstall(packageFolder) installs the specified package folder and its dependencies, adds them to the path, and returns a matlab.mpm.Package object.

pkg = mpminstall(packageSpecifier) installs the specified package and its dependencies and adds them to the path. By default, the function searches all known repositories and installs the latest version.

pkg = mpminstall(pkgArray) installs the specified packages and their dependencies. The function copies packages and their dependencies to the default installation area. All packages specified in the argument list are added to the MATLAB^® path.

pkg = mpminstall(___,Name=Value) specifies options using one or more name-value arguments. For example, you can specify whether to install package dependencies and whether to add the package member folders to the beginning or end of the MATLAB path.

Examples

Install Package

Install the package MyPackage. When prompted, confirm the installation.

pkg = mpminstall("MyPackage")

The following packages will be installed:
    MyPackage@1.0.0

Do you want to continue? [YES/no]:


Copying MyPackage@1.0.0 package...Done.

Successfully added the following packages to the path:
    MyPackage  (help)

Installation complete.


pkg = 

  Package with properties:

   Package Definition
                     Name: "MyPackage"
              DisplayName: "MyPackage"
                  Version: 1.0.0 (1×1 Version)
                  Summary: ""
                     Tags: [1×0 string]
                   Readme: ""
                 Provider: <missing>
                  Folders: [1×0 PackageFolder] (1×0 PackageFolder)
             Dependencies: ""
     ReleaseCompatibility: "*"
       SupportedPlatforms: [1×1 matlab.mpm.PlatformConfiguration]
              FormerNames: ""
                       ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"

   Package Installation
                Installed: 1
                 Editable: 0
        DirectlyInstalled: 1
              PackageRoot: "C:\Users\MyProfile\AppData\Roaming\MathWorks\MATLAB Add-Ons\MyPackage@1.0.0"
    InstalledDependencies: ""
      MissingDependencies: ""

   Repository
               Repository: [0×0 Repository]

  help MyPackage

Install Package Using Root Folder

Install the package MyPackage by specifying the root folder. When prompted, confirm the installation.

pkg = mpminstall("C:\MyCode\PackageRootDir")

The following packages will be installed:
    MyPackage@1.0.0

Do you want to continue? [YES/no]:


Copying MyPackage@1.0.0 package...Done.

Successfully added the following packages to the path:
    MyPackage  (help)

Installation complete.


pkg = 

  Package with properties:

   Package Definition
                     Name: "MyPackage"
              DisplayName: "MyPackage"
                  Version: 1.0.0 (1×1 Version)
                  Summary: ""
                     Tags: [1×0 string]
                   Readme: ""
                 Provider: <missing>
                  Folders: [1×0 PackageFolder] (1×0 PackageFolder)
             Dependencies: ""
     ReleaseCompatibility: "*"
       SupportedPlatforms: [1×1 matlab.mpm.PlatformConfiguration]
              FormerNames: ""
                       ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"

   Package Installation
                Installed: 1
                 Editable: 0
        DirectlyInstalled: 1
              PackageRoot: "C:\Users\MyProfile\AppData\Roaming\MathWorks\MATLAB Add-Ons\MyPackage@1.0.0"
    InstalledDependencies: ""
      MissingDependencies: ""

   Repository
               Repository: [0×0 Repository]

  help MyPackage

Install Package in Authoring Mode

Install the package MyPackage in authoring mode by specifying the root folder and the Authoring name-value argument. In authoring mode, the mpminstall function installs the package in its current location rather than in the default installation area and makes the package editable. When prompted, confirm the installation.

pkg = mpminstall("C:\MyCode\PackageRootDir",Authoring=true)

The following packages will be installed:
    MyPackage@1.0.0

Do you want to continue? [YES/no]:


Copying MyPackage@1.0.0 package...Done.

Successfully added the following packages to the path:
    MyPackage  (help)

Installation complete.


pkg = 

  Package with properties:

   Package Definition
                     Name: "MyPackage"
              DisplayName: "MyPackage"
                  Version: 1.0.0 (1×1 Version)
                  Summary: ""
                     Tags: [1×0 string]
                   Readme: ""
                 Provider: <missing>
                  Folders: [1×0 PackageFolder] (1×0 PackageFolder)
             Dependencies: ""
     ReleaseCompatibility: "*"
       SupportedPlatforms: [1×1 matlab.mpm.PlatformConfiguration]
              FormerNames: ""
                       ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"

   Package Installation
                Installed: 1
                 Editable: 1
        DirectlyInstalled: 1
              PackageRoot: "C:\MyCode\PackageRootDir"
    InstalledDependencies: ""
      MissingDependencies: ""

   Repository
               Repository: [0×0 Repository]

  help MyPackage

Input Arguments

packageFolder — MATLAB package folder

string array

MATLAB package folder, specified as a string array where each element contains a package root folder.

Example: “MyFolder\packageSource”

packageSpecifier — Package specifier

string scalar | character vector | matlab.mpm.PackageSpecifier object array | matlab.mpm.PackageIdentifier object array

Package specifier, specified as a string scalar, character vector, a matlab.mpm.PackageSpecifier object array, or a matlab.mpm.PackageIdentifier object array. If packageSpecifier is a string scalar or character vector, then it must contain a package specifier in the format "Name", "Name@VersionRange", or "Name@VersionRange@ID". This option limits the output to only packages whose package specifier fits the specified value.

For additional information on package specifiers and their syntax, see What Is a Package Specifier?.

Example: "MyPackage"

Example: "MyPackage@1.0.1"

Example: "MyPackage@1.0.1@9ecfea6b-1710-4fb9-aa66-e4750f0e8251"

pkgArray — MATLAB package

matlab.mpm.Package object array

MATLAB package, specified as a matlab.mpm.Package object array.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: pkg = mpminstall(pkgArray,Prompt=true)

Prompt — Display installation prompts

true or 1 (default) | false or 0

Display installation prompts, specified as a numeric or logical 1 (true) or 0 (false). If you specify Prompt as false, then installation prompts are not displayed and the function automatically confirms that packages should be installed when prompted.

Example: Prompt=false

Verbosity — Verbosity level for displayed information

"normal" (default) | "quiet" | "detailed"

Verbosity level for displayed information, specified as one of these values:

• "normal" (default) — Display informational messages during installation.

• "quiet" — Do not display informational messages.

• "detailed" — Display additional informational messages.

Example: Verbosity="quiet"

InstallDependencies — Install dependencies

true or 1 (default) | false or 0

Install dependencies, specified as a numeric or logical 1 (true) or 0 (false). If you specify InstallDependencies as false, then the function does not install package dependencies.

Example: InstallDependencies=false

Force — Force installation

false or 0 (default) | true or 1

Force installation, specified as a numeric or logical 1 (true) or 0 (false). If you specify Force as true, then the function installs packages even if a dependency is not found or if the MATLAB version or platform is not compatible with the ReleaseCompatibility or SupportedPlatforms properties of the installed package.

When a dependency of the updated package conflicts with an already installed package or dependency and you specify Force as true, then the updated dependency overwrites the installed package or dependency even if it breaks an installed package. For example, if the installed packageA depends on version 1.0.0 of packageB and you call mpmupdate with Force as true on packageC, which depends on version 2.0.0 of packageB, then mpmupdate overwrites version 1.0.0 of packageB with version 2.0.0 and breaks the dependency of packageA. (since R2026b)

Before R2026b: mpminstall does not overwrite installed packages or dependencies if it would break an installed package.

Example: Force=true

AllowVersionReplacement — Allow replacement of installed version

false or 0 (default) | true or 1

Allow replacement of installed version, specified as a numeric or logical 1 (true) or 0 (false). If you specify AllowVersionReplacement as true, then the function can replace any previously installed version of a package with the specified version so that only one version of the package is installed. If false, then an error is thrown when the package to be installed matches an already installed package.

Example: AllowVersionReplacement=true

InPlace — Install in place

false or 0 (default) | true or 1

Install in place, specified as a numeric or logical 1 (true) or 0 (false). If you specify InPlace as true, then the function installs the package in its current location rather than copying it to the default installation area.

Inputs must be root folders when InPlace is true.

Example: InPlace=true

Editable — Enable editable mode

false or 0 (default) | true or 1

Enable editable mode, specified as a numeric or logical 1 (true) or 0 (false). If you specify Editable as true, then the function installs the package in editable mode and MATLAB will recognize changes to the package definition file and member folders. InPlace must also be true.

The package to be installed must be specified as a package root folder or as a matlab.mpm.Package object created from a package root folder when Editable is true.

Example: Editable=true

Temporary — Temporary install

false or 0 (default) | true or 1

Temporary install, specified as a numeric or logical 1 (true) or 0 (false). If you specify Temporary as true, then the function installs the package only for the current MATLAB session.

Example: Temporary=true

PathPosition — Position on MATLAB path

"end" (default) | "beginning"

Position on the MATLAB path, specified as "end" or "beginning". This value determines if package member folders are added to the end or beginning of the MATLAB path, respectively.

Example: PathPosition="beginning"

Authoring — Enable authoring mode

false or 0 (default) | true or 1

Enable authoring mode, specified as a numeric or logical 1 (true) or 0 (false). If you specify Authoring as true, then Editable and InPlace are automatically set to true and PathPosition is automatically set to "beginning".

pkgArray must be a root folder when Authoring is true.

Example: Authoring=true

DryRun — View installation changes without installation

false or 0 (default) | true or 1

Since R2026b

View installation changes without installation, specified as a numeric or logical 1 (true) or 0 (false). If you specify DryRun as True, then the names and versions of all packages and their dependencies that would be installed are displayed without installation. If AllowVersionReplacement is true, then the names and versions of packages and dependencies that would be removed are displayed as well. Use this information to verify the packages you are installing are the correct packages.

Output Arguments

pkg — Installed packages

matlab.mpm.PackageSpecifier object array

Installed packages, specified as a matlab.mpm.PackageSpecifier object array.

Tips

• Packages installed from MATLAB launched in -batch mode do not persist across sessions.

• During package installation the event is logged by the system audit logger. MATLAB records the following information for each installed package and dependency:

  • Package ID

  • Originating repository

  • Download URL

  • Download destination

  • Package digest, as returned by digest

Algorithms

Package Resolution During Installation

When installing a package, the MATLAB Package Manager determines if a package matching the specified package ID and a version in the specified version range is already installed or on the list of packages to be installed. If not, then MATLAB searches the known repositories for available packages that meet all the following conditions:

• The package identifier matches the specified package name or ID. Package names are matched case-insensitively.

• The version is compatible with the specified version range.

• The ReleaseCompatibility property value is compatible with the MATLAB release being used.

MATLAB searches each repository on the known repository list in order. If a repository has multiple packages that meet these conditions, then MATLAB selects the package with the latest semantic version. Once a package that meets the conditions has been found, other repositories on the list of known repositories are not searched.

When a package is installed from a repository that repository becomes the package owner and MATLAB will only install newer versions of that package from the same repository. If the version in that repository does not match the specified version range then MATLAB throws an error. Packages installed directly from a file path are still installed even if that package is owned by a repository. (since R2026b)

When installing a package, MATLAB determines required dependencies to install as well.

For each required dependency, MATLAB determines if a package matching the dependency package ID and a version compatible with the package version range is already installed or on the install list. If so, MATLAB skips the dependency and advances to the next required dependency. If not, MATLAB searches the known repositories for the dependency package following the same process as for the original package.

If a package or required dependency conflicts with an already installed package, installation will not proceed and an error will be thrown. If the AllowVersionReplacement Name-Value argument is specified as true, then the required dependency version will replace the installed version.

If installed dependencies have their own dependencies, MATLAB follows the same process recursively until it finds and installs all required packages.

Package Installation Location

Once the MATLAB Package Manager has identified all the packages to install, MATLAB copies the files from the source to the installation area. The default installation area is the same as the add-ons installation folder. For additional information and see Default Add-On Installation Folder.

During package installation, MATLAB creates a folder in the installation area named for the package name, version, and ID. The folder name can be truncated or modified to comply with the naming conventions of the local file system.

If the package source is a folder and the package InPlace property is true, then MATLAB does not copy the package.

Package Registration and the MATLAB Path

After copying packages to the installation area, MATLAB registers the packages and their dependencies and adds the package root folder and all subfolders to the MATLAB path. During package registration, MATLAB adds the package root folder and all subfolders to the MATLAB path based on the PathPosition property.

Version History

Introduced in R2024b

R2026b: Packages resolve from same repository

Installing a package from a repository designates that repository as the package owner. When you attempt to install a new version of that package MATLAB attempts to install from the owning repository. If you specify a version that the owning repository does not have then installation fails and an error is thrown, even if a different repository on the list of known repositories has a version that meets the specifications.

Packages installed directly from a file path are still installed even if that package is owned by a repository.

R2026b: Package installation logged by system audit logger

During package installation the event is logged by the system audit logger. MATLAB records the following information for each installed package and dependency:

• Package ID

• Originating repository

• Download URL

• Download destination

• Package digest, as returned by digest

Audit logger behavior varies by operating system. In a Windows^® system audit logging must be enabled. Open a Windows PowerShell command prompt as an administrator and run this command:

$source = "MathWorks"
$logName = "Application"
$eventSourceExists = [System.Diagnostics.EventLog]::SourceExists($source)

if (-not $eventSourceExists) {
    [System.Diagnostics.EventLog]::CreateEventSource($source, $logName)
    Write-Host "Event source $source created successfully."
} else {
    Write-Host "Event source $source already exists."
}

You can then specify what level of severity you want to log by creating a new REG_DWORD in the event source HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\MathWorks and setting its value to 0 to log nothing, 1 to log only critical severity, 4 to log notice severity, or 7 to log all levels.

Audit logging is on by default for Linux^® and Mac systems. You can disable audit logging or set the logging level by creating a file: /etc/mathworks/settings.json in Linux and /Library/Preferences/SystemConfiguration/MathWorks/settings.json in MacOS. To the file add:

{
  "auditlogging": {
    "level": "all"
  }
}

Set the level property to "all" to log all events, "critical" to log only critical events, or "none" to turn it off.

R2026b: Use DryRun option to see changes installing a package before proceeding with installation

Specify DryRun as True to view the names and versions of all packages and their dependencies that would be installed before actually installing anything. If AllowVersionReplacement is true, then the names and versions of packages and dependencies that would be removed are displayed as well. Use this information to verify the packages you are installing are the correct packages.

R2026b: Force=true installs specified packages and dependencies even if that breaks existing dependencies

When a dependency of a the installed package conflicts with an already installed package or dependency and you specify Force as true, then the newly-installed dependency overwrites the installed package or dependency even if this breaks an installed package.

For example, if the installed packageA depends on version 1.0.0 of packageB and you call mpminstall with Force as true on package C which depends on version 2.0.0 of packageB, then mpminstall overwrites version 1.0.0 of packageB with version 2.0.0 and this breaks the dependency of packageA.

Before R2026b: mpminstall does not overwrite installed packages or dependencies if it would break an installed package.