1OPAM-SEARCH(1)                    Opam Manual                   OPAM-SEARCH(1)
2
3
4

NAME

6       opam-search - An alias for list --search.
7

SYNOPSIS

9       opam search [OPTION]... [PATTERNS]...
10

DESCRIPTION

12       opam search is an alias for opam list --search.
13
14       See opam list --help for details.
15

PACKAGE SELECTION OPTIONS

17       -A, --all
18           Include all, even uninstalled or unavailable packages
19
20       -a, --available
21           List only packages that are available on the current system
22
23       --base
24           List only the immutable base of the current switch (i.e. compiler
25           packages)
26
27       --coinstallable-with=PACKAGES
28           Only list packages that are compatible with all of PACKAGES.
29
30       --conflicts-with=PACKAGES
31           List packages that have declared conflicts with at least one of the
32           given list. This includes conflicts defined from the packages in
33           the list, from the other package, or by a common conflict-class:
34           field.
35
36       --depends-on=PACKAGES
37           List only packages that depend on one of (comma-separated)
38           PACKAGES.
39
40       --depopts
41           Include optional dependencies in dependency requests.
42
43       --dev
44           Include development packages in dependencies.
45
46       --field-match=FIELD:PATTERN
47           Filter packages with a match for PATTERN on the given FIELD
48
49       --has-flag=FLAG
50           Only include packages which have the given flag set. Package flags
51           are one of: light-uninstall verbose plugin compiler conf
52
53       --has-tag=TAG
54           Only includes packages which have the given tag set
55
56       -i, --installed
57           List installed packages only. This is the default when no further
58           arguments are supplied
59
60       --installable
61           List only packages that can be installed on the current switch
62           (this calls the solver and may be more costly; a package depending
63           on an unavailable package may be available, but is never
64           installable)
65
66       --no-switch
67           List what is available from the repositories, without consideration
68           for the current (or any other) switch (installed or pinned
69           packages, etc.)
70
71       --nobuild
72           Exclude build dependencies (they are included by default).
73
74       --or
75           Instead of selecting packages that match all the criteria, select
76           packages that match any of them
77
78       --owns-file=FILE
79           Finds installed packages responsible for installing the given file
80
81       --pinned
82           List only the pinned packages
83
84       --post
85           Include dependencies tagged as post.
86
87       --recursive
88           With `--depends-on' and `--required-by', display all transitive
89           dependencies rather than just direct dependencies.
90
91       --repos=REPOS
92           Include only packages that took their origin from one of the given
93           repositories (unless no-switch is also specified, this excludes
94           pinned packages).
95
96       --required-by=PACKAGES
97           List only the dependencies of (comma-separated) PACKAGES.
98
99       --resolve=PACKAGES
100           Restrict to a solution to install (comma-separated) PACKAGES, i.e.
101           a consistent set of packages including those. This is subtly
102           different from `--required-by --recursive`, which is more
103           predictable and can't fail, but lists all dependencies
104           independently without ensuring consistency. Without `--installed`,
105           the answer is self-contained and independent of the current
106           installation. With `--installed', it's computed from the set of
107           currently installed packages. `--no-switch` further makes the
108           solution independent from the currently pinned packages,
109           architecture, and compiler version. The combination with
110           `--depopts' is not supported.
111
112       --roots, --installed-roots
113           List only packages that were explicitly installed, excluding the
114           ones installed as dependencies
115
116       -t, --with-test, --test
117           Include test-only dependencies.
118
119       --with-doc, --doc
120           Include doc-only dependencies.
121

OUTPUT FORMAT OPTIONS

