Debugging & Logging

Applies to

Windows

MacOS

Linux

Find or configure application logs to find runtime issues.

All parts of Velopack have logging built in to help troubleshoot issues, and you should provide these logs when opening a GitHub issue about a potential bug.

Logging in Velopack

All Velopack components (binaries, libraries, and the UpdateManager) log to a shared file by default. The log file name includes the app ID from sq.version when available (e.g. velopack_myapp.log), or falls back to velopack.log when no app context exists (such as during initial setup/install). Log files are automatically rotated at 1 MB.

For the Update.exe and Setup.exe binaries, you can override the log location with the --log {path} parameter. You can also use the --verbose flag to capture debug/trace output to the log file. Please see the command line reference for a comprehensive list of arguments supported.

Windows

• Default: %LocalAppData%\velopack\velopack_{appid}.log
• Setup.exe: %LocalAppData%\velopack\velopack.log (no app context at install time)
• Fallback: If %LocalAppData% is not accessible, logs are written to the system temp directory.

On Windows, to avoid showing up as a console window, the Velopack binaries are compiled as a WinExe and there will be no console output by default.

Linux

All logs will be sent to /tmp/velopack_{appid}.log (or /tmp/velopack.log without app context).

macOS

Logs are sent to ~/Library/Logs/velopack_{appid}.log. If ~/Library/Logs does not exist, falls back to /tmp/velopack_{appid}.log.

Advanced Log Handling

By default, the C# library logs to the same file as the Velopack binaries. You can provide an additional custom logger via VelopackApp.SetLogger(IVelopackLogger) — this will receive all diagnostic messages in addition to the default file log. A logger can also be provided to the UpdateManager via its IVelopackLocator Log property.

Note: If you provide a custom locator, the logger passed to SetLogger will be ignored — attach your logger to the custom locator instead.

For example:

using Velopack.Logging;

public class MyConsoleLogger : IVelopackLogger
{
    public void Log(VelopackLogLevel logLevel, string? message, Exception? exception)
    {
        var logMessage = $"[{DateTime.Now.ToShortTimeString()}] [{logLevel}] {message}";
        if (exception != null) {
            logMessage += Environment.NewLine + exception;
        }

        Console.WriteLine(logMessage);
    }
}

// Option 1: Pass to VelopackApp (used alongside default file logger)
VelopackApp.Build()
    .SetLogger(new MyConsoleLogger())
    .Run();

// Option 2: Pass to a custom locator
var locator = VelopackLocator.CreateDefaultForPlatform(logger: new MyConsoleLogger());
var updateManager = new UpdateManager("your-update-url", null, locator);

Environment variables

Velopack reads a handful of environment variables at runtime. These affect the behavior of the library and the bundled binaries (Setup.exe / Update.exe), and are unrelated to the vpk build tool's command-line options.

Variable	Set by	Description
VELOPACK_FIRSTRUN	Velopack	Set when your app is launched for the very first time after install. Velopack reads and clears it inside VelopackApp.Run(), surfacing it via the OnFirstRun hook. Read it only through the hook, not directly.
VELOPACK_RESTART	Velopack	Set when your app was restarted by Velopack to apply an update. Velopack reads and clears it inside VelopackApp.Run(), surfacing it via the OnRestarted hook.
VELOPACK_TEMP	You	Overrides the temp/working directory Velopack uses for downloading and staging updates. Useful in locked-down or CI environments where the default temp location is unavailable.
VELOPACK_DEBUG	You	When set, Velopack does not automatically exit the process after running a fast-callback hook (install/update/uninstall). Useful for attaching a debugger to inspect hook behavior. Leave unset in production.

The debug builds of Velopack binaries have additional logging/debugging capabilities, and will produce console output. In some instances, it may be useful to compile Velopack for your platform, and replace the release binaries of Setup.exe and Update.exe with debug versions.

If your issue is with package building, after building the rust binaries in Debug mode, it can also be useful to run the Velopack.Vpk project from Visual Studio with your intended command line arguments rather than running the vpk tool directly.

If doing this has not helped, you may need to debug and step through the rust binaries - for which I recommend the CodeLLDB VSCode extension.