1OPAM-SEARCH(1) Opam Manual OPAM-SEARCH(1)
2
3
4
6 opam-search - An alias for list --search.
7
9 opam search [OPTION]... [PATTERNS]...
10
12 opam search is an alias for opam list --search.
13
14 See opam list --help for details.
15
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
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
174 PATTERNS
175 Package patterns with globs. Unless --search is specified, they
176 match againsta NAME or NAME.VERSION
177
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
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
218 `auto'.
219
220 --confirm-level=LEVEL
221 Confirmation level, LEVEL must be one of `ask', `no', `yes' or
222 `unsafe-yes'. Can be specified more than once. If --yes or --no are
223 also given, the value of the last --confirm-level is taken into
224 account. This is equivalent to setting $OPAMCONFIRMLEVEL`.
225
226 --criteria=CRITERIA
227 Specify user preferences for dependency solving for this run.
228 Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
229 on the supported language, and the external solvers available, see
230 http://opam.ocaml.org/doc/External_solvers.html. A general guide to
231 using solver preferences can be found at
232 http://www.dicosmo.org/Articles/usercriteria.pdf.
233
234 --cudf=FILENAME
235 Debug option: Save the CUDF requests sent to the solver to
236 FILENAME-<n>.cudf.
237
238 --debug
239 Print debug message to stderr. This is equivalent to setting
240 $OPAMDEBUG to "true".
241
242 --debug-level=LEVEL
243 Like --debug, but allows specifying the debug level (--debug sets
244 it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
245
246 --git-version
247 Print the git version of opam, if set (i.e. you are using a
248 development version), and exit.
249
250 --help[=FMT] (default=auto)
251 Show this help in format FMT. The value FMT must be one of `auto',
252 `pager', `groff' or `plain'. With `auto', the format is `pager` or
253 `plain' whenever the TERM env var is `dumb' or undefined.
254
255 --ignore-pin-depends
256 Ignore extra pins required by packages that get pinned, either
257 manually through opam pin or through opam install DIR. This is
258 equivalent to setting IGNOREPINDEPENDS=true.
259
260 --json=FILENAME
261 Save the results of the opam run in a computer-readable file. If
262 the filename contains the character `%', it will be replaced by an
263 index that doesn't overwrite an existing file. Similar to setting
264 the $OPAMJSON variable.
265
266 --no-aspcud
267 Removed in 2.1.
268
269 --no-auto-upgrade
270 When configuring or updating a repository that is written for an
271 earlier opam version (1.2), opam internally converts it to the
272 current format. This disables this behaviour. Note that
273 repositories should define their format version in a 'repo' file at
274 their root, or they will be assumed to be in the older format. It
275 is, in any case, preferable to upgrade the repositories manually
276 using opam admin upgrade [--mirror URL] when possible.
277
278 --no-self-upgrade
279 Opam will replace itself with a newer binary found at OPAMROOT/opam
280 if present. This disables this behaviour.
281
282 -q, --quiet
283 Disables --verbose.
284
285 --root=ROOT
286 Use ROOT as the current root path. This is equivalent to setting
287 $OPAMROOT to ROOT.
288
289 --safe, --readonly
290 Make sure nothing will be automatically updated or rewritten.
291 Useful for calling from completion scripts, for example. Will fail
292 whenever such an operation is needed ; also avoids waiting for
293 locks, skips interactive questions and overrides the $OPAMDEBUG
294 variable. This is equivalent to set environment variable $OPAMSAFE.
295
296 --solver=CMD
297 Specify the CUDF solver to use for resolving package installation
298 problems. This is either a predefined solver (this version of opam
299 supports builtin-mccs+lp(), builtin-mccs+glpk,
300 builtin-dummy-z3-solver, builtin-dummy-0install-solver, aspcud,
301 mccs, aspcud-old, packup), or a custom command that should contain
302 the variables %{input}%, %{output}%, %{criteria}%, and optionally
303 %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
304
305 --strict
306 Fail whenever an error is found in a package definition or a
307 configuration file. The default is to continue silently if
308 possible.
309
310 --switch=SWITCH
311 Use SWITCH as the current compiler switch. This is equivalent to
312 setting $OPAMSWITCH to SWITCH.
313
314 --use-internal-solver
315 Disable any external solver, and use the built-in one (this
316 requires that opam has been compiled with a built-in solver). This
317 is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
318
319 -v, --verbose
320 Be more verbose. One -v shows all package commands, repeat to also
321 display commands called internally (e.g. tar, curl, patch etc.)
322 Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
323
324 --version
325 Show version information.
326
327 -w, --working-dir
328 Whenever updating packages that are bound to a local,
329 version-controlled directory, update to the current working state
330 of their source instead of the last committed state, or the ref
331 they are pointing to. As source directory is copied as it is, if it
332 isn't clean it may result on a opam build failure.This only affects
333 packages explicitly listed on the command-line.It can also be set
334 with $OPAMWORKINGDIR.
335
337 Opam makes use of the environment variables listed here. Boolean
338 variables should be set to "0", "no", "false" or the empty string to
339 disable, "1", "yes" or "true" to enable.
340
341 OPAMALLPARENS surround all filters with parenthesis.
342
343 OPAMASSUMEDEPEXTS see option `--assume-depexts'.
344
345 OPAMAUTOREMOVE see remove option `--auto-remove'.
346
347 OPAMBESTEFFORT see option `--best-effort'.
348
349 OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
350 the criteria when the `--best-effort' option is set, and is expected to
351 maximise the `opam-query' property in the solution.
352
353 OPAMBUILDDOC Removed in 2.1.
354
355 OPAMBUILDTEST Removed in 2.1.
356
357 OPAMCLI see option `--cli'.
358
359 OPAMCOLOR when set to always or never, sets a default value for the
360 `--color' option.
361
362 OPAMCONFIRMLEVEL see option `--confirm-level`. OPAMCONFIRMLEVEL has
363 priority over OPAMYES and OPAMNO.
364
365 OPAMCRITERIA specifies user preferences for dependency solving. The
366 default value depends on the solver version, use `config report' to
367 know the current setting. See also option --criteria.
368
369 OPAMCUDFFILE save the cudf graph to file-actions-explicit.dot.
370
371 OPAMCUDFTRIM controls the filtering of unrelated packages during CUDF
372 preprocessing.
373
374 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
375 for more options.
376
377 OPAMDEBUG see options `--debug' and `--debug-level'.
378
379 OPAMDEBUGSECTIONS if set, limits debug messages to the space-separated
380 list of sections. Sections can optionally have a specific debug level
381 (for example, CLIENT:2 or CLIENT CUDF:2), but otherwise use
382 `--debug-level'.
383
384 OPAMDIGDEPTH defines how aggressive the lookup for conflicts during
385 CUDF preprocessing is.
386
387 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
388
389 OPAMDROPWORKINGDIR overrides packages previously updated with
390 --working-dir on update. Without this variable set, opam would keep
391 them unchanged unless explicitly named on the command-line.
392
393 OPAMDRYRUN see option `--dry-run'.
394
395 OPAMEDITOR sets the editor to use for opam file editing, overrides
396 $EDITOR and $VISUAL.
397
398 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
399 fails. 0 to print all.
400
401 OPAMEXTERNALSOLVER see option `--solver'.
402
403 OPAMFAKE see option `--fake'.
404
405 OPAMFETCH specifies how to download files: either `wget', `curl' or a
406 custom command where variables %{url}%, %{out}%, %{retry}%,
407 %{compress}% and %{checksum}% will be replaced. Overrides the
408 'download-command' value from the main config file.
409
410 OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup.
411
412 OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on'.
413
414 OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends'.
415
416 OPAMINPLACEBUILD see option `--inplace-build'.
417
418 OPAMJOBS sets the maximum number of parallel workers to run.
419
420 OPAMJSON log json output to the given file (use character `%' to index
421 the files).
422
423 OPAMKEEPBUILDDIR see install option `--keep-build-dir'.
424
425 OPAMKEEPLOGS tells opam to not remove some temporary command logs and
426 some backups. This skips some finalisers and may also help to get more
427 reliable backtraces.
428
429 OPAMLOCKED combination of `--locked' and `--lock-suffix' options.
430
431 OPAMLOGS logdir sets log directory, default is a temporary directory in
432 /tmp
433
434 OPAMMAKECMD set the system make command to use.
435
436 OPAMMERGEOUT merge process outputs, stderr on stdout.
437
438 OPAMNO answer no to any question asked, see options `--no` and
439 `--confirm-level`. OPAMNO is ignored if either OPAMCONFIRMLEVEL or
440 OPAMYES is set.
441
442 OPAMNOAGGREGATE with `opam admin check', don't aggregate packages.
443
444 OPAMNOASPCUD Deprecated.
445
446 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
447 in an earlier format to the current one, on 'update' or 'init'.
448
449 OPAMNOCHECKSUMS enables option --no-checksums when available.
450
451 OPAMNODEPEXTS disables system dependencies handling, see option
452 `--no-depexts'.
453
454 OPAMNOENVNOTICE Internal.
455
456 OPAMNOSELFUPGRADE see option `--no-self-upgrade'
457
458 OPAMPINKINDAUTO sets whether version control systems should be detected
459 when pinning to a local path. Enabled by default since 1.3.0.
460
461 OPAMPRECISETRACKING fine grain tracking of directories.
462
463 OPAMPREPRO set this to false to disable CUDF preprocessing. Less
464 efficient, but might help debugging solver issue.
465
466 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
467 available (e.g. for `opam install').
468
469 OPAMRETRIES sets the number of tries before failing downloads.
470
471 OPAMREUSEBUILDDIR see option `--reuse-build-dir'.
472
473 OPAMROOT see option `--root'. This is automatically set by `opam env
474 --root=DIR --set-root'.
475
476 OPAMROOTISOK don't complain when running as root.
477
478 OPAMSAFE see option `--safe'.
479
480 OPAMSHOW see option `--show'.
481
482 OPAMSKIPUPDATE see option `--skip-updates'.
483
484 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
485 compatibility testing only.
486
487 OPAMSOLVERALLOWSUBOPTIMAL (default `true') allows some solvers to still
488 return a solution when they reach timeout; while the solution remains
489 assured to be consistent, there is no guarantee in this case that it
490 fits the expected optimisation criteria. If `true', opam willcontinue
491 with a warning, if `false' a timeout is an error. Currently only the
492 builtin-z3 backend handles this degraded case.
493
494 OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
495 60.0, set to 0 for unlimited. Note that all solvers may not support
496 this option.
497
498 OPAMSTATS display stats at the end of command.
499
500 OPAMSTATUSLINE display a dynamic status line showing what's currently
501 going on on the terminal. (one of one of `always', `never' or `auto')
502
503 OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.).
504
505 OPAMSWITCH see option `--switch'. Automatically set by `opam env
506 --switch=SWITCH --set-switch'.
507
508 OPAMUNLOCKBASE see install option `--unlock-base'.
509
510 OPAMUPGRADECRITERIA specifies user preferences for dependency solving
511 when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
512 are set. See also option --criteria.
513
514 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
515
516 OPAMUSEOPENSSL force openssl use for hash computing.
517
518 OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
519 or `auto'). By default `auto', which is determined from the locale).
520
521 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
522 Implies OPAMUTF8. This is set by default on OSX only.
523
524 OPAMVALIDATIONHOOK if set, uses the `%{hook%}' command to validate an
525 opam repository update.
526
527 OPAMVERBOSE see option `--verbose'.
528
529 OPAMVERSIONLAGPOWER do not use.
530
531 OPAMWITHDOC see install option `--with-doc'.
532
533 OPAMWITHTEST see install option `--with-test.
534
535 OPAMWORKINGDIR see option `--working-dir'.
536
537 OPAMYES see options `--yes' and `--confirm-level`. OPAMYES has has
538 priority over OPAMNO and is ignored if OPAMCONFIRMLEVEL is set.
539
540 OPAMVAR_var overrides the contents of the variable var when
541 substituting `%{var}%` strings in `opam` files.
542
543 OPAMVAR_package_var overrides the contents of the variable package:var
544 when substituting `%{package:var}%` strings in `opam` files.
545
547 All scripts and programmatic invocations of opam should use `--cli' in
548 order to ensure that they work seamlessly with future versions of the
549 opam client. Additionally, blog posts or other documentation can
550 benefit, as it prevents information from becoming stale.
551
552 Although opam only supports roots (~/.opam/) for the current version,
553 it does provide backwards compatibility for its command-line interface.
554
555 Since CLI version support was only added in opam 2.1, use OPAMCLI to
556 select 2.0 support (as opam 2.0 will just ignore it), and `--cli=2.1'
557 for 2.1 (or later) versions, since an environment variable controlling
558 the parsing of syntax is brittle. To this end, opam displays a warning
559 if OPAMCLI specifies a valid version other than 2.0, and also if
560 `--cli=2.0' is specified.
561
562 The command-line version is selected by using the `--cli' option or the
563 OPAMCLI environment variable. `--cli' may be specified morethan once,
564 where the last instance takes precedence. OPAMCLI is only inspected if
565 `--cli' is not given.
566
568 As an exception to the following, the `exec' command returns 127 if the
569 command was not found or couldn't be executed, and the command's exit
570 value otherwise.
571
572 0 Success, or true for boolean queries.
573
574 1 False. Returned when a boolean return value is expected, e.g. when
575 running with --check, or for queries like opam lint.
576
577 2 Bad command-line arguments, or command-line arguments pointing to
578 an invalid context (e.g. file not following the expected format).
579
580 5 Not found. You requested something (package, version, repository,
581 etc.) that couldn't be found.
582
583 10 Aborted. The operation required confirmation, which wasn't given.
584
585 15 Could not acquire the locks required for the operation.
586
587 20 There is no solution to the user request. This can be caused by
588 asking to install two incompatible packages, for example.
589
590 30 Error in package definition, or other metadata files. Using
591 --strict raises this error more often.
592
593 31 Package script error. Some package operations were unsuccessful.
594 This may be an error in the packages or an incompatibility with
595 your system. This can be a partial error.
596
597 40 Sync error. Could not fetch some remotes from the network. This can
598 be a partial error.
599
600 50 Configuration error. Opam or system configuration doesn't allow
601 operation, and needs fixing.
602
603 60 Solver failure. The solver failed to return a sound answer. It can
604 be due to a broken external solver, or an error in solver
605 configuration.
606
607 99 Internal error. Something went wrong, likely due to a bug in opam
608 itself.
609
610 130 User interrupt. SIGINT was received, generally due to the user
611 pressing Ctrl-C.
612
614 See https://opam.ocaml.org/doc.
615
617 Vincent Bernardoff <vb@luminar.eu.org>
618 Raja Boujbel <raja.boujbel@ocamlpro.com>
619 Roberto Di Cosmo <roberto@dicosmo.org>
620 Thomas Gazagnaire <thomas@gazagnaire.org>
621 Louis Gesbert <louis.gesbert@ocamlpro.com>
622 Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
623 Anil Madhavapeddy <anil@recoil.org>
624 Guillem Rieu <guillem.rieu@ocamlpro.com>
625 Ralf Treinen <ralf.treinen@pps.jussieu.fr>
626 Frederic Tuong <tuong@users.gforge.inria.fr>
627
629 Check bug reports at https://github.com/ocaml/opam/issues.
630
631
632
633Opam 2.1.2 OPAM-SEARCH(1)