Documentation Index
Fetch the complete documentation index at: https://mintlify.com/microsoft/winget-cli/llms.txt
Use this file to discover all available pages before exploring further.
Overview
InstallOptions provides comprehensive control over package installation behavior. These options apply to both InstallPackageAsync and UpgradePackageAsync operations.
Class Definition
runtimeclass InstallOptions
{
InstallOptions();
// Version selection
PackageVersionId PackageVersionId;
// Installation behavior
String PreferredInstallLocation;
PackageInstallScope PackageInstallScope;
PackageInstallMode PackageInstallMode;
String LogOutputPath;
Boolean AllowHashMismatch;
String ReplacementInstallerArguments;
String AdditionalInstallerArguments;
// Metadata
String CorrelationData;
String AdditionalPackageCatalogArguments;
// Architecture
IVector<ProcessorArchitecture> AllowedArchitectures { get; };
// Advanced options
Boolean AllowUpgradeToUnknownVersion;
Boolean Force;
Boolean AcceptPackageAgreements;
Boolean BypassIsStoreClientBlockedPolicyCheck;
Boolean SkipDependencies;
PackageInstallerType InstallerType;
// Authentication
AuthenticationArguments AuthenticationArguments;
}
Properties
PackageVersionId
Specifies which version to install. If not set, uses DefaultInstallVersion.
var options = new InstallOptions();
// Install specific version
var versionId = new PackageVersionId()
{
PackageCatalogId = "winget",
Version = "1.5.0",
Channel = ""
};
options.PackageVersionId = versionId;
// Or leave null for latest version
options.PackageVersionId = null; // Uses package.DefaultInstallVersion
PackageInstallScope
Specifies whether to install for current user or system-wide.
Any - Installer determines scope (default)User - Install for current user onlySystem - Install system-wide (requires admin)UserOrUnknown - User or unknown scope allowedSystemOrUnknown - System or unknown scope allowed
var options = new InstallOptions()
{
PackageInstallScope = PackageInstallScope.User
};
// For system-wide install (requires elevation)
var systemOptions = new InstallOptions()
{
PackageInstallScope = PackageInstallScope.System
};
PackageInstallMode
Controls installer UI behavior.
Default - Installer’s default experience (may show UI)Silent - Suppress UI where possibleInteractive - Show full installer UI
// Silent installation (no UI)
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent
};
// Interactive installation
var interactiveOptions = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Interactive
};
PreferredInstallLocation
Alternate installation location (if supported by installer).
var options = new InstallOptions()
{
PreferredInstallLocation = @"D:\Programs\MyApp"
};
// Note: Not all installers support custom locations
LogOutputPath
Path to write installation log file.
var logPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"WinGet", "Logs", $"install-{DateTime.Now:yyyyMMdd-HHmmss}.log"
);
var options = new InstallOptions()
{
LogOutputPath = logPath
};
Console.WriteLine($"Install log will be written to: {logPath}");
AllowHashMismatch
Continue installation even if installer hash doesn’t match catalog.
Use with caution. Hash mismatches may indicate corrupted or tampered installers.
// Only use when absolutely necessary
var options = new InstallOptions()
{
AllowHashMismatch = true
};
ReplacementInstallerArguments
ReplacementInstallerArguments
Custom arguments that replace default installer arguments.
// Override ALL installer arguments
var options = new InstallOptions()
{
ReplacementInstallerArguments = "/S /D=C:\\CustomPath"
};
// Equivalent to: winget install --override "/S /D=C:\CustomPath"
AdditionalInstallerArguments
AdditionalInstallerArguments
Additional arguments appended to default installer arguments.
// Add to default arguments
var options = new InstallOptions()
{
AdditionalInstallerArguments = "/NORESTART /LOG=install.log"
};
// Equivalent to: winget install --custom "/NORESTART /LOG=install.log"
AcceptPackageAgreements
Automatically accept package agreements and license terms.
var options = new InstallOptions()
{
AcceptPackageAgreements = true
};
// Check agreements before accepting
var package = match.CatalogPackage;
var version = package.DefaultInstallVersion;
var metadata = version.GetCatalogPackageMetadata();
if (metadata.Agreements.Count > 0)
{
Console.WriteLine("Package requires accepting agreements:");
foreach (var agreement in metadata.Agreements)
{
Console.WriteLine($"- {agreement.Label}");
Console.WriteLine($" {agreement.Text}");
Console.WriteLine($" URL: {agreement.Url}");
}
// User confirms acceptance
options.AcceptPackageAgreements = true;
}
AllowedArchitectures
AllowedArchitectures
IVector<ProcessorArchitecture>
Allowed architectures in preference order.
using Windows.System;
var options = new InstallOptions();
// Prefer ARM64, fall back to x64
options.AllowedArchitectures.Clear();
options.AllowedArchitectures.Add(ProcessorArchitecture.Arm64);
options.AllowedArchitectures.Add(ProcessorArchitecture.X64);
// Or prefer native architecture
var arch = Package.Current.Id.Architecture;
options.AllowedArchitectures.Add(arch);
Force
Force installation, bypassing non-security related checks.
var options = new InstallOptions()
{
Force = true // Override non-critical failures
};
SkipDependencies
Skip installing package dependencies.
var options = new InstallOptions()
{
SkipDependencies = true
};
// Install only the main package, not dependencies
InstallerType
Force specific installer type when multiple are available.
Unknown - Auto-detectMsix - MSIX/AppX installerMsi - MSI installerExe - Executable installerInno - Inno SetupNullsoft - NSIS installerWix - WiX installerBurn - WiX Burn bundlePortable - Portable application
var options = new InstallOptions()
{
InstallerType = PackageInstallerType.Msi
};
// Force MSI installer if multiple types available
AllowUpgradeToUnknownVersion
AllowUpgradeToUnknownVersion
Allow upgrading to packages with unknown version.
var options = new InstallOptions()
{
AllowUpgradeToUnknownVersion = true
};
// Used for upgrade operations when version comparison isn't possible
CorrelationData
JSON-encoded correlation data returned in result.
using System.Text.Json;
var correlationData = new
{
SessionId = Guid.NewGuid().ToString(),
UserId = "user123",
Timestamp = DateTime.UtcNow
};
var options = new InstallOptions()
{
CorrelationData = JsonSerializer.Serialize(correlationData)
};
var result = await manager.InstallPackageAsync(package, options);
// Retrieve correlation data from result
Console.WriteLine($"Correlation: {result.CorrelationData}");
AuthenticationArguments
Authentication arguments for package download.
var authArgs = new AuthenticationArguments()
{
AuthenticationMode = AuthenticationMode.SilentPreferred,
AuthenticationAccount = "user@contoso.com"
};
var options = new InstallOptions()
{
AuthenticationArguments = authArgs
};
// Used when downloading from authenticated sources
Common Scenarios
Silent Installation
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent,
AcceptPackageAgreements = true,
PackageInstallScope = PackageInstallScope.User
};
System-Wide Installation with Logging
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent,
PackageInstallScope = PackageInstallScope.System,
LogOutputPath = @"C:\Logs\install.log",
AcceptPackageAgreements = true
};
// Requires administrator privileges
Custom Install Location
var options = new InstallOptions()
{
PreferredInstallLocation = @"D:\Apps\MyApplication",
PackageInstallMode = PackageInstallMode.Silent,
AdditionalInstallerArguments = "/NORESTART"
};
// Note: Not all installers support custom locations
Upgrade with Version Control
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent,
AllowUpgradeToUnknownVersion = true,
Force = true,
LogOutputPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"Logs", $"upgrade-{DateTime.Now:yyyyMMdd-HHmmss}.log"
)
};
var result = await manager.UpgradePackageAsync(package, options);
Development/Testing Installation
var options = new InstallOptions()
{
PackageInstallMode = PackageInstallMode.Silent,
AllowHashMismatch = true, // Allow testing pre-release builds
Force = true,
SkipDependencies = false,
LogOutputPath = @"C:\Dev\Logs\install.log"
};