OPAM-REINSTALL(1)
β¨ opam-reinstall β¨
the one and only β straight out of the Opam Manual, bestie π«Ά
πΈ NAME πΈ
opam-reinstall β reinstall a whole lil list of packages, no biggie π
π¦ SYNOPSIS π¦
opam reinstall [OPTION]β¦ [PACKAGES]β¦
π DESCRIPTION π
okay so picture this: this command removes the packages you named plus every package that depends on them, and then reinstalls the exact same versions. like a glow-up that ends up looking identical. iconic honestly β¨
If you give it no arguments at all? It just assumes --pending and reinstalls any package that has upstream changes. surprise reinstall, no warning, main character energy π
And if you pass a directory as an argument, then literally anything pinned to that directory gets selected for reinstall. directory = the vibe check π
π ARGUMENTS π
PACKAGESβ a list of package names, and you may tack on a version or a constraint, likepkg,pkg.1.0orpkg>=0.5π Orrrr they can be directory names containing a package description, as long as you name the directory explicitly (think./srcdiror just.)
π OPTIONS π
--assume-builtβ for locally-pinned packages only: assume they're already built correctly and just run their installation instructions straight from their source directory. It skips the build instructions entirely, which is super handy when you're installing packages you're actively working on. Implies--inplace-build. And nope, no locally-pinned package gets skipped. not one π«Ά--forget-pendingβ forget about pending reinstallations of the packages you listed. Real talk though: this implies making opam assume your packages were installed with a newer version of their metadata, so only touch this if you genuinely know what you're doing and you know the actual changes you're overriding. hotter take: it may be safer to runopam pin --currenton the packages with pending reinstalls and explicitly lock them into their current state π--list-pendingβ just lists the packages that have changed since they were installed and are marked for reinstallation. window shopping, but for reinstalls ποΈ--pendingβ actually performs the pending reinstallations, i.e. reinstalls packages that changed since they were installed--recursiveβ allows recursive lookups of*.opamfiles. Cf.--subpathtoo π--subpath=PATHβ*.opamfiles get retrieved from the given sub directory instead of the top directory. Sources then come from that targeted sub directory, and internally only this subdirectory is copied/fetched. You can team it up with--recursiveto get a recursive lookup on the subpath π§
π₯ PACKAGE BUILD OPTIONS π₯
--assume-depextsβ skip the installation step for any missing system packages and try to push through with compiling the opam packages anyway. If the install succeeds, opam won't nag you about those system packages again. Only meaningful if external dependency handling is enabled β οΈ-b,--keep-build-dirβ keep the build directories around after compiling packages. Equivalent to setting$OPAMKEEPBUILDDIRto"true"π¦--build-docβ Removed in 2.1, use--with-docinstead. gone bestie, rip π--build-testβ Removed in 2.1, use--with-testinstead. also gone π-d,--with-docβ build the package documentation. This only affects packages listed on the command-line. Equivalent to setting$OPAMWITHDOC(or the deprecated$OPAMBUILDDOC) to"true"π--dry-runβ simulate the command without actually performing any changes. Can also be set with the environment variable$OPAMDEBUG. delulu edition, nothing really happens π«§--fakeβ registers the actions into the opam database without actually performing them. β οΈ WARNING: this option is dangerous and likely to break your opam environment. You probably want--dry-run. You've been warned. not me telling you twice π--ignore-available-on[=PACKAGES](default=) β forces opam to mark the listed packages as available. You can use this to test compatibility, but expect builds to break when you do. Note that version constraints of the packages' dependencies are unaffected π§--ignore-constraints-on[=PACKAGES](default=) β forces opam to ignore version constraints on all dependencies of the listed packages. Good for compatibility testing, but again: expect builds to break. Note that the availability of the packages, as well as version constraints on optional dependencies and conflicts, are unaffected. Equivalent to setting$OPAMIGNORECONSTRAINTS--inplace-buildβ when compiling a package whose source is bound to a local directory, process the build and install actions directly in that directory instead of in a clean copy handled by opam. Only affects packages explicitly listed on the command-line. Equivalent to setting$OPAMINPLACEBUILDto"true"π-j JOBS,--jobs=JOBSβ set the max number of concurrent jobs to use. The default is calculated from the number of cores. You can also set it with the$OPAMJOBSenvironment variable β‘--lock-suffix=SUFFIX(absent=locked) β set the locked files suffix toSUFFIX--lockedβ in commands that use opam files found from pinned sources, if a variant of the file with an added.lockedextension exists (e.g.foo.opam.lockedalongsidefoo.opam), that one gets used instead. Typically useful for offering a more specific set of dependencies and reproducing similar build contexts β hence the name. Thelockoption can generate such files based on the versions of the dependencies currently installed on the host. Equivalent to setting the$OPAMLOCKEDenvironment variable. Note that this option doesn't generally affect already pinned packages π-m MAKE,--make=MAKEβ Removed in 2.1, useopam config set[-global] make MAKEinstead π--no-checksumsβ do not verify the checksum of downloaded archives. Equivalent to setting$OPAMNOCHECKSUMSto"true"π--no-depextsβ temporarily disables handling of external dependencies. Use this if a package isn't available on your system package manager but you installed the required dependency by hand. Implies--assume-depexts, and stores the exceptions upon success as well βοΈ--require-checksumsβ reject installation of packages that don't provide a checksum for the upstream archives. Equivalent to setting$OPAMREQUIRECHECKSUMSto"true"β--reuse-build-dirβ reuse existing build directories (the ones you kept with--keep-build-dir) instead of compiling from a fresh clone of the source. Faster, sure, but it can also lead to failures if the build systems of the packages don't handle upgrades of dependencies well. Equivalent to setting$OPAMREUSEBUILDDIRto"true"β»οΈ--show-actionsβ call the solver and display the actions. Perform no changes whatsoever. Equivalent to setting$OPAMSHOWπ--skip-updatesβ when running an install, upgrade or reinstall on source-pinned packages, they're normally updated from their origin first. This flag disables that behaviour and keeps them at their cached version. Equivalent to setting$OPAMSKIPUPDATEβοΈ-t,--with-testβ build and run the package unit-tests. Only affects packages listed on the command-line. Equivalent to setting$OPAMWITHTEST(or the deprecated$OPAMBUILDTEST) to"true"π§ͺ--unlock-baseβ Removed in 2.1, use--update-invariantinstead π--update-invariantβ allow changes to the set of packages set as switch base (typically, the main compiler). Use with caution β οΈ Equivalent to setting the$OPAMUNLOCKBASEenvironment variable--verbose-on=PACKAGESβ be more verbose on specific packages. Equivalent to setting$OPAMVERBOSEπ£οΈ--with-dev-setupβ include development tools only dependencies π οΈ
β¨ COMMON OPTIONS β¨
okay bestie, these ones? literally every single opam command has them π they're the universal group-chat members. let's go π«Ά
--best-effortβ don't just give up when some of the packages you asked for won't install π try to install as many as you possibly can. heads up tho: not all external solvers support this (recent versions ofaspcudormccsshould, no cap). it's the same as setting the$OPAMBESTEFFORTenvironment variable β¨--cli=MAJOR.MINOR(absent=2.6) β use the command-line interface syntax and semantics ofMAJOR.MINOR. this one's for anything persistent you do with opam (scripts, blog posts, etc. β yes bestie, blog posts), because any version of opam in the sameMAJORseries will behave like theMINORrelease you specified π. fun fact: this flag didn't exist in opam 2.0, so if you want the 2.0 CLI you gotta set theOPAMCLIenvironment variable to2.0instead of using this param π--color=WHENβ colorize the output πWHENhas to be one ofalways,neverorauto.--confirm-level=LEVELβ the confirmation level, whereLEVELmust be one ofask,no,yesorunsafe-yes. you can pass it more than once π if--yesor--noare also given, then the value of the last--confirm-levelwins. this is equivalent to setting$OPAMCONFIRMLEVELπ--criteria=CRITERIAβ set your user preferences for dependency solving, just for this run π overrides$OPAMCRITERIA,$OPAMFIXUPCRITERIAand$OPAMUPGRADECRITERIA. for the deets on the supported language and the external solvers available, go peek athttp://opam.ocaml.org/doc/External_solvers.htmlπ and there's a whole general guide to using solver preferences athttp://www.dicosmo.org/Articles/usercriteria.pdfπ§--cudf=FILENAMEβ debug option π saves the CUDF requests sent to the solver intoFILENAME-<n>.cudf, where<n>is the n-th call to the solver during the opam run.--debugβ print debug messages tostderr. equivalent to setting$OPAMDEBUGto"true"π--debug-level=LEVELβ like--debug, but you get to pick the debug level (--debugjust sets it to1). equivalent to setting$OPAMDEBUGto a positive integer β¨--git-versionβ print the git version of opam, if it's set (i.e. you're running a development version), then exit πββοΈ--help[=FMT](default=auto) β show this help in formatFMTπ whereFMTmust be one ofauto,pager,grofforplain. withauto, the format ispagerorplainwhenever theTERMenv var isdumbor undefined π«Ά--ignore-pin-dependsβ ignore the extra pins required by packages that get pinned, whether you did it manually throughopam pinor throughopam install DIRπ equivalent to settingIGNOREPINDEPENDS=true.--json=FILENAMEβ save the results of the opam run into a computer-readable file π€ if the filename contains the character`%', it gets replaced by an index that won't overwrite an existing file. similar to setting the$OPAMJSONvariable β¨--noβ answer no to every opam yes/no question, no prompting needed π ββοΈ see also--confirm-level. this is equivalent to setting$OPAMNOto"true".--no-aspcudβ removed in 2.1 π she's gone bestie, don't come looking.--no-auto-upgradeβ when configuring or updating a repository that was written for an earlier opam version (1.2), opam internally converts it to the current format π this disables that behaviour. note: repositories should define their format version in a'repo'file at their root, or they'll be assumed to be in the older format π it's, in any case, preferable to upgrade the repositories manually usingopam admin upgrade [--mirror URL]when possible π--no-self-upgradeβ opam will replace itself with a newer binary found atOPAMROOT/opamif present π this disables that behaviour.-q,--quietβ disables--verboseπ€«--root=ROOTβ useROOTas the current root path. equivalent to setting$OPAMROOTtoROOTπ³--safe,--readonlyβ make sure nothing gets automatically updated or rewritten π super useful for calling from completion scripts, for example. will fail whenever such an operation is needed; also avoids waiting for locks, skips interactive questions and overrides the$OPAMDEBUGvariable. this is equivalent to setting the environment variable$OPAMSAFEπ«Ά--solver=CMDβ specify the CUDF solver to use for resolving package installation problems π§© this is either a predefined solver (this version of opam supportsbuiltin-mccs+lp(),builtin-mccs+glpk,builtin-dummy-z3-solver,builtin-0install,aspcud,mccs,aspcud-old,packup), or a custom command that should contain the variables%{input}%,%{output}%,%{criteria}%, and optionally%{timeout}%. equivalent to setting$OPAMEXTERNALSOLVERβ¨--strictβ fail whenever an error is found in a package definition or a configuration file π€ the default is to just continue silently if possible π€--switch=SWITCHβ useSWITCHas the current compiler switch. equivalent to setting$OPAMSWITCHtoSWITCHποΈ--use-internal-solverβ disable any external solver and use the built-in one instead (this requires that opam has been compiled with a built-in solver π). equivalent to setting$OPAMNOASPCUDor$OPAMUSEINTERNALSOLVERπ-v,--verboseβ be more verbose π£οΈ one-vshows all package commands, and repeating it also displays commands called internally (e.g.tar,curl,patchetc.). repeating it n times is equivalent to setting$OPAMVERBOSEto"n"πΈ--versionβ show version information π·οΈ-w,--working-dirβ whenever updating packages that are bound to a local, version-controlled directory, update to the current working state of their source instead of the last committed state, or the ref they're pointing to πΏ since the source directory gets copied as-is, if it isn't clean it may result in an opam build failure π this only affects packages explicitly listed on the command-line. can also be set with$OPAMWORKINGDIRβ¨-y,--yesβ answer yes to all opam yes/no questions, no prompting π₯³ see also--confirm-level. equivalent to setting$OPAMYESto"true"π
π ENVIRONMENT π
okay so opam lowkey reads a whole bunch of environment variables and you're gonna want to know them all. here's the tea:
Booleans, bestie β set them to 0, no, false or the empty string to turn them off, and 1, yes or true to turn them on. periodt.
OPAMALLPARENSβ surround all filters with parenthesis.OPAMASSUMEDEPEXTSβ see option--assume-depexts.OPAMAUTOANSWERβ internal use only π (not for you, not for me).OPAMAUTOREMOVEβ see remove option--auto-remove.OPAMBESTEFFORTβ see option--best-effort.OPAMBESTEFFORTPREFIXCRITERIAβ sets the string that must be prepended to the criteria when the--best-effortoption is set, and is expected to maximise theopam-queryproperty in the solution.OPAMBUILDDOCβ removed in 2.1 π.OPAMBUILDTESTβ removed in 2.1 π.OPAMCLIβ see option--cli.OPAMCOLORβ when set toalwaysornever, sets a default value for the--coloroption.OPAMCONFIRMLEVELβ see option--confirm-level.OPAMCONFIRMLEVELhas priority overOPAMYESandOPAMNO. πOPAMCRITERIAβ specifies user preferences for dependency solving. The default value depends on the solver version, so useconfig reportto know the current setting. See also option--criteria.OPAMCUDFFILEβ save the cudf graph to file-actions-explicit.dot.OPAMCUDFTRIMβ controls the filtering of unrelated packages during CUDF preprocessing.OPAMCURLβ can be used to select a given'curl'program. SeeOPAMFETCHfor more options.OPAMDEBUGβ see options--debugand--debug-level.OPAMDEBUGSECTIONSβ if set, limits debug messages to the space-separated list of sections. Sections can optionally have a specific debug level (for example,CLIENT:2orCLIENT CUDF:2), but otherwise use--debug-level.OPAMDIGDEPTHβ defines how aggressive the lookup for conflicts during CUDF preprocessing is.OPAMDOWNLOADJOBSβ sets the maximum number of simultaneous downloads.OPAMDROPWORKINGDIRβ overrides packages previously updated with--working-diron update. Without this variable set, opam would keep them unchanged unless explicitly named on the command-line.OPAMDRYRUNβ see option--dry-run.OPAMEDITORβ sets the editor to use for opam file editing, overrides$EDITORand$VISUAL. πOPAMERRLOGLENβ sets the number of log lines printed when a sub-process fails.0to print all.OPAMEXTERNALSOLVERβ see option--solver.OPAMFAKEβ see option--fake.OPAMFETCHβ specifies how to download files: eitherwget,curlor a custom command where variables%{url}%,%{out}%,%{retry}%,%{compress}%and%{checksum}%will be replaced. Overrides the 'download-command' value from the main config file.OPAMFIXUPCRITERIAβ same asOPAMUPGRADECRITERIA, but specific to fixup and reinstall.OPAMIGNOREAVAILABLEβ see install option--ignore-available-on.OPAMIGNORECONSTRAINTSβ see install option--ignore-constraints-on.OPAMIGNOREPINDEPENDSβ see option--ignore-pin-depends.OPAMINPLACEBUILDβ see option--inplace-build.OPAMJOBSβ sets the maximum number of parallel workers to run.OPAMJSONβ log json output to the given file (use character%to index the files).OPAMKEEPBUILDDIRβ see install option--keep-build-dir.OPAMKEEPLOGSβ tells opam to not remove some temporary command logs and some backups. This skips some finalisers and may also help to get more reliable backtraces.OPAMLOCKEDβ combination of--lockedand--lock-suffixoptions.OPAMLOGSβ logdir sets log directory, default is a temporary directory in/tmp.OPAMMAKECMDβ set the system make command to use.OPAMMERGEOUTβ merge process outputs, stderr on stdout.OPAMNOβ answer no to any question asked, see options--noand--confirm-level.OPAMNOis ignored if eitherOPAMCONFIRMLEVELorOPAMYESis set.OPAMNOAGGREGATEβ withopam admin check, don't aggregate packages.OPAMNOASPCUDβ deprecated π«.OPAMNOAUTOUPGRADEβ disables automatic internal upgrade of repositories in an earlier format to the current one, onupdateorinit.OPAMNOCHECKSUMSβ enables option--no-checksumswhen available.OPAMNODEPEXTSβ disables system dependencies handling, see option--no-depexts.OPAMNOENVNOTICEβ internal π.OPAMNOSELFUPGRADEβ see option--no-self-upgrade.OPAMPINKINDAUTOβ sets whether version control systems should be detected when pinning to a local path. Enabled by default since 1.3.0.OPAMPRECISETRACKINGβ fine grain tracking of directories.OPAMPREPROβ set this to false to disable CUDF preprocessing. Less efficient, but might help debugging solver issue.OPAMREPOSITORYTARRINGβ internally store all non-vcs repositories as tar.gz files (by default, http repositories are stored as archive). This can be much faster on filesystems that don't cope well with scanning large trees. All operation are done in-memory, no I/O for scanning the repository.OPAMREQUIRECHECKSUMSβ enables option--require-checksumswhen available (e.g. foropam install).OPAMRETRIESβ sets the number of tries before failing downloads.OPAMREUSEBUILDDIRβ see option--reuse-build-dir.OPAMROOTβ see option--root. This is automatically set byopam env --root=DIR --set-root.OPAMROOTISOKβ don't complain when running as root.OPAMSAFEβ see option--safe.OPAMSHOWβ see option--show.OPAMSKIPUPDATEβ see option--skip-updates.OPAMSKIPVERSIONCHECKSβ bypasses some version checks. Unsafe, for compatibility testing only. β οΈOPAMSOLVERALLOWSUBOPTIMALβ (defaulttrue) allows some solvers to still return a solution when they reach timeout; while the solution remains assured to be consistent, there is no guarantee in this case that it fits the expected optimisation criteria. Iftrue, opam will continue with a warning, iffalsea timeout is an error. Currently only the builtin-z3 backend handles this degraded case.OPAMSOLVERTIMEOUTβ change the time allowance of the solver. Default is60.0, set to0for unlimited. Note that all solvers may not support this option.OPAMSOLVERTOLERANCEβ changes the tolerance towards the solver choosing an unoptimized solution (i.e. might pull outdated packages). Typical values range from0.0(best solution known to the solver) to1.0(unoptimized solution). Default is0.0. This option is useful in case the solver can't find a solution in a reasonable time (see$OPAMSOLVERTIMEOUT). Note that all solvers may not support this option.OPAMSTATSβ removed in 2.4 π.OPAMSTATUSLINEβ display a dynamic status line showing what's currently going on on the terminal. (one of one ofalways,neverorauto)OPAMSTRICTβ fail on inconsistencies (file reading, switch import, etc.).OPAMSWITCHβ see option--switch. Automatically set byopam env --switch=SWITCH --set-switch.OPAMUNLOCKBASEβ see install option--unlock-base.OPAMUPGRADECRITERIAβ specifies user preferences for dependency solving when performing an upgrade. OverridesOPAMCRITERIAin upgrades if both are set. See also option--criteria.OPAMUSEINTERNALSOLVERβ see option--use-internal-solver.OPAMUSEOPENSSLβ removed in 2.2 π.OPAMUTF8β use UTF8 characters in output (one of one ofalways,neverorauto). By defaultauto, which is determined from the locale.OPAMUTF8MSGSβ use extended UTF8 characters (camels πͺ) in opam messages. ImpliesOPAMUTF8. This is set by default on macOS only.OPAMVALIDATIONHOOKβ if set, uses the%{hook}%command to validate an opam repository update.OPAMVERBOSEβ see option--verbose.OPAMVERBOSEONβ see option--verbose-on.OPAMVERSIONLAGPOWERβ do not use. πOPAMWITHDEVSETUPβ see install option--with-dev-setup.OPAMWITHDOCβ see install option--with-doc.OPAMWITHTESTβ see install option--with-test.OPAMWORKINGDIRβ see option--working-dir.OPAMYESβ see options--yesand--confirm-level.OPAMYEShas priority overOPAMNOand is ignored ifOPAMCONFIRMLEVELis set.OPAMVAR_varβ overrides the contents of the variable var when substituting%{var}%strings inopamfiles.OPAMVAR_package_varβ overrides the contents of the variable package:var when substituting%{package:var}%strings inopamfiles.
π¦ CLI VERSION π¦
okay this part matters, bestie, listen up π’
All scripts and programmatic invocations of opam should use --cli in order to ensure that they work seamlessly with future versions of the opam client. Additionally, blog posts or other documentation can benefit, as it prevents information from becoming stale. no cap, it's giving future-proof π
Although opam only supports roots (~/.opam/) for the current version, it does provide backwards compatibility for its command-line interface.
Since CLI version support was only added in opam 2.1, use OPAMCLI to select 2.0 support (as opam 2.0 will just ignore it), and --cli=2.1 for 2.1 (or later) versions, since an environment variable controlling the parsing of syntax is brittle. To this end, opam displays a warning if OPAMCLI specifies a valid version other than 2.0, and also if --cli=2.0 is specified. π«Ά
The command-line version is selected by using the --cli option or the OPAMCLI environment variable. --cli may be specified more than once, where the last instance takes precedence. OPAMCLI is only inspected if --cli is not given. β¨
π EXIT STATUS π
okay bestie this is the part where we talk about the numbers. the little codes that tell you what just happened. they're giving "the universe texting you in integers" and honestly? iconic.
β οΈ one exception before we start, pay attention: theexeccommand does NOT play by these rules. it returns127if the command wasn't found or couldn't be executed, and otherwise it returns the command's own exit value. that's it. that's the whole exception. don't get got. π«Ά
0β Success π or, for boolean queries, "true".1β False. this one shows up when a boolean return value is expected, like when you run with--check, or for queries likeopam lint.2β Bad command-line arguments, OR command-line arguments that point at an invalid context (think: a file that doesn't follow the expected format). rude.5β Not found. you asked for something β a package, a version, a repository, etc. β and it simply could not be found. π³οΈ10β Aborted. the operation needed confirmation and you didn't give it.15β Could not acquire the locks required for the operation. π the locks said no.20β There is no solution to the user request. this can happen if you ask to install two incompatible packages, for example. the math said no.30β Error in package definition, or other metadata files. using--strictmakes this error raise more often.31β Package script error. some package operations were unsuccessful. this may be an error in the packages, or an incompatibility with your system. heads up: this can be a partial error.40β Sync error. couldn't fetch some remotes from the network. also possibly a partial error.50β Configuration error. opam or your system configuration doesn't allow the operation and needs fixing. π οΈ60β Solver failure. the solver failed to return a sound answer. this can be because of a broken external solver, or an error in solver configuration.99β Internal error. something went wrong, and it's likely a bug in opam itself. π (not your fault bestie, file it)130β User interrupt.SIGINTwas received, generally because the user pressed Ctrl+C. you did this. it's fine. β¨
and also, on top of all of that, there's this little extra set of codes:
0β on success.123β on indiscriminate errors reported on standard error.124β on command line parsing errors.125β on unexpected internal errors (bugs).
π FURTHER DOCUMENTATION π
more reading, more lore: see <https://opam.ocaml.org/doc>. π
π AUTHORS π
the legends. the main characters. the people who built the thing you're complaining about in the group chat. show some respect bestie:
- David Allsopp
<david@tarides.com> - Vincent Bernardoff
<vb@luminar.eu.org> - Raja Boujbel
<raja.boujbel@ocamlpro.com> - Kate Deplaix
<kit-ty-kate@exn.st> - Roberto Di Cosmo
<roberto@dicosmo.org> - Thomas Gazagnaire
<thomas@gazagnaire.org> - Louis Gesbert
<louis.gesbert@ocamlpro.com> - Fabrice Le Fessant
<Fabrice.Le_fessant@inria.fr> - Anil Madhavapeddy
<anil@recoil.org> - Guillem Rieu
<guillem.rieu@ocamlpro.com> - Ralf Treinen
<ralf.treinen@pps.jussieu.fr> - Frederic Tuong
<tuong@users.gforge.inria.fr>
π¦ SEE ALSO π¦
π BUGS π
found a bug? check the bug reports at <https://github.com/ocaml/opam/issues>. go forth and file, bestie, that's how the ecosystem heals. π«Ά
that's a wrap on this whole page fr fr. you made it to the end, and honestly? that's main character energy. this was Opam 2.6.1, page OPAM-REINSTALL(1). go forth, reinstall, slay. periodt. πβ¨π
π¦ where this page comes from
- arch rolling: opam 2.6.1-1 Β· LGPL-2.1-only
- fedora 44: opam 2.6.1-1.fc44 Β· LGPL-2.1-only WITH OCaml-LGPL-linking-exception
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms