Main Content

mpminstall

Install package

Since R2024b

collapse all in page

    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.

    example

    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.

    example

    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.

    example

    Examples

    collapse all

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

    collapse all

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

    Example: “MyFolder\packageSource”

    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"

    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)

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

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

    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

    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

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

    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"

    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

    collapse all

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

    See Also

    Objects

    Functions

    Topics