How-to guides#

Control which kind of installer gets generated#

Constructor is currently limited to generating installers for the platform on which it is running. In other words, if you run constructor on a Windows computer, you can only generate Windows installers. This is largely because OS-native tools are needed to generate the Windows .exe files and macOS .pkg files. There is a key in construct.yaml, installer_type, which dictates the type of installer that gets generated. This is primarily only useful for macOS, where you can generate either .pkg or .sh installers. When not set in construct.yaml, this value defaults to .sh on Unix platforms, and .exe on Windows. Using this key is generally done with selectors. For example, to build a .pkg installer on MacOS, but fall back to default behavior on other platforms:

installer_type: pkg  #[osx]

See installer_type for more details.

Customization and branding#

Graphical installers (.pkg on macOS and .exe on Windows) support some level of branding and customization.

Logos, backgrounds and banners:

Messages and texts. You can specify these via *_file (a path is expected) or _text (raw string expected).

On Windows, you can also add extra pages to the installer. This is an advanced option, so your best bet is to check the examples in the source repository at examples/customized_welcome_conclusion.

Signing and notarization#

See also

Example of a CI pipeline implementing:

Signing EXE installers#

Windows can trigger SmartScreen alerts for EXE installers, signed or not. It does help when they are signed, though. Read this SO answer about SmartScreen reputation for more details.

constructor supports the following tools to sign installers:

The signtool that is used can be set in the construct.yaml file via the windows_signing_tool key. If the signing_certificate key is set, windows_signing_tool defaults to signtool.

For each tool, there are environment variables that may need to be set to configure signing.

Environment variables for SignTool#

Variable

Description

CLI flag

Default

CONSTRUCTOR_PFX_CERTIFICATE_PASSWORD

Password for the pfx certificate file.

/p

Empty

CONSTRUCTOR_SIGNTOOL_PATH

Path to signtool.exe. Needed if signtool is not in PATH.

N/A

signtool

CONSTRUCTOR_SIGNTOOL_FILE_DIGEST

Digest algorithm for creating the file signatures.

/fd

sha256

CONSTRUCTOR_SIGNTOOL_TIMESTAMP_SERVER_URL

URL to the RFC 3161 timestamp server.

/tr

http://timestamp.sectigo.com

CONSTRUCTOR_SIGNTOOL_TIMESTAMP_DIGEST

Digest algorithm for the RFC 3161 time stamp.

/td

sha256

Environment variables for AzureSignTool#

Variable

Description

CLI flag

Default

AZURE_SIGNTOOL_FILE_DIGEST

Digest algorithm for creating the file signatures.

-fd

sha256

AZURE_SIGNTOOL_KEY_VAULT_ACCESSTOKEN

An access token used to authenticate to Azure.

-kva

Empty

AZURE_SIGNTOOL_KEY_VAULT_CERTIFICATE

The name of the certificate in the key vault.

-kvc

Empty

AZURE_SIGNTOOL_KEY_VAULT_CLIENT_ID

The client ID used to authenticate to Azure. Required for authentication with a secret.

-kvi

Empty

AZURE_SIGNTOOL_KEY_VAULT_SECRET

The client secret used to authenticate to Azure. Required for authentication with a secret.

-kvs

Empty

AZURE_SIGNTOOL_KEY_VAULT_TENANT_ID

The tenant ID used to authenticate to Azure. Required for authentication with a secret.

-kvt

Empty

AZURE_SIGNTOOL_KEY_VAULT_URL

The URL of the key vault with the certificate.

-kvu

Empty

AZURE_SIGNTOOL_PATH

Path to AzureSignTool.exe. Needed if azuresigntool is not in PATH.

N/A

azuresigntool

AZURE_SIGNTOOL_TIMESTAMP_SERVER_URL

URL to the RFC 3161 timestamp server.

-tr

http://timestamp.sectigo.com

AZURE_SIGNTOOL_TIMESTAMP_DIGEST

Digest algorithm for the RFC 3161 time stamp.

-td

sha256

Note

If neither AZURE_SIGNTOOL_KEY_VAULT_ACCESSTOKEN nor AZURE_SIGNTOOL_KEY_VAULT_SECRET are set, constructor will use a Managed Identity (-kvm CLI option).

Signing and notarizing PKG installers#

In the case of macOS, users might get warnings for PKGs if the installers are not signed and notarized. However, once these two requirements are fulfilled, the warnings disappear instantly. constructor offers some configuration options to help you in this process:

You will need to provide two identity names:

  • the installer certificate identity (via signing_identity_name) to sign the pkg installer,

  • the application certificate identity to pass the notarization (via notarization_identity_name); this certificate is used to sign binaries and plugins inside the pkg installer. These can be obtained in the Apple Developer portal. Once signed, you can notarize your PKG with Apple’s notarytool.

Note

To sign a pkg installer, the keychain containing the identity names must be unlocked and in the keychain search list.

Create shortcuts

On Windows, conda supports menuinst 1.x shortcuts. If a package provides a certain JSON file under $PREFIX/Menu, conda will process it to create the specified menu items. This happens by default for all packages. If you only want this to happen for certain packages, use the menu_packages key.

Starting with conda 23.11, menuinst 2.x is supported, which means you can create shortcuts in all platforms (Linux, macOS and Windows). The JSON document format is slightly different, so make sure to check the menuinst documentation. Your installer will need to be created with conda-standalone 23.11 or above. micromamba does not currently support menuinst 2.x style shortcuts (only 1.x on Windows).

To learn more about menuinst, visit conda/menuinst.

Find out the used constructor version