123       --columns=COLUMNS
124           Select the columns to display among: name, version, package,
125           synopsis, synopsis-or-target, description, <field>:,
126           installed-version, pin, source-hash, opam-file,
127           all-installed-versions, available-versions, all-versions,
128           repository, installed-files, vc-ref, depexts. The default is name
129           when --short is present and name, installed-version,
130           synopsis-or-target otherwise.
131
132       -e, --external, --depexts
133           Instead of displaying the packages, display their external
134           dependencies that are associated with the current system. This
135           excludes other display options. Rather than using this directly,
136           you should probably head for the `depext' plugin, that will use
137           your system package management system to handle the installation of
138           the dependencies. Run `opam depext'.
139
140       --normalise
141           Print the values of opam fields normalised
142
143       -S, --sort
144           Sort the packages in dependency order (i.e. an order in which they
145           could be individually installed.)
146
147       -s, --short
148           Don't print a header, and sets the default columns to name only. If
149           you need package versions included, use --columns=package instead
150
151       --separator=STRING (absent= )
152           Set the column-separator string
153
154       -V, --all-versions
155           Normally, when multiple versions of a package match, only one is
156           shown in the output (the installed one, the pinned-to one, or,
157           failing that, the highest one available or the highest one). This
158           flag disables this behaviour and shows all matching versions. This
159           also changes the default display format to include package versions
160           instead of just package names (including when --short is set). This
161           is automatically turned on when a single non-pattern package name
162           is provided on the command-line.
163
164       --vars=[VAR=STR,...]
165           Define the given variable bindings. Typically useful with
166           --external to override the values for arch, os, os-distribution,
167           os-version, os-family.
168
169       --wrap
170           Wrap long lines, the default being to truncate when displaying on a
171           terminal, or to keep as is otherwise
172

ARGUMENTS

174       PATTERNS
175           Package patterns with globs. Unless --search is specified, they
176           match againsta NAME or NAME.VERSION
177

OPTIONS

179       --help[=FMT] (default=auto)
180           Show this help in format FMT. The value FMT must be one of `auto',
181           `pager', `groff' or `plain'. With `auto', the format is `pager` or
182           `plain' whenever the TERM env var is `dumb' or undefined.
183
184       --silent
185           Don't write anything in the output, exit with return code 0 if the
186           list is not empty, 1 otherwise.
187
188       --version
189           Show version information.
190

COMMON OPTIONS

192       These options are common to all commands.
193
194       --best-effort
195           Don't fail if all requested packages can't be installed: try to
196           install as many as possible. Note that not all external solvers may
197           support this option (recent versions of aspcud or mccs should).
198           This is equivalent to setting $OPAMBESTEFFORT environment variable.
199
200       --color=WHEN
201           Colorize the output. WHEN must be one of `always', `never' or
202           `auto'.
203
204       --criteria=CRITERIA
205           Specify user preferences for dependency solving for this run.
206           Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
207           on the supported language, and the external solvers available, see
208           http://opam.ocaml.org/doc/External_solvers.html. A general guide to
209           using solver preferences can be found at
210           http://www.dicosmo.org/Articles/usercriteria.pdf.
211
212       --cudf=FILENAME
213           Debug option: Save the CUDF requests sent to the solver to
214           FILENAME-<n>.cudf.
215
216       --debug
217           Print debug message to stderr. This is equivalent to setting
218           $OPAMDEBUG to "true".
219
220       --debug-level=LEVEL
221           Like --debug, but allows specifying the debug level (--debug sets
222           it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
223
224       --git-version
225           Print the git version of opam, if set (i.e. you are using a
226           development version), and exit.
227
228       --ignore-pin-depends
229           Ignore extra pins required by packages that get pinned, either
230           manually through opam pin or through opam install DIR. This is
231           equivalent to setting IGNOREPINDEPENDS=true.
232
233       --json=FILENAME
234           Save the results of the opam run in a computer-readable file. If
235           the filename contains the character `%', it will be replaced by an
236           index that doesn't overwrite an existing file. Similar to setting
237           the $OPAMJSON variable.
238
239       --no-aspcud
240           Deprecated.
241
242       --no-auto-upgrade
243           When configuring or updating a repository that is written for an
244           earlier opam version (1.2), opam internally converts it to the
245           current format. This disables this behaviour. Note that
246           repositories should define their format version in a 'repo' file at
247           their root, or they will be assumed to be in the older format. It
248           is, in any case, preferable to upgrade the repositories manually
249           using opam admin upgrade [--mirror URL] when possible.
250
251       --no-self-upgrade
252           Opam will replace itself with a newer binary found at OPAMROOT/opam
253           if present. This disables this behaviour.
254
255       -q, --quiet
256           Disables --verbose.
257
258       --root=ROOT
259           Use ROOT as the current root path. This is equivalent to setting
260           $OPAMROOT to ROOT.
261
262       --safe, --readonly
263           Make sure nothing will be automatically updated or rewritten.
264           Useful for calling from completion scripts, for example. Will fail
265           whenever such an operation is needed ; also avoids waiting for
266           locks, skips interactive questions and overrides the $OPAMDEBUG
267           variable. This is equivalent to set environment variable $OPAMSAFE.
268
269       --solver=CMD
270           Specify the CUDF solver to use for resolving package installation
271           problems. This is either a predefined solver (this version of opam
272           supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
273           aspcud-old, packup), or a custom command that should contain the
274           variables %{input}%, %{output}%, %{criteria}%, and optionally
275           %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
276
277       --strict
278           Fail whenever an error is found in a package definition or a
279           configuration file. The default is to continue silently if
280           possible.
281
282       --switch=SWITCH
283           Use SWITCH as the current compiler switch. This is equivalent to
284           setting $OPAMSWITCH to SWITCH.
285
286       --use-internal-solver
287           Disable any external solver, and use the built-in one (this
288           requires that opam has been compiled with a built-in solver). This
289           is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
290
291       -v, --verbose
292           Be more verbose. One -v shows all package commands, repeat to also
293           display commands called internally (e.g. tar, curl, patch etc.)
294           Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
295
296       -w, --working-dir
297           Whenever updating packages that are bound to a local,
298           version-controlled directory, update to the current working state
299           of their source instead of the last committed state, or the ref
300           they are pointing to. This only affects packages explicitly listed
301           on the command-line.It can also be set with $OPAMWORKINGDIR.
302
303       -y, --yes
304           Answer yes to all yes/no questions without prompting. This is
305           equivalent to setting $OPAMYES to "true".
306

