1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Installing and Removing Packages (GNU Octave (version 7.3.0))</title>
<meta name="description" content="Installing and Removing Packages (GNU Octave (version 7.3.0))">
<meta name="keywords" content="Installing and Removing Packages (GNU Octave (version 7.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Packages.html" rel="up" title="Packages">
<link href="Using-Packages.html" rel="next" title="Using Packages">
<style type="text/css">
<!--
a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
span:hover a.copiable-anchor {visibility: visible}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="section" id="Installing-and-Removing-Packages">
<div class="header">
<p>
Next: <a href="Using-Packages.html" accesskey="n" rel="next">Using Packages</a>, Up: <a href="Packages.html" accesskey="u" rel="up">Packages</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<span id="Installing-and-Removing-Packages-1"></span><h3 class="section">37.1 Installing and Removing Packages</h3>
<p>Assuming a package is available in the file <samp>image-1.0.0.tar.gz</samp>
it can be installed from the Octave prompt with the command
</p>
<div class="example">
<pre class="example">pkg install image-1.0.0.tar.gz
</pre></div>
<p>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 <code>pkg install</code>
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.
</p>
<p>To see which packages are installed type
</p>
<div class="example">
<pre class="example">pkg list
-| Package Name | Version | Installation directory
-| --------------+---------+-----------------------
-| image *| 1.0.0 | /home/jwe/octave/image-1.0.0
</pre></div>
<p>In this case, version 1.0.0 of the <code>image</code> package is installed.
The <code>'*'</code> character next to the package name shows that the image
package is loaded and ready for use.
</p>
<p>It is possible to remove a package from the system using the
<code>pkg uninstall</code> command like this
</p>
<div class="example">
<pre class="example">pkg uninstall image
</pre></div>
<p>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
<code>pkg list</code> should be used when removing a package. It is possible
to remove several packages at once by writing several package names
after the <code>pkg uninstall</code> command.
</p>
<p>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 <samp>-nodeps</samp> flag to the <code>pkg install</code>
command
</p>
<div class="example">
<pre class="example">pkg install -nodeps my_package_with_dependencies.tar.gz
</pre></div>
<p>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.
</p>
<span id="XREFpkg"></span><dl class="def">
<dt id="index-pkg-1"><span class="category">: </span><span><em></em> <strong>pkg</strong> <em><var>command</var> <var>pkg_name</var></em><a href='#index-pkg-1' class='copiable-anchor'> ¶</a></span></dt>
<dt id="index-pkg-2"><span class="category">: </span><span><em></em> <strong>pkg</strong> <em><var>command</var> <var>option</var> <var>pkg_name</var></em><a href='#index-pkg-2' class='copiable-anchor'> ¶</a></span></dt>
<dt id="index-pkg-3"><span class="category">: </span><span><em>[<var>out1</var>, …] =</em> <strong>pkg</strong> <em>(<var>command</var>, … )</em><a href='#index-pkg-3' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>Manage or query packages (groups of add-on functions) for Octave.
</p>
<p>Packages can be installed globally (i.e., for all users of the system) or
locally (i.e., for the current user only).
</p>
<p>Global packages are installed by default in a system-wide location. This is
usually a subdirectory of the folder where Octave itself is installed.
Therefore, Octave needs write access to this folder to install global
packages, which is usually only available when Octave is run with
administrative privileges, such as when run as root (or superuser) on
Unix-like systems, or run with elevated privileges ("Run as administrator")
on Windows.
</p>
<p>In contrast, local packages are installed by default in the user’s home
directory (or user profile on Windows) and are only available to that
specific user. Usually, they can be installed without administrative
privileges.
</p>
<p>When Octave is running with administrative privileges, <code>pkg</code> will
install packages to the global package location by default. Otherwise,
packages will be installed to the local location by default. The user can
override this default installation location with optional arguments
(<samp>-local</samp> or <samp>-global</samp>) as described below. The currently
used default package installation location can be queried with
<code>pkg prefix</code>.
</p>
<p>For global and local packages, there are separate databases holding the
information about the installed packages. If some package is installed
globally as well as locally, the local installation takes precedence over
("shadows") the global one. Which (global or local) package installation is
used can also be manipulated by using prefixes and/or using the
‘<samp>local_list</samp>’ input argument. Using these mechanisms, several different
releases of the same package can be installed side by side as well (but
cannot be loaded simultaneously).
</p>
<p>Packages might depend on external software and/or other packages. To be
able to install such packages, these dependencies should be installed
beforehand. A package that depends on other package(s) can still be
installed using the <samp>-nodeps</samp> flag. The effects of unsatisfied
dependencies on external software—like libraries—depends on the
individual package.
</p>
<p>Packages must be loaded before they can be used. When loading a package,
Octave performs the following tasks:
</p><ol>
<li> If the package depends on other packages (and <code>pkg load</code> is called
without the <samp>-nodeps</samp> option), the package is not loaded
immediately. Instead, those dependencies are loaded first (recursively if
needed).
</li><li> When all dependencies are satisfied, the package’s subdirectories are
added to the search path.
</li></ol>
<p>This load order leads to functions that are provided by dependencies being
potentially shadowed by functions of the same name that are provided by
top-level packages.
</p>
<p>Each time, a package is added to the search path, initialization script(s)
for the package are automatically executed if they are provided by the
package.
</p>
<p>Depending on the value of <var>command</var> and on the number of requested
return arguments, <code>pkg</code> can be used to perform several tasks.
Possible values for <var>command</var> are:
</p>
<dl compact="compact">
<dt><span>‘<samp>install</samp>’</span></dt>
<dd><p>Install named packages. For example,
</p>
<div class="example">
<pre class="example">pkg install image-1.0.0.tar.gz
</pre></div>
<p>installs the package found in the file <samp>image-1.0.0.tar.gz</samp>. The
file containing the package can be a URL, e.g.,
</p>
<div class="example">
<pre class="example">pkg install 'http://somewebsite.org/image-1.0.0.tar.gz'
</pre></div>
<p>installs the package found in the given URL. This
requires an internet connection and the cURL library.
</p>
<p><em>Security risk</em>: no verification of the package is performed
before the installation. It has the same security issues as manually
downloading the package from the given URL and installing it.
</p>
<p><em>No support</em>: the GNU Octave community is not responsible for
packages installed from foreign sites. For support or for
reporting bugs you need to contact the maintainers of the installed
package directly (see the <samp>DESCRIPTION</samp> file of the package)
</p>
<p>The <var>option</var> variable can contain options that affect the manner
in which a package is installed. These options can be one or more of
</p>
<dl compact="compact">
<dt><span><code>-nodeps</code></span></dt>
<dd><p>The package manager will 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. <strong>Use this option with care.</strong>
</p>
</dd>
<dt><span><code>-local</code></span></dt>
<dd><p>A local installation (package available only to current user) is forced,
even if Octave is being run with administrative privileges.
</p>
</dd>
<dt><span><code>-global</code></span></dt>
<dd><p>A global installation (package available to all users) is forced, even if
Octave is not being run with administrative privileges. The user must have
write access to the global package store.
</p>
</dd>
<dt><span><code>-forge</code></span></dt>
<dd><p>Install a package directly from the Octave Forge repository. This
requires an internet connection and the cURL library.
</p>
<p><em>Security risk</em>: no verification of the package is performed
before the installation. There are no signatures for packages, or
checksums to confirm the correct file was downloaded. It has the
same security issues as manually downloading the package from the
Octave Forge repository and installing it.
</p>
</dd>
<dt><span><code>-verbose</code></span></dt>
<dd><p>The package manager will print the output of all commands as
they are performed.
</p></dd>
</dl>
</dd>
<dt><span>‘<samp>update</samp>’</span></dt>
<dd><p>Check installed Octave Forge packages against repository 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.
</p>
<p>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 <samp>-local</samp> or <samp>-global</samp> option is specified,
<code>pkg update</code> limits the update check to the local or global installed
packages, and installs updates in that same context. For example,
</p>
<p>Update all packages:
</p><div class="example">
<pre class="example">pkg update
</pre></div>
<p>Update all local packages:
</p><div class="example">
<pre class="example">pkg update -local
</pre></div>
<p>Update certain packages, ignore dependencies, max verbosity:
</p><div class="example">
<pre class="example">pkg update -verbose -nodeps image signal geometry
</pre></div>
<p>Updates for multiple packages are sorted alphabetically and not checked
for dependencies affected by installation order. If dependency order
related <code>pkg update</code> failure occurs, use <code>pkg update -nodeps</code> to
ignore dependencies, or <code>pkg install -forge <package_name></code> to update
individual packages manually.
</p>
</dd>
<dt><span>‘<samp>uninstall</samp>’</span></dt>
<dd><p>Uninstall named packages. For example,
</p>
<div class="example">
<pre class="example">pkg uninstall image
</pre></div>
<p>removes the <code>image</code> package from the system. If another installed
package depends on the <code>image</code> package an error will be issued.
The package can be uninstalled anyway by using the <samp>-nodeps</samp> option.
</p>
</dd>
<dt><span>‘<samp>load</samp>’</span></dt>
<dd><p>Add named packages to the path. After loading a package it is
possible to use the functions provided by the package. For example,
</p>
<div class="example">
<pre class="example">pkg load image
</pre></div>
<p>adds the <code>image</code> package to the path.
</p>
<p>Note: When loading a package, <code>pkg</code> will automatically try to load
any unloaded dependencies as well, unless the <samp>-nodeps</samp> flag has
been specified. For example,
</p>
<div class="example">
<pre class="example">pkg load signal
</pre></div>
<p>adds the <code>signal</code> package and also tries to load its dependency: the
<code>control</code> package. Be aware that the functionality of package(s)
loaded will probably be impacted by use of the <samp>-nodeps</samp> flag. Even
if necessary dependencies are loaded later, the functionality of top-level
packages can still be affected because the optimal loading order may not
have been followed.
</p>
</dd>
<dt><span>‘<samp>unload</samp>’</span></dt>
<dd><p>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 will result
in an error; no packages will be unloaded in this case. A package can
be forcibly removed with the <samp>-nodeps</samp> flag, but be aware that the
functionality of dependent packages will likely be affected. As when
loading packages, reloading dependencies after having unloaded them with the
<samp>-nodeps</samp> flag may not restore all functionality of the dependent
packages as the required loading order may be incorrect.
</p>
</dd>
<dt><span>‘<samp>list</samp>’</span></dt>
<dd><p>Show the list of currently installed packages. For example,
</p>
<div class="example">
<pre class="example">pkg list
</pre></div>
<p>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:
</p>
<div class="example">
<pre class="example">pkg list image
</pre></div>
<p>If a single return argument is requested then <code>pkg</code> returns a cell
array where each element is a structure with information on a single
package.
</p>
<div class="example">
<pre class="example">installed_packages = pkg ("list")
</pre></div>
<p>If two output arguments are requested <code>pkg</code> splits the list of
installed packages into those which were installed by the current user,
and those which were installed by the system administrator.
</p>
<div class="example">
<pre class="example">[user_packages, system_packages] = pkg ("list")
</pre></div>
<p>The <code>"-forge"</code> option lists packages available at the Octave Forge
repository. This requires an internet connection and the cURL library.
For example:
</p>
<div class="example">
<pre class="example">oct_forge_pkgs = pkg ("list", "-forge")
</pre></div>
</dd>
<dt><span>‘<samp>describe</samp>’</span></dt>
<dd><p>Show a short description of installed packages. With the option
<code>"-verbose"</code> also list functions provided by the package. For
example,
</p>
<div class="example">
<pre class="example">pkg describe -verbose
</pre></div>
<p>will describe all installed packages and the functions they provide.
Display can be limited to a set of packages:
</p>
<div class="example">
<pre class="example">## describe control and signal packages
pkg describe control signal
</pre></div>
<p>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:
</p>
<div class="example">
<pre class="example">desc = pkg ("describe", "secs1d", "image")
</pre></div>
<p>If any of the requested packages is not installed, <code>pkg</code> returns an
error, unless a second output is requested:
</p>
<div class="example">
<pre class="example">[desc, flag] = pkg ("describe", "secs1d", "image")
</pre></div>
<p><var>flag</var> will take one of the values <code>"Not installed"</code>,
<code>"Loaded"</code>, or
<code>"Not loaded"</code> for each of the named packages.
</p>
</dd>
<dt><span>‘<samp>prefix</samp>’</span></dt>
<dd><p>Set the installation prefix directory. For example,
</p>
<div class="example">
<pre class="example">pkg prefix ~/my_octave_packages
</pre></div>
<p>sets the installation prefix to <samp>~/my_octave_packages</samp>.
Packages will be installed in this directory.
</p>
<p>It is possible to get the current installation prefix by requesting an
output argument. For example:
</p>
<div class="example">
<pre class="example">pfx = pkg ("prefix")
</pre></div>
<p>The location in which to install the architecture dependent files can be
independently specified with an addition argument. For example:
</p>
<div class="example">
<pre class="example">pkg prefix ~/my_octave_packages ~/my_arch_dep_pkgs
</pre></div>
</dd>
<dt><span>‘<samp>local_list</samp>’</span></dt>
<dd><p>Set the file in which to look for information on locally
installed packages. Locally installed packages are those that are
available only to the current user. For example:
</p>
<div class="example">
<pre class="example">pkg local_list ~/.octave_packages
</pre></div>
<p>It is possible to get the current value of local_list with the following
</p>
<div class="example">
<pre class="example">pkg local_list
</pre></div>
</dd>
<dt><span>‘<samp>global_list</samp>’</span></dt>
<dd><p>Set the file in which to look for information on globally
installed packages. Globally installed packages are those that are
available to all users. For example:
</p>
<div class="example">
<pre class="example">pkg global_list /usr/share/octave/octave_packages
</pre></div>
<p>It is possible to get the current value of global_list with the following
</p>
<div class="example">
<pre class="example">pkg global_list
</pre></div>
</dd>
<dt><span>‘<samp>build</samp>’</span></dt>
<dd><p>Build a binary form of a package or packages. The binary file produced
will itself be an Octave package that can be installed normally with
<code>pkg</code>. The form of the command to build a binary package is
</p>
<div class="example">
<pre class="example">pkg build builddir image-1.0.0.tar.gz …
</pre></div>
<p>where <code>builddir</code> is the name of a directory where the temporary
installation will be produced and the binary packages will be found.
The options <samp>-verbose</samp> and <samp>-nodeps</samp> are respected, while
all other options are ignored.
</p>
</dd>
<dt><span>‘<samp>rebuild</samp>’</span></dt>
<dd><p>Rebuild the package database from the installed directories. This can
be used in cases where the package database has been corrupted.
</p>
</dd>
<dt><span>‘<samp>test</samp>’</span></dt>
<dd><p>Perform the built-in self tests contained in all functions provided by
the named packages. For example:
</p>
<div class="example">
<pre class="example">pkg test image
</pre></div>
</dd>
</dl>
<p><strong>See also:</strong> <a href="System-Information.html#XREFver">ver</a>, <a href="Getting-Help.html#XREFnews">news</a>.
</p></dd></dl>
</div>
<hr>
<div class="header">
<p>
Next: <a href="Using-Packages.html">Using Packages</a>, Up: <a href="Packages.html">Packages</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
