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, --available
18           List only packages that are available on the current system
19
20       -A, --all
21           Include all, even uninstalled or unavailable packages
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       --check
180           Don't write anything in the output, exit with return code 0 if the
181           list is not empty, 1 otherwise.
182
183       --no
184           Answer no to all opam yes/no questions without prompting. See also
185           --confirm-level. This is equivalent to setting $OPAMNO to "true".
186
187       --no-depexts
188           Disable external dependencies handling for the query. This can be
189           used to include packages that are marked as unavailable because of
190           an unavailable system dependency.
191
192       --silent
193           Removed in 2.1, use --check instead.
194
195       -y, --yes
196           Answer yes to all opam yes/no questions without prompting. See also
197           --confirm-level. This is equivalent to setting $OPAMYES to "true".
198

COMMON OPTIONS

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

ENVIRONMENT

336       Opam makes use of the environment variables listed here. Boolean
337       variables should be set to "0", "no", "false" or the empty string to
338       disable, "1", "yes" or "true" to enable.
339
340       OPAMALLPARENS surround all filters with parenthesis.
341
342       OPAMASSUMEDEPEXTS see option `--assume-depexts'.
343
344       OPAMAUTOREMOVE see remove option `--auto-remove'.
345
346       OPAMBESTEFFORT see option `--best-effort'.
347
348       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
349       the criteria when the `--best-effort' option is set, and is expected to
350       maximise the `opam-query' property in the solution.
351
352       OPAMBUILDDOC Removed in 2.1.
353
354       OPAMBUILDTEST Removed in 2.1.
355
356       OPAMCLI see option `--cli'.
357
358       OPAMCOLOR when set to always or never, sets a default value for the
359       `--color' option.
360
361       OPAMCONFIRMLEVEL see option `--confirm-level`. OPAMCONFIRMLEVEL has
362       priority over OPAMYES and OPAMNO.
363
364       OPAMCRITERIA specifies user preferences for dependency solving. The
365       default value depends on the solver version, use `config report' to
366       know the current setting. See also option --criteria.
367
368       OPAMCUDFFILE save the cudf graph to file-actions-explicit.dot.
369
370       OPAMCUDFTRIM controls the filtering of unrelated packages during CUDF
371       preprocessing.
372
373       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
374       for more options.
375
376       OPAMDEBUG see options `--debug' and `--debug-level'.
377
378       OPAMDEBUGSECTIONS if set, limits debug messages to the space-separated
379       list of sections. Sections can optionally have a specific debug level
380       (for example, CLIENT:2 or CLIENT CUDF:2), but otherwise use
381       `--debug-level'.
382
383       OPAMDIGDEPTH defines how aggressive the lookup for conflicts during
384       CUDF preprocessing is.
385
386       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
387
388       OPAMDROPWORKINGDIR overrides packages previously updated with
389       --working-dir on update. Without this variable set, opam would keep
390       them unchanged unless explicitly named on the command-line.
391
392       OPAMDRYRUN see option `--dry-run'.
393
394       OPAMEDITOR sets the editor to use for opam file editing, overrides
395       $EDITOR and $VISUAL.
396
397       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
398       fails. 0 to print all.
399
400       OPAMEXTERNALSOLVER see option `--solver'.
401
402       OPAMFAKE see option `--fake'.
403
404       OPAMFETCH specifies how to download files: either `wget', `curl' or a
405       custom command where variables %{url}%, %{out}%, %{retry}%,
406       %{compress}% and %{checksum}% will be replaced. Overrides the
407       'download-command' value from the main config file.
408
409       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup.
410
411       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on'.
412
413       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends'.
414
415       OPAMINPLACEBUILD see option `--inplace-build'.
416
417       OPAMJOBS sets the maximum number of parallel workers to run.
418
419       OPAMJSON log json output to the given file (use character `%' to index
420       the files).
421
422       OPAMKEEPBUILDDIR see install option `--keep-build-dir'.
423
424       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
425       some backups. This skips some finalisers and may also help to get more
426       reliable backtraces.
427
428       OPAMLOCKED combination of `--locked' and `--lock-suffix' options.
429
430       OPAMLOGS logdir sets log directory, default is a temporary directory in
431       /tmp
432
433       OPAMMAKECMD set the system make command to use.
434
435       OPAMMERGEOUT merge process outputs, stderr on stdout.
436
437       OPAMNO answer no to any question asked, see options `--no` and
438       `--confirm-level`. OPAMNO is ignored if either OPAMCONFIRMLEVEL or
439       OPAMYES is set.
440
441       OPAMNOAGGREGATE with `opam admin check', don't aggregate packages.
442
443       OPAMNOASPCUD Deprecated.
444
445       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
446       in an earlier format to the current one, on 'update' or 'init'.
447
448       OPAMNOCHECKSUMS enables option --no-checksums when available.
449
450       OPAMNODEPEXTS disables system dependencies handling, see option
451       `--no-depexts'.
452
453       OPAMNOENVNOTICE Internal.
454
455       OPAMNOSELFUPGRADE see option `--no-self-upgrade'
456
457       OPAMPINKINDAUTO sets whether version control systems should be detected
458       when pinning to a local path. Enabled by default since 1.3.0.
459
460       OPAMPRECISETRACKING fine grain tracking of directories.
461
462       OPAMPREPRO set this to false to disable CUDF preprocessing. Less
463       efficient, but might help debugging solver issue.
464
465       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
466       available (e.g. for `opam install').
467
468       OPAMRETRIES sets the number of tries before failing downloads.
469
470       OPAMREUSEBUILDDIR see option `--reuse-build-dir'.
471
472       OPAMROOT see option `--root'. This is automatically set by `opam env
473       --root=DIR --set-root'.
474
475       OPAMROOTISOK don't complain when running as root.
476
477       OPAMSAFE see option `--safe'.
478
479       OPAMSHOW see option `--show'.
480
481       OPAMSKIPUPDATE see option `--skip-updates'.
482
483       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
484       compatibility testing only.
485
486       OPAMSOLVERALLOWSUBOPTIMAL (default `true') allows some solvers to still
487       return a solution when they reach timeout; while the solution remains
488       assured to be consistent, there is no guarantee in this case that it
489       fits the expected optimisation criteria. If `true', opam willcontinue
490       with a warning, if `false' a timeout is an error. Currently only the
491       builtin-z3 backend handles this degraded case.
492
493       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
494       60.0, set to 0 for unlimited. Note that all solvers may not support
495       this option.
496
497       OPAMSTATS display stats at the end of command.
498
499       OPAMSTATUSLINE display a dynamic status line showing what's currently
500       going on on the terminal. (one of one of always, never or auto)
501
502       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.).
503
504       OPAMSWITCH see option `--switch'. Automatically set by `opam env
505       --switch=SWITCH --set-switch'.
506
507       OPAMUNLOCKBASE see install option `--unlock-base'.
508
509       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
510       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
511       are set. See also option --criteria.
512
513       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
514
515       OPAMUSEOPENSSL force openssl use for hash computing.
516
517       OPAMUTF8 use UTF8 characters in output (one of one of always, never or
518       auto). By default `auto', which is determined from the locale).
519
520       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
521       Implies OPAMUTF8. This is set by default on OSX only.
522
523       OPAMVALIDATIONHOOK if set, uses the `%{hook%}' command to validate an
524       opam repository update.
525
526       OPAMVERBOSE see option `--verbose'.
527
528       OPAMVERSIONLAGPOWER do not use.
529
530       OPAMWITHDOC see install option `--with-doc'.
531
532       OPAMWITHTEST see install option `--with-test.
533
534       OPAMWORKINGDIR see option `--working-dir'.
535
536       OPAMYES see options `--yes' and `--confirm-level`. OPAMYES has has
537       priority over OPAMNO and is ignored if OPAMCONFIRMLEVEL is set.
538
539       OPAMVAR_var overrides the contents of the variable var when
540       substituting `%{var}%` strings in `opam` files.
541
542       OPAMVAR_package_var overrides the contents of the variable package:var
543       when substituting `%{package:var}%` strings in `opam` files.
544

