1OPAM-SEARCH(1) Opam Manual OPAM-SEARCH(1)
2
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 See opam list --help for details.
15
17 -A, --all
18 Include all, even uninstalled or unavailable packages
19 -a, --available
21 List only packages that are available on the current system
22 --base
24 List only the immutable base of the current switch (i.e. compiler
25 packages)
26 --coinstallable-with=PACKAGES
28 Only list packages that are compatible with all of PACKAGES.
29 --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 --depends-on=PACKAGES
37 List only packages that depend on one of (comma-separated)
38 PACKAGES.
39 --depopts
41 Include optional dependencies in dependency requests.
42 --dev
44 Include development packages in dependencies.
45 --field-match=FIELD:PATTERN
47 Filter packages with a match for PATTERN on the given FIELD
48 --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 --has-tag=TAG
54 Only includes packages which have the given tag set
55 -i, --installed
57 List installed packages only. This is the default when no further
58 arguments are supplied
59 --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 --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 --nobuild
72 Exclude build dependencies (they are included by default).
73 --or
75 Instead of selecting packages that match all the criteria, select
76 packages that match any of them
77 --owns-file=FILE
79 Finds installed packages responsible for installing the given file
80 --pinned
82 List only the pinned packages
83 --post
85 Include dependencies tagged as post.
86 --recursive
88 With `--depends-on' and `--required-by', display all transitive
89 dependencies rather than just direct dependencies.
90 --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 --required-by=PACKAGES
97 List only the dependencies of (comma-separated) PACKAGES.
98 --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 --roots, --installed-roots
113 List only packages that were explicitly installed, excluding the
114 ones installed as dependencies
115 -t, --with-test, --test
117 Include test-only dependencies.
118 --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 -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 --normalise
141 Print the values of opam fields normalised
142 -S, --sort
144 Sort the packages in dependency order (i.e. an order in which they
145 could be individually installed.)
146 -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 --separator=STRING (absent= )
152 Set the column-separator string
153 -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 --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 --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 --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 --silent
185 Don't write anything in the output, exit with return code 0 if the
186 list is not empty, 1 otherwise.
187 --version
189 Show version information.
190
192 These options are common to all commands.
193 --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 --color=WHEN
201 Colorize the output. WHEN must be one of `always', `never' or
202 `auto'.
203 --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 --cudf=FILENAME
213 Debug option: Save the CUDF requests sent to the solver to
214 FILENAME-<n>.cudf.
215 --debug
217 Print debug message to stderr. This is equivalent to setting
218 $OPAMDEBUG to "true".
219 --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 --git-version
225 Print the git version of opam, if set (i.e. you are using a
226 development version), and exit.
227 --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 --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 --no-aspcud
240 Deprecated.
241 --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 --no-self-upgrade
252 Opam will replace itself with a newer binary found at OPAMROOT/opam
253 if present. This disables this behaviour.
254 -q, --quiet
256 Disables --verbose.
257 --root=ROOT
259 Use ROOT as the current root path. This is equivalent to setting
260 $OPAMROOT to ROOT.
261 --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 --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 --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 --switch=SWITCH
283 Use SWITCH as the current compiler switch. This is equivalent to
284 setting $OPAMSWITCH to SWITCH.
285 --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 -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 -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 -y, --yes
304 Answer yes to all yes/no questions without prompting. This is
305 equivalent to setting $OPAMYES to "true".
306
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 OPAMALLPARENS surround all filters with parenthesis
313 OPAMAUTOREMOVE see remove option `--auto-remove`
315 OPAMBESTEFFORT see option `--best-effort`
317 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 OPAMCOLOR, when set to always or never, sets a default value for the
323 --color option.
324 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 OPAMCUDFFILE file save the cudf graph to file-actions-explicit.dot
330 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
332 for more options.
333 OPAMDEBUG see options `--debug' and `--debug-level'.
335 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
337 OPAMDRYRUN see option `--dry-run`
339 OPAMEDITOR sets the editor to use for opam file editing, overrides
341 $EDITOR and $VISUAL
342 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
344 fails. 0 to print all.
345 OPAMEXTERNALSOLVER see option `--solver'.
347 OPAMFAKE see option `--fake`
349 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 OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup
356 OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on`
358 OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends`
360 OPAMJOBS sets the maximum number of parallel workers to run.
362 OPAMJSON log json output to the given file (use character `%' to index
364 the files)
365 OPAMLOCKED see install option `--locked`
367 OPAMLOGS logdir sets log directory, default is a temporary directory in
369 /tmp
370 OPAMMAKECMD set the system make command to use
372 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
374 in an earlier format to the current one, on 'update' or 'init'.
375 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 OPAMLOCKRETRIES sets the number of tries after which opam gives up
381 acquiring its lock and fails. <= 0 means infinite wait.
382 OPAMMERGEOUT merge process outputs, stderr on stdout
384 OPAMNO answer no to any question asked.
386 OPAMNOASPCUD Deprecated.
388 OPAMNOCHECKSUMS enables option --no-checksums when available.
390 OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
392 OPAMPINKINDAUTO sets whether version control systems should be detected
394 when pinning to a local path. Enabled by default since 1.3.0.
395 OPAMPRECISETRACKING fine grain tracking of directories
397 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
399 available (e.g. for `opam install`).
400 OPAMRETRES sets the number of tries before failing downloads.
402 OPAMROOT see option `--root'. This is automatically set by `opam env
404 --root=DIR --set-root'.
405 OPAMROOTISOK don't complain when running as root.
407 OPAMSAFE see option `--safe'
409 OPAMSHOW see option `--show`
411 OPAMSKIPUPDATE see option `--skip-updates`
413 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
415 compatibility testing only.
416 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 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 OPAMSTATS display stats at the end of command
425 OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.)
427 OPAMSWITCH see option `--switch'. Automatically set by `opam env
429 --switch=SWITCH --set-switch'.
430 OPAMUNLOCKBASE see install option `--unlock-base`
432 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 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
438 OPAMUSEOPENSSL force openssl use for hash computing
440 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 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
445 Implies OPAMUTF8. This is set by default on OSX only.
446 OPAMVALIDATIONHOOK hook if set, uses the `%{hook%}` command to validate
448 an opam repository update
449 OPAMVAR_var overrides the contents of the variable var when
451 substituting `%{var}%` strings in `opam` files.
452 OPAMVAR_package_var overrides the contents of the variable package:var
454 when substituting `%{package:var}%` strings in `opam` files.
455 OPAMVERBOSE see option `--verbose'.
457 OPAMWORKINGDIR see option `--working-dir`
459 OPAMYES see option `--yes'.
461
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 0 Success, or true for boolean queries.
468 1 False. Returned when a boolean return value is expected, e.g. when
470 running with --check, or for queries like opam lint.
471 2 Bad command-line arguments, or command-line arguments pointing to
473 an invalid context (e.g. file not following the expected format).
474 5 Not found. You requested something (package, version, repository,
476 etc.) that couldn't be found.
477 10 Aborted. The operation required confirmation, which wasn't given.
479 15 Could not acquire the locks required for the operation.
481 20 There is no solution to the user request. This can be caused by
483 asking to install two incompatible packages, for example.
484 30 Error in package definition, or other metadata files. Using
486 --strict raises this error more often.
487 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 40 Sync error. Could not fetch some remotes from the network. This can
493 be a partial error.
494 50 Configuration error. Opam or system configuration doesn't allow
496 operation, and needs fixing.
497 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 99 Internal error. Something went wrong, likely due to a bug in opam
503 itself.
504 130 User interrupt. SIGINT was received, generally due to the user
506 pressing Ctrl-C.
507
509 See https://opam.ocaml.org/doc.
510
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
524 Check bug reports at https://github.com/ocaml/opam/issues.
525Opam 2.0.6 OPAM-SEARCH(1)