Installers
Velopack takes a relatively light-touch when it comes to installers, so there is not a lot of customisation available like you would find in other installation frameworks. This is the tradeoff Velopack makes to ensure that the developer/user experience is as fast and easy as possible.
In both operating systems, if code signing is configured the installer will also be signed. (This is required on MacOS)
Windows Overview
The Windows installer is currently a "one-click" installer, meaning when the Setup.exe binary is run, Velopack will not show any questions / wizards to the user, it will simply attempt to install the app as fast as possible and then launch it.
The setup will install a shortcut to StartMenuRoot and Desktop by default. [Read more]
The key options which will customize the installer are as follows:
--packTitle {app name}customizes shortcut names, the Apps & Features name, and the portable entry exe name.--icon {path}sets the .ico on Update.exe and Setup.exe (and also the icon of any dialogs shown)--splashImage {path}sets the (possibly animated) splash image to be shown while installing.
The splash image can be a jpeg, png, or gif. In the latter case, it will be animated.
You can also bootstrap required frameworks before installing your app.
The Windows installer will extract the application to %LocalAppData%\{packId}. For the resulting directory structure, see the canonical layout on the Windows page.
The current directory will be fully replaced while doing updates. The other files added by Velopack (Update.exe and sq.version) are crucial and are required files for Velopack to be able to properly update your application.
Windows MSI Installer
In addition to Setup.exe, Velopack can generate a .msi installer using WiX 5. The MSI provides full Windows Installer integration, including support for per-machine installs to Program Files, Group Policy deployment, and standard Add/Remove Programs entries.
To enable MSI generation, add the --msi flag to your vpk pack command. The MSI is built alongside Setup.exe during packaging.
Install Location
The --instLocation option controls where the MSI will install:
PerUser— installs to%LocalAppData%\{packId}(HKCU registry, no elevation required)PerMachine— installs toProgram Files\{publisher}\{packTitle}(HKLM registry, requires elevation)Either(default) — the user chooses during installation
MSI Options
| Option | Description |
|---|---|
--msi | Enable MSI generation |
--msiVersion | Override the product version (must be a valid MSI version, i.e. x.x.x.x) |
--instLocation | Set install scope: PerUser, PerMachine, or Either (default) |
--instWelcome {path} | Welcome message shown during install (.txt or .md) |
--instLicense {path} | License agreement (.txt, .md, or .rtf) |
--instReadme {path} | Readme message (.txt or .md) |
--instConclusion {path} | Conclusion message (.txt or .md) |
--msiBanner {path} | Top banner image for MSI dialogs (.bmp, 493x58) |
--msiLogo {path} | Background logo for MSI dialogs (.bmp, 493x312) |
Directory Structure
The MSI installs the same directory layout as Setup.exe (see the canonical layout on the Windows page), under {installFolder} instead of %LocalAppData%\{packId}.
After installation, updates work identically via Update.exe regardless of whether the app was installed with Setup.exe or the .msi.
Overriding the install location at install time
By default the MSI installs to the location implied by --instLocation (see above). A system administrator can override the destination at install time by setting the secure VELOPACK_INSTALLDIR property when running msiexec:
msiexec /i MyApp.msi /qn VELOPACK_INSTALLDIR="D:\Apps\MyApp"
When set, VELOPACK_INSTALLDIR takes precedence over the default per-user/per-machine path in both the UI and silent installs. This is the MSI equivalent of Setup.exe --installto.
Overriding the install location
Velopack offers three ways to control where your app is installed:
| Mechanism | When | Notes |
|---|---|---|
Setup.exe --installto <DIR> | install time | Overrides the default %LocalAppData%\{packId} location for the one-click Setup.exe. |
--instLocation PerUser|PerMachine|Either | pack time (MSI) | Sets the default install scope baked into the .msi. PerUser → %LocalAppData%\{packId}, PerMachine → Program Files\{publisher}\{packTitle}. |
VELOPACK_INSTALLDIR | install time (MSI) | Secure msiexec property that overrides the MSI's default destination, e.g. msiexec /i MyApp.msi /qn VELOPACK_INSTALLDIR="D:\Apps\MyApp". |
MacOS Overview
The MacOS installer will be a standard .pkg - which is just a bundle where the UI is provided by the operating system, allowing the user to pick the install location. The app will be launched automatically after the install (mirroring the behavior on Windows) because of a postinstall script added by Velopack.
The key options which will customize the installer are as follows:
--packTitle {app name}customizes the name of the.appbundle and the app name shown in the.pkg--instWelcome {path}adds a Welcome page--instReadme {path}adds a Readme page--instLicense {path}adds a License Acceptance page--instConclusion {path}adds a Conclusion page
These content arguments accept the file types supported by the macOS Installer, i.e. .txt, .rtf, or .html.
The .app package can be extracted to /Applications or ~/Applications, this is selected by the user while installing.