Recent constructor versions (>=3.4.2) burn-in their version into created installers in order to be able to trace back bugs in created installers to the constructor code base.

The burned-in version can be retrieved in different ways depending on the installer type:

  • For .sh intallers (via cli): head $installer.sh | grep "Created by constructor"

  • For .exe installers (via Windows Explorer): $installer.exe → Properties → Details → Comments, or (via cli) exiftool $installer.exe

  • For .pkg installers (via cli on macOS): xar -xf $installer.pkg -n run_installation.pkg/Scripts; zgrep -a "Created by constructor" run_installation.pkg/Scripts or pkgutil --expand $installer.pkg extracted; grep "Created by constructor" extracted/run_installation.pkg/Scripts/postinstall

Uninstall constructor-generated installations

Note

Many constructor installers ship conda (Miniconda, Miniforge, etc), and offer the user to initialize the installation. This adds further changes to the system configuration. These changes won’t be reverted by simply deleting the installation directory. If you want to revert these changes, you can execute this command before deleting the installation directory.

$ conda init --reverse --all

Use the --dry-run flag if you want to check what things will be reverted before actually doing it.

Windows#

On Windows, constructor-generated installations include an uninstaller executable, which is also exposed in the Control Panel menu “Add or remove programs”. The uninstaller executable is located in the installation directory, and is named Uninstall-<INSTALLATION_NAME>.exe.

Once opened, the uninstaller will guide the user through the uninstallation process. It will also remove the installation directory, and the uninstaller executable itself. In certain cases, some dangling files might be left behind, but these will be removed in the next reboot.

If you want to perform the uninstallation steps manually, you can:

  1. Remove the installation directory. Usually this is a directory in your user’s home directory (user installs), or under C:\Program Files for system-wide installations.

  2. In some installations, remove the entries added to the registry. System installs will use HKEY_LOCAL_MACHINE as the top level key; user installs will use HKEY_CURRENT_USER. You might find these items:

    • Uninstaller information: TOP_LEVEL_KEY\Software\Microsoft\Windows\CurrentVersion\Uninstall\<INSTALLATION_NAME>.

    • Python information: TOP_LEVEL_KEY\Software\Python\PythonCore\<PYTHON_VERSION>. Verify that these entries correspond to the installation directory you removed in step 1.

    • PATH modifications. You’ll need to remove the entries corresponding to the installation directory, but leave the other locations intact. This is better handled via the UI available in the Control Panel (follow these instructions). The actual registry keys (in case you are curious) are located in:

      • System install: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\PATH.

      • User install: HKEY_CURRENT_USER\Environment\PATH

  3. In some installations, remove the associated shortcuts under %APPDATA%\Microsoft\Windows\Start Menu\Programs\ (user installs) or %PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\ (system installs). You can enter these paths directly in the Windows Explorer address bar to open them.

macOS and Linux#

Note

The following sections requires installers to be built using the uninstall_with_conda_exe option. This is currently only implemented for conda-standalone 24.11.0 and higher.

For other installers, all files need to be removed manually.

Unlike Windows, macOS and Linux installers do not ship an uninstaller executable. However, some standalone applications (like conda-standalone) provide an uninstaller subcommand. The following can be used to uninstall an existing installation:

$ $INSTDIR/_conda constructor uninstall --prefix $INSTDIR

where $INSTDIR is the installation directory. This command recursively removes all environments and removes shell initializers that point to $INSTDIR.

The command supports additional options to delete files outside the installation directory:

  • --remove-caches: Removes cache directories such as package caches and notices. Not recommended with multiple conda installations when softlinks are enabled.

  • --remove-config-files {user,system,all}: Removes all configuration files such as .condarc files outside the installation directory. user removes the files inside the current user’s home directory and system removes all files outside of that directory.

  • --remove-user-data: This removes user data files such as the ~/.conda directory.

These options are not recommended if multiple conda installations are on the same system because they delete commonly used files.

Note

If removing these files requires superuser privileges, use sudo -E instead of sudo since finding these files may rely on environment variables, especially $HOME.

For more detailed implementation notes, see the documentation of the standalone application:

Control how conda runs on your machine#

The traditional installation mechanism for conda is for the constructor-generated installer to run the initialization logic once the files have been copied into the target directory $INSTDIR:

%INSTDIR%\_conda.exe init --all

$INSTDIR/bin/conda init --all

On most shells, conda init will modify your shell configuration (.bashrc and similar files) to inject a conda shell function that wraps the actual Python conda modules (see activation deep dive guide for more details). This is needed so that conda activate and conda deactivate can modify the state of the current shell session.

While very convenient, this shell logic requires significant modifications in the shell profiles and also adds a runtime overhead everytime a shell session starts. For users that prefer a simpler PATH-based initialization strategy, a alternative method is provided with conda 25.5.0 and later:

conda init --condabin

This new option only adds $INSTDIR/condabin to PATH, which is a minimally invasive change to your shell configuration and has no runtime overhead. This directory is special because it is guaranteed to only contain the conda executables and nothing else.

As an installer author, you can control which of these options are made available to the end user:

  • initialize_conda: classic: the classic, shell-function-based initialization logic. Default.

  • initialize_conda: condabin: the new, lightweight PATH-only logic.

Note

The --condabin initialization won’t be sufficient to run conda activate, and conda will error out saying you need to fully initialize your installation. This might get fixed in the future, but for now, you can rely on an experimental plugin to use a different activation strategy that doesn’t require shell modifications: conda-spawn. Add it to your specs definition and it will be available in your installations as conda spawn.