mpminstall

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. MATLAB^® searches all folders on the MATLAB path and installs the latest version.

pkg = mpminstall(packageSpecifier) installs the specified package and it's 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: ""
              Description: ""
                 Provider: <missing>
                  Folders: [1×0 PackageFolder] (1×0 PackageFolder)
             Dependencies: ""
     ReleaseCompatibility: "*"
              FormerNames: ""
                       ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"

   Package Installation
                Installed: 1
                 Editable: 0
    InstalledAsDependency: 0
              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: ""
              Description: ""
                 Provider: <missing>
                  Folders: [1×0 PackageFolder] (1×0 PackageFolder)
             Dependencies: ""
     ReleaseCompatibility: "*"
              FormerNames: ""
                       ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"

   Package Installation
                Installed: 1
                 Editable: 0
    InstalledAsDependency: 0
              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: ""
              Description: ""
                 Provider: <missing>
                  Folders: [1×0 PackageFolder] (1×0 PackageFolder)
             Dependencies: ""
     ReleaseCompatibility: "*"
              FormerNames: ""
                       ID: "bb9abc84-5324-42fd-851c-b65e2887f3b5"

   Package Installation
                Installed: 1
                 Editable: 1
    InstalledAsDependency: 0
              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 — MATLAB package specifier

string array | matlab.mpm.PackageSpecifier object array

MATLAB package specifier, specified as a string array where each element contains a package specifier or a matlab.mpm.PackageSpecifier object. A valid folder matching the input takes precedence over a valid package specifier.

Example: “packageSpecifier”

Example: “packageSpecifier@1.0.0”

Example: "Pkg@1.0.1@17487be8-15e8-447b-9319-83516fc31f08"

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 is not compatible with the ReleaseCompatibility property of the 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

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