### 37.2 Installing and Removing Packages ¶

Assuming a package is available in the file `image-1.0.0.tar.gz` it can be installed from the Octave prompt with the command

    pkg install image-1.0.0.tar.gz

If the package is installed successfully nothing will be printed on the prompt, but if a warning or error occurred during installation it will be reported. It is possible to install several packages at once by writing several package file names after the `pkg install` command. If a different version of the package is already installed it will be removed prior to installing the new package. This makes it easy to upgrade and downgrade the version of a package, but makes it impossible to have several versions of the same package installed at once.

To see which packages are installed type

    pkg list
    ⊣ Package Name  | Version | Installation directory
    ⊣ --------------+---------+-----------------------
    ⊣        image *|   1.0.0 | /home/jwe/octave/image-1.0.0

In this case, version 1.0.0 of the `image` package is installed. The `'*'` character next to the package name shows that the image package is loaded and ready for use.

It is possible to remove a package from the system using the `pkg uninstall` command like this

    pkg uninstall image

If the package is removed successfully nothing will be printed in the prompt, but if a warning or error occurred it will be reported. It should be noted that the package file used for installation is not needed for removal, and that only the package name as reported by `pkg list` should be used when removing a package. It is possible to remove several packages at once by writing several package names after the `pkg uninstall` command.

To minimize the amount of code duplication between packages, it is possible that one package depends on another one. If a package depends on another, it will check if that package is installed during installation. If it is not, an error will be reported and the package will not be installed. This behavior can be disabled by passing the `-nodeps` flag to the `pkg install` command

    pkg install -nodeps my_package_with_dependencies.tar.gz

Since the installed package expects its dependencies to be installed it may not function correctly. Because of this it is not recommended to disable dependency checking.

pkg `command` ¶
pkg `command pkg_name` ¶
pkg `command pkg_name1 pkg_name2 …` ¶
pkg `command option1 … pkg_name1 …` ¶
`[out1, …] =` pkg `(command, …)` ¶

  Manage or query packages (groups of add-on functions) for Octave.

  Depending on the value of command and on the number of requested return arguments, `pkg` can be used to perform several tasks. Possible values for command are:

  ‘`search`’

    Search for packages having the specified search terms in the Octave Packages index. This may require an internet connection and the cURL library.

        pkg search foo bar baz

    shows packages whose descriptions contain all the search terms.

    Search terms are case-insensitive and can be regular expressions as well. For example,

        pkg search "[aeiou]{4,}"

    shows all packages whose descriptions have four or more consecutive vowels.

    The option `-all` as in

        pkg search -all

    shows all packages available on the Octave Packages index (not only those that can be installed with the `pkg` command).

    By default, the Octave Packages index is downloaded only once per Octave session in order to improve performance and to reduce the load on the index server during repeated searches. An update of the index can be enforced with the option `-refresh`:

        pkg search -all -refresh foo

    If an output variable is provided, as in

        mypackages = pkg ("search", "foo")

    then `pkg search` returns only those package names matching the search term(s) and which can be installed with `pkg install`.

  ‘`install`’

    Install named packages. For example, each of the following commands:

        pkg install pkgname
        pkg install 'pkgname-1.0.0.tar.gz'
        pkg install 'https://somewebsite.org/pkgname-1.0.0.tar.gz'

    might install the package `pkgname`. The sequence for the resolution of the arguments after `pkg install` is:

    1. If `pkgname` is a local file, Octave installs it.
    2. Otherwise, if `pkgname` resembles a URL, Octave downloads and installs it.
    3. Otherwise, Octave queries the Octave Packages index online for a package named `pkgname`, and if found, downloads and installs its latest version. If the Octave Packages index cannot be reached, a locally cached version of the index might be used. The Octave Packages index is only downloaded once per Octave session (unless an index refresh is requested with the option `-refresh`).

    Online access requires an internet connection and the cURL library.

    No support: the GNU Octave community is not responsible for any installed packages. For support or for reporting bugs, you need to contact the maintainers of the installed package directly (run `pkg describe` on the package to get information).

    The following options are accepted for `pkg install`:

    `-nodeps`

      Disable dependency checking. With this option it is possible to install a package even when it depends on another package which is not installed on the system. Use this option with care.

    `-local`

      A local installation (package available only to current user) is forced, even if Octave is being run with administrative privileges.

    `-global`

      Force a global installation (package available to all users), even if Octave is not being run with administrative privileges. The user must have write access to the global package store.

    `-verbose`

      Print the output of all commands as they are performed.

    `-refresh`

      Force an update of the cached package database from the online index. By default, Octave tries to download the Octave Packages index only once per Octave session. This option forces refreshing the index even if it was already downloaded in the current Octave session. The option `-refresh` applies to `install`, `search`, and `update` commands.

    `-forge`

      The option `-forge` forces an installation of a package from the Octave Packages index. It cannot be used to install packages from a URL or a local file. It implies `-refresh`.

    If the package tarball contains a `configure` script, it is run during the installation of the package. If it contains a `Makefile`, the command `make` is used by default. It is possible to override the default command with the environment variable `MAKE`. Some Octave packages might require GNU `make` which may be present under a different name such as `gmake`.

  ‘`update`’

    Check installed Octave packages against the latest version on the Octave Packages index and update any outdated items. Updated packages are installed either globally or locally depending on whether Octave is running with elevated privileges. This requires an internet connection and the cURL library.

    Options for the install command and the names of individual packages to be checked for updates may be specified as a list following the update command. If the option `-local` or `-global` is specified, `pkg update` limits the update check to the local or global installed packages, and installs updates in that same context. For example,

    Update all packages:

        pkg update

    Update all local packages:

        pkg update -local

    Update certain packages, ignore dependencies, max verbosity:

        pkg update -verbose -nodeps image signal geometry

    Updates for multiple packages are sorted alphabetically and not checked for dependencies affected by installation order. If a dependency order related `pkg update` failure occurs, use `pkg update -nodeps` to ignore dependencies, or `pkg install <package_name>` to update individual packages manually.

  ‘`uninstall`’

    Uninstall named packages. For example,

        pkg uninstall image

    removes the `image` package from the system. If another installed package depends on the `image` package an error is issued. The package removal can be forced by using the `-nodeps` option.

    Depending on whether Octave is being run with administrative privileges only global or local packages are removed by default. See `-global` or `-local` to override that default behavior.

  ‘`load`’

    Add named packages to the path. After loading a package it is possible to use the functions provided by the package. For example,

        pkg load image

    adds the `image` package to the path.

    Note: When loading a package, `pkg` automatically tries to load any unloaded dependencies as well, unless the `-nodeps` flag has been specified. For example,

        pkg load signal

    adds the `signal` package and also tries to load its dependency: the `control` package. Be aware that use of the `-nodeps` option can adversely affect package functionality.

  ‘`unload`’

    Remove named packages from the path. After unloading a package it is no longer possible to use the functions provided by the package. Trying to unload a package that other loaded packages still depend on causes an error; no packages are unloaded in this case. A package can be forcibly unloaded with the `-nodeps` flag, at the risk of breaking dependent packages that are still loaded.

  ‘`list`’

    Show the list of currently installed packages. For example,

        pkg list

    will produce a short report with the package name, version, and installation directory for each installed package. Supply a package name to limit reporting to a particular package. For example:

        pkg list image

    If a single return argument is requested then `pkg` returns a cell array where each element is a structure with information on a single package.

        installed_packages = pkg ("list")

    If two output arguments are requested `pkg` splits the list of installed packages into those which were installed by the current user (local packages), and those which were installed by the system administrator (global packages).

        [user_packages, system_packages] = pkg ("list")

    The option `-forge` lists all packages available on the Octave Packages index that can be installed with the `pkg` command. This requires an internet connection and the cURL library. This also updates the locally cached file of the Octave Packages index. Calling

        octave_packages = pkg ("list", "-forge")

    is identical to calling

        octave_packages = pkg ("search", "-refresh", "-all")

  ‘`describe`’

    Show a short description of installed packages. With the option `"-verbose"` also list functions provided by the package. For example,

        pkg describe -verbose

    describes all installed packages and the functions they provide.

    The result can be limited to a set of packages:

        ## describe control and signal packages
        pkg describe control signal

    If one output is requested a cell of structure containing the description and list of functions of each package is returned as output rather than printed on screen:

        desc = pkg ("describe", "secs1d", "image")

    If any of the requested packages is not installed, `pkg` returns an error, unless a second output is requested:

        [desc, flag] = pkg ("describe", "secs1d", "image")

    flag takes one of the values `"Not installed"`, `"Loaded"`, or `"Not loaded"` for each of the named packages.

  ‘`prefix`’

    Set the installation prefix directory. For example,

        pkg prefix ~/my_octave_packages

    sets the installation prefix to `~/my_octave_packages`.

    Packages are installed in this directory.

    Giving an output argument returns the current installation prefix. For example:

        pfx = pkg ("prefix")

    The location in which to install the architecture dependent files can be independently specified with an additional argument. For example:

        pkg prefix ~/my_octave_packages ~/my_arch_dep_pkgs

  ‘`local_list`’

    Set the file in which to look for information on locally installed packages. Locally installed packages are those that are typically available only to the current user. For example:

        pkg local_list ~/.octave_packages

    Get the current value of local_list with

        pkg local_list

  ‘`global_list`’

    Set the file in which to look for information on globally installed packages. Globally installed packages are those that are typically available to all users. For example:

        pkg global_list /usr/share/octave/site/api-v59/octave_packages

    Get the current value of global_list with

        pkg global_list

  ‘`build`’

    Build a binary form of a package or packages. The binary file produced is itself an Octave package that can be installed normally with `pkg`. For example:

        pkg build builddir image-1.0.0.tar.gz ...

    where `builddir` is a directory where the binary packages are built. The options `-verbose` and `-nodeps` are respected, while all other options are ignored.

  ‘`rebuild`’

    Rebuild the package database from the installed global and local packages. This can be used in cases where the package database has been corrupted.

  ‘`test`’

    Perform the built-in self tests contained in all functions provided by the named packages. For example:

        pkg test image

  See also: ver, news.