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 0. 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

MSI installers#

MSI installers use Windows Installer (msiexec) instead of NSIS. They support a different set of command-line options passed as public properties.

Installation#

> msiexec /i your-installer.msi [properties] [options]

Common msiexec options:

Option

Description

/i <msi>

Install the specified MSI package

/x <msi>

Uninstall the specified MSI package

/qn

No UI (completely silent)

/qb

Basic UI (progress bar only)

/qr

Reduced UI

/l*v <logfile>

Verbose logging to file

Installer properties (passed as PROPERTY=value):

Property

Description

Default

ALLUSERS

1 for all users, 0 (or empty) for current user

Per-user

TARGETDIR

Installation directory

%LOCALAPPDATA%\<name> (per-user) or %PROGRAMFILES%\<name> (all users)

OPTION_REGISTER_PYTHON

Register as system Python (1 or 0)

0

OPTION_INITIALIZE_CONDA

Add to PATH (1 or 0)

0

OPTION_CLEAR_PACKAGE_CACHE

Clear package cache after install (1 or 0)

1

OPTION_ENABLE_SHORTCUTS

Create shortcuts (1 or 0)

1

OPTION_PRE_INSTALL_SCRIPT

Run pre-install script if configured (1 or 0)

0

OPTION_POST_INSTALL_SCRIPT

Run post-install script if configured (1 or 0)

0

Uninstallation#

MSI installers can be uninstalled via:

  1. Add/Remove Programs: Right-click and select “Uninstall”

  2. Double-clicking the MSI file: Shows a dialog with “Repair” and “Remove” options

  3. Command line: msiexec /x your-installer.msi [options]

Options 2 and 3 support additional cleanup properties (see below). Option 1 performs a basic uninstall without these options.

Uninstaller properties (passed as PROPERTY=value):

Property

Description

Default

OPTION_REMOVE_USER_DATA

Remove user data like ~/.conda (1 or 0)

0

OPTION_REMOVE_CACHES

Remove package caches (1 or 0)

0

OPTION_REMOVE_CONFIG_FILES

Remove .condarc files (1 or 0)

0

Examples#

Install silently for the current user:

> msiexec /i MyApp.msi /qn

Install silently for all users to a custom directory:

> msiexec /i MyApp.msi /qn ALLUSERS=1 TARGETDIR="C:\Program Files\MyApp"

Install silently with verbose logging:

> msiexec /i MyApp.msi /qn /l*v install.log

Install silently, registering Python and adding to PATH:

> msiexec /i MyApp.msi /qn OPTION_REGISTER_PYTHON=1 OPTION_INITIALIZE_CONDA=1

Uninstall silently:

> msiexec /x MyApp.msi /qn

Uninstall silently with cleanup options:

> msiexec /x MyApp.msi /qn OPTION_REMOVE_CACHES=1 OPTION_REMOVE_CONFIG_FILES=1

Note

Unlike EXE installers which display help with /?, MSI installers rely on msiexec /? for general Windows Installer help. See this documentation for constructor-specific properties.

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.