CLI VERSION

546       All scripts and programmatic invocations of opam should use `--cli' in
547       order to ensure that they work seamlessly with future versions of the
548       opam client. Additionally, blog posts or other documentation can
549       benefit, as it prevents information from becoming stale.
550
551       Although opam only supports roots (~/.opam/) for the current version,
552       it does provide backwards compatibility for its command-line interface.
553
554       Since CLI version support was only added in opam 2.1, use OPAMCLI to
555       select 2.0 support (as opam 2.0 will just ignore it), and `--cli=2.1'
556       for 2.1 (or later) versions, since an environment variable controlling
557       the parsing of syntax is brittle. To this end, opam displays a warning
558       if OPAMCLI specifies a valid version other than 2.0, and also if
559       `--cli=2.0' is specified.
560
561       The command-line version is selected by using the `--cli' option or the
562       OPAMCLI environment variable. `--cli' may be specified morethan once,
563       where the last instance takes precedence. OPAMCLI is only inspected if
564       `--cli' is not given.
565

EXIT STATUS

567       As an exception to the following, the `exec' command returns 127 if the
568       command was not found or couldn't be executed, and the command's exit
569       value otherwise.
570
571       0   Success, or true for boolean queries.
572
573       1   False. Returned when a boolean return value is expected, e.g. when
574           running with --check, or for queries like opam lint.
575
576       2   Bad command-line arguments, or command-line arguments pointing to
577           an invalid context (e.g. file not following the expected format).
578
579       5   Not found. You requested something (package, version, repository,
580           etc.) that couldn't be found.
581
582       10  Aborted. The operation required confirmation, which wasn't given.
583
584       15  Could not acquire the locks required for the operation.
585
586       20  There is no solution to the user request. This can be caused by
587           asking to install two incompatible packages, for example.
588
589       30  Error in package definition, or other metadata files. Using
590           --strict raises this error more often.
591
592       31  Package script error. Some package operations were unsuccessful.
593           This may be an error in the packages or an incompatibility with
594           your system. This can be a partial error.
595
596       40  Sync error. Could not fetch some remotes from the network. This can
597           be a partial error.
598
599       50  Configuration error. Opam or system configuration doesn't allow
600           operation, and needs fixing.
601
602       60  Solver failure. The solver failed to return a sound answer. It can
603           be due to a broken external solver, or an error in solver
604           configuration.
605
606       99  Internal error. Something went wrong, likely due to a bug in opam
607           itself.
608
609       130 User interrupt. SIGINT was received, generally due to the user
610           pressing Ctrl-C.
611

FURTHER DOCUMENTATION

613       See https://opam.ocaml.org/doc.
614

AUTHORS

616       Vincent Bernardoff <vb@luminar.eu.org>
617       Raja Boujbel <raja.boujbel@ocamlpro.com>
618       Roberto Di Cosmo <roberto@dicosmo.org>
619       Thomas Gazagnaire <thomas@gazagnaire.org>
620       Louis Gesbert <louis.gesbert@ocamlpro.com>
621       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
622       Anil Madhavapeddy <anil@recoil.org>
623       Guillem Rieu <guillem.rieu@ocamlpro.com>
624       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
625       Frederic Tuong <tuong@users.gforge.inria.fr>
626

BUGS

628       Check bug reports at https://github.com/ocaml/opam/issues.
629
630
631
632Opam 2.1.5                                                      OPAM-SEARCH(1)
Impressum