ENVIRONMENT VARIABLES

308       Opam makes use of the environment variables listed here. Boolean
309       variables should be set to "0", "no", "false" or the empty string to
310       disable, "1", "yes" or "true" to enable.
311
312       OPAMALLPARENS surround all filters with parenthesis
313
314       OPAMAUTOREMOVE see remove option `--auto-remove`
315
316       OPAMBESTEFFORT see option `--best-effort`
317
318       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
319       the criteria when the `--best-effort` option is set, and is expected to
320       maximise the `opam-query` property in the solution
321
322       OPAMCOLOR, when set to always or never, sets a default value for the
323       --color option.
324
325       OPAMCRITERIA specifies user preferences for dependency solving. The
326       default value depends on the solver version, use `config report` to
327       know the current setting. See also option --criteria
328
329       OPAMCUDFFILE file save the cudf graph to file-actions-explicit.dot
330
331       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
332       for more options.
333
334       OPAMDEBUG see options `--debug' and `--debug-level'.
335
336       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
337
338       OPAMDRYRUN see option `--dry-run`
339
340       OPAMEDITOR sets the editor to use for opam file editing, overrides
341       $EDITOR and $VISUAL
342
343       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
344       fails. 0 to print all.
345
346       OPAMEXTERNALSOLVER see option `--solver'.
347
348       OPAMFAKE see option `--fake`
349
350       OPAMFETCH specifies how to download files: either `wget', `curl' or a
351       custom command where variables %{url}%, %{out}%, %{retry}%,
352       %{compress}% and %{checksum}% will be replaced. Overrides the
353       'download-command' value from the main config file.
354
355       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup
356
357       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on`
358
359       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends`
360
361       OPAMJOBS sets the maximum number of parallel workers to run.
362
363       OPAMJSON log json output to the given file (use character `%' to index
364       the files)
365
366       OPAMLOCKED see install option `--locked`
367
368       OPAMLOGS logdir sets log directory, default is a temporary directory in
369       /tmp
370
371       OPAMMAKECMD set the system make command to use
372
373       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
374       in an earlier format to the current one, on 'update' or 'init'.
375
376       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
377       some backups. This skips some finalisers and may also help to get more
378       reliable backtraces
379
380       OPAMLOCKRETRIES sets the number of tries after which opam gives up
381       acquiring its lock and fails. <= 0 means infinite wait.
382
383       OPAMMERGEOUT merge process outputs, stderr on stdout
384
385       OPAMNO answer no to any question asked.
386
387       OPAMNOASPCUD Deprecated.
388
389       OPAMNOCHECKSUMS enables option --no-checksums when available.
390
391       OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
392
393       OPAMPINKINDAUTO sets whether version control systems should be detected
394       when pinning to a local path. Enabled by default since 1.3.0.
395
396       OPAMPRECISETRACKING fine grain tracking of directories
397
398       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
399       available (e.g. for `opam install`).
400
401       OPAMRETRES sets the number of tries before failing downloads.
402
403       OPAMROOT see option `--root'. This is automatically set by `opam env
404       --root=DIR --set-root'.
405
406       OPAMROOTISOK don't complain when running as root.
407
408       OPAMSAFE see option `--safe'
409
410       OPAMSHOW see option `--show`
411
412       OPAMSKIPUPDATE see option `--skip-updates`
413
414       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
415       compatibility testing only.
416
417       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
418       60.0, set to 0 for unlimited. Note that all solvers may not support
419       this option.
420
421       OPAMSTATUSLINE display a dynamic status line showing what's currently
422       going on on the terminal. (one of one of `always', `never' or `auto')
423
424       OPAMSTATS display stats at the end of command
425
426       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.)
427
428       OPAMSWITCH see option `--switch'. Automatically set by `opam env
429       --switch=SWITCH --set-switch'.
430
431       OPAMUNLOCKBASE see install option `--unlock-base`
432
433       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
434       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
435       are set. See also option --criteria
436
437       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
438
439       OPAMUSEOPENSSL force openssl use for hash computing
440
441       OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
442       or `auto'). By default `auto', which is determined from the locale).
443
444       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
445       Implies OPAMUTF8. This is set by default on OSX only.
446
447       OPAMVALIDATIONHOOK hook if set, uses the `%{hook%}` command to validate
448       an opam repository update
449
450       OPAMVAR_var overrides the contents of the variable var when
451       substituting `%{var}%` strings in `opam` files.
452
453       OPAMVAR_package_var overrides the contents of the variable package:var
454       when substituting `%{package:var}%` strings in `opam` files.
455
456       OPAMVERBOSE see option `--verbose'.
457
458       OPAMWORKINGDIR see option `--working-dir`
459
460       OPAMYES see option `--yes'.
461

EXIT STATUS

463       As an exception to the following, the `exec' command returns 127 if the
464       command was not found or couldn't be executed, and the command's exit
465       value otherwise.
466
467       0   Success, or true for boolean queries.
468
469       1   False. Returned when a boolean return value is expected, e.g. when
470           running with --check, or for queries like opam lint.
471
472       2   Bad command-line arguments, or command-line arguments pointing to
473           an invalid context (e.g. file not following the expected format).
474
475       5   Not found. You requested something (package, version, repository,
476           etc.) that couldn't be found.
477
478       10  Aborted. The operation required confirmation, which wasn't given.
479
480       15  Could not acquire the locks required for the operation.
481
482       20  There is no solution to the user request. This can be caused by
483           asking to install two incompatible packages, for example.
484
485       30  Error in package definition, or other metadata files. Using
486           --strict raises this error more often.
487
488       31  Package script error. Some package operations were unsuccessful.
489           This may be an error in the packages or an incompatibility with
490           your system. This can be a partial error.
491
492       40  Sync error. Could not fetch some remotes from the network. This can
493           be a partial error.
494
495       50  Configuration error. Opam or system configuration doesn't allow
496           operation, and needs fixing.
497
498       60  Solver failure. The solver failed to return a sound answer. It can
499           be due to a broken external solver, or an error in solver
500           configuration.
501
502       99  Internal error. Something went wrong, likely due to a bug in opam
503           itself.
504
505       130 User interrupt. SIGINT was received, generally due to the user
506           pressing Ctrl-C.
507

FURTHER DOCUMENTATION

509       See https://opam.ocaml.org/doc.
510

AUTHORS

512       Vincent Bernardoff <vb@luminar.eu.org>
513       Raja Boujbel <raja.boujbel@ocamlpro.com>
514       Roberto Di Cosmo <roberto@dicosmo.org>
515       Thomas Gazagnaire <thomas@gazagnaire.org>
516       Louis Gesbert <louis.gesbert@ocamlpro.com>
517       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
518       Anil Madhavapeddy <anil@recoil.org>
519       Guillem Rieu <guillem.rieu@ocamlpro.com>
520       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
521       Frederic Tuong <tuong@users.gforge.inria.fr>
522

BUGS

524       Check bug reports at https://github.com/ocaml/opam/issues.
525
526
527
528Opam 2.0.6                                                      OPAM-SEARCH(1)
Impressum