CLI options for constructor-generated installers#

The are the command-line flags available in the installers generated by constructor.

Configure conda’s verbosity

Whether it’s while running constructor to build an installer, or while the installer is running in the target machine, some instance of conda will be running behind the scenes. You can request more verbose output via the CONDA_VERBOSITY environment variable. It can take values from 1 to 4. You can also set CONDA_DEBUG to 1.

Shell-based installers for MacOS and Linux#

We have the following CLI options available for MacOS and Linux:

  • -h (help): display the installer help message and exit.

  • -b (batch): run the installer in batch mode without user intervention.

  • -f (force): ignores existing installations and overwrites them.

  • -i (interactive): run in interactive mode (default).

  • -k (keep): do not delete the pkgs/ cache after installation.

  • -p PREFIX (path): installs to the given path.

  • -s (skip): do not run any pre/post-install scripts.

These options are available in installers that ship the conda package:

  • -t (test): can be used to run package tests after installation (it may install conda-build).

  • -u (update): try to update an existing conda installation.

Examples#

Run the installer in batch mode:

$ bash my_installer.sh -b

Run the installer in batch mode and install to a custom path:

$ bash my_installer.sh -b -p /opt/my_app

Extra verbosity

Get more verbose outputs by running the installer with -x and/or CONDA_VERBOSITY=3:

$ bash -x my_installer.sh
# or with verbose conda:
$ CONDA_VERBOSITY=3 bash -x my_installer.sh

Windows installers#

Windows installers have the following CLI options available:

  • /NCRC: disables the CRC check.

  • /S (silent): runs the installer in headless mode. Installers created with constructor 3.10 or later will report information to the active console. See below for different invocation examples.

  • /Q (quiet): do not report to the console in headless mode. Only relevant when used with /S (see above).

  • /InstallationType=[JustMe|AllUsers]: This flag sets the installation type. The default is JustMe. AllUsers might require elevated privileges.

  • /AddToPath=[0|1]: Whether to add the installation directory to the PATH environment variable. The default is 0. This is NOT recommended.

  • /CheckPathLength=[0|1]: Check whether the installation path is too long (>46 characters). The default depends on how the installer was created.

  • /KeepPkgCache=[0|1]: Whether to keep the package cache or not. Defaults to 1.

  • /NoRegistry=[0|1]: Whether to prevent registry modification or not. Defaults to 0.

  • /NoScripts=[0|1]: If set to 1, the installer will not run any post-install scripts. Defaults to 0.

  • /NoShortcuts=[0|1]: If set to 1, the installer will not create any shortcuts. Defaults to 0.

  • /RegisterPython=[0|1]: Whether to register Python as default in the Windows registry. Defaults to 1. This is preferred to AddToPath.

  • /D (directory): sets the default installation directory. Note that even if the path contains spaces, it must be the last parameter used in the command line and must not contain any quotes. Only absolute paths are supported.

Some of these flags are standard NSIS flags.

Windows uninstallers have the following CLI options:

  • /S (silent): uninstaller in headless mode. Uninstallers created with constructor 3.10 or later will report information to the console in a new window. See below for different invocation examples.

  • /Q (quiet): do not report to the console in headless mode. Only relevant when used with /S (see above). Also works for the uninstallers.

  • /RemoveCaches=[0|1] (only if built with uninstall_with_conda_exe): Removes caches such package caches. For details, see the constructor uninstall subcommand of the conda.exe file.

  • /RemoveConfigFiles=[none|user|system|all] (only if built with uninstall_with_conda_exe): Removes configuration files such as .condarc files. user removes the files inside the current user’s home directory and system removes all files outside of that directory. For details, see the constructor uninstall subcommand of the conda.exe file.

  • /RemoveUserData=[0|1] (only if built with uninstall_with_conda_exe): removes user data such as the ~/.conda directory. For details, see the constructor uninstall subcommand of the conda.exe file.

  • /Q (quiet): do not report to the console in headless mode. Only relevant when used with /S

  • /D (directory): sets the default installation directory. Note that even if the path contains spaces, it must be the last parameter used in the command line and must not contain any quotes. Only absolute paths are supported.

  • _?: like /D but prevents the uninstaller from copying itself to the temporary directory.

[!IMPORTANT] Flags without arguments should precede flags with arguments to avoid parsing errors.

Examples#

Run the installer in headless mode:

cmd.exe /C start /wait my_installer.exe /S

Start-Process -FilePath .\my_installer.exe -ArgumentList "/S" -NoNewWindow -Wait

Run the installer in headless mode, for all users, adding to PATH and installing to a custom path:

cmd.exe /C start /wait my_installer.exe /S /InstallationType=AllUsers /AddToPath=1 /D=C:\Program Files\my_app

Start-Process -FilePath .\my_installer.exe -ArgumentList "/S /InstallationType=AllUsers /AddToPath=1 /D=C:\Program Files\my_app" -NoNewWindow -Wait

Redirect the console output to a file named log.txt:

my_installer.exe /S > log.txt

Stream redirection only works if the installer is invoked directly. Unfortunately this means that the call won’t block and the installer will run in the background. If you need to block on the call, you can poll log.txt until you find Done! or :error:. We strongly recommend the Powershell alternative instead.

Start-Process -FilePath .\my_installer.exe -ArgumentList "/S" -NoNewWindow -Wait -RedirectStandardOutput log.txt

Run the uninstaller in headless mode from its original location:

cmd.exe /C start /wait C:\Program Files\my_app\uninstaller.exe /S _?=C:\Program Files\my_app

Start-Process -FilePath C:\Program Files\my_app\uninstaller.exe -ArgumentList "/S _?=C:\Program Files\my_app" -NoNewWindow -Wait

EXE installers with file logging

Windows installers do not have a verbose mode. By default, the graphical logs are only available in the “progress bar” dialog, by clicking on “Show details”. This text box is right-clickable, which will allow you to copy the contents to the clipboard (and then paste them in a text file, presumably).

There’s a way of building EXE installers that can write logs to a file; for this, you need a special nsis package configured to do so:

> conda install "nsis=*=*log*"

Then, you can invoke constructor normally after setting a special environment variable:

> set "NSIS_USING_LOG_BUILD=1"
> constructor .

The resulting EXE installer will always generate an install.log file in the target directory. It will contain the full logs, as available in the “Show details” dialog.

Combine this with CONDA_VERBOSITY=3 at install time for maximum details:

> set "CONDA_VERBOSITY=3"
> cmd.exe /c start /wait your-installer.exe

PKG installers#

The PKG installers do not offer any CLI options. Instead, you need to use the installer subcommand:

$ installer -pkg my_installer.pkg -dumplog -target CurrentUserHomeDirectory
# with extra verbosity from conda
$ CONDA_VERBOSITY=3 installer -pkg my_installer.pkg -dumplog -target CurrentUserHomeDirectory

Note you can’t choose a custom path for the installation. Instead, you can only choose a target. Refer to man installer for more information.