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.
command ¶command pkg_name ¶command pkg_name1 pkg_name2 … ¶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 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 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:
pkgname is a local file, Octave installs it.
pkgname resembles a URL, Octave downloads and
installs it.
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:
-nodepsDisable 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.
-localA local installation (package available only to current user) is forced, even if Octave is being run with administrative privileges.
-globalForce 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.
-verbosePrint the output of all commands as they are performed.
-refreshForce 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.
-forgeThe 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.
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 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.
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.
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.
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")
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.
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
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
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 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 the package database from the installed global and local packages. This can be used in cases where the package database has been corrupted.
Perform the built-in self tests contained in all functions provided by the named packages. For example:
pkg test image