Skip to main content

Parcel configuration reference

A .parcel file contains the settings that Parcel uses to publish, package, and sign an application. The file has five top-level sections: GeneralSettings, PublishSettings, Win32Settings, MacOsSettings, and LinuxSettings.

Parcel resolves relative paths from the location of the .parcel file. If you use Save As or Move To, Parcel updates relative paths for the new project location.

Setting values

For most scalar settings, you can specify a literal value, an environment variable, or an MSBuild property. In the GUI, select the value source next to the setting. Use environment variables for passwords, access tokens, and other secrets. Do not store secrets directly in a .parcel file.

If the project does not define a supported setting, Parcel checks its automatic environment variable. The following tables give the exact variable names. Collection settings and structured-object settings do not have automatic environment-variable overrides.

The defaults in this reference describe the resulting package behavior. Parcel writes some defaults when it creates a project. It applies other defaults during packaging if a setting is empty.

General settings

These settings apply to every target platform. They appear on the Basics page.

Setting.parcel propertyType or valuesDefaultEnvironment variableDescription
ProjectGeneralSettings.NetProjectPathPathRequiredPath to the application .csproj file. Parcel manages this field.
Package NameGeneralSettings.PackageNameStringAssembly namePARCEL_GENERAL_PACKAGE_NAMEPackage identifier and output file name. Platform-specific normalization may apply.
Assembly NameGeneralSettings.AssemblyNameStringProject file namePARCEL_GENERAL_ASSEMBLY_NAMEName of the executable assembly. This advanced field is normally read from the .NET project.
Application NameGeneralSettings.ApplicationNameStringPackage namePARCEL_GENERAL_APPLICATION_NAMEDisplay name used by installers, bundles, shortcuts, and desktop entries.
VersionGeneralSettings.VersionVersion string1.0.0PARCEL_GENERAL_VERSIONApplication and package version. Parcel converts it to the format required by each platform.
Application IconGeneralSettings.IconPath to an iconParcel default iconPARCEL_GENERAL_ICONShared application icon. A platform icon overrides it when configured.
CompanyGeneralSettings.CompanyStringPackage name where requiredPARCEL_GENERAL_COMPANYSets the Windows publisher and Linux package maintainer unless a platform setting overrides it. Maximum 255 characters.
File AssociationsGeneralSettings.FileTypesCollectionNoneFile types registered by supported installers and bundles.
URL SchemesGeneralSettings.UrlTypesCollectionNoneURL schemes registered by supported installers and bundles.

File associations v1.1 New!

Each entry in GeneralSettings.FileTypes has the following properties:

PropertyTypeRequiredDescription
GeneralSettings.FileTypes[].NameStringYesHuman-readable file type name.
GeneralSettings.FileTypes[].ExtensionStringExtension or MIME typeExtension with or without a leading period. After normalization, it must contain 1–10 lowercase letters or digits.
GeneralSettings.FileTypes[].MimeTypeStringExtension or MIME typeMIME type such as application/x-example. Parcel generates one when Linux needs it and it is omitted.

Each entry in GeneralSettings.UrlTypes has the following properties:

PropertyTypeRequiredDescription
GeneralSettings.UrlTypes[].NameStringYesHuman-readable name for the URL type.
GeneralSettings.UrlTypes[].SchemesStringYesOne or more RFC 3986 schemes without ://, separated by commas, semicolons, or spaces.

Parcel adds associations to NSIS and MSIX packages on Windows, application bundles on macOS, and DEB and RPM desktop entries on Linux.

On Windows, file association requires an extension. Windows cannot register an entry that contains only a MIME type.

On macOS, associations require MacOsSettings.CreateBundle.

.NET publish settings

These settings control the dotnet publish operation Parcel runs before packaging.

Setting.parcel propertyTypeDefaultEnvironment variableDescription
ConfigurationPublishSettings.ConfigurationString.NET project defaultPARCEL_NET_CONFIGURATIONBuild configuration. It must begin with a letter and contain only letters, digits, _, or -.
Publish Single FilePublishSettings.PublishSingleFileBooleanEnabled for new Parcel projectsPARCEL_NET_PUBLISH_SINGLE_FILEPublishes managed assemblies in a single executable.
Publish TrimmedPublishSettings.PublishTrimmedBoolean.NET project defaultPARCEL_NET_PUBLISH_TRIMMEDEnables trimming to reduce the package size. Testing the trimmed application is recommended.
Publish AOTPublishSettings.PublishAotBoolean.NET project defaultPARCEL_NET_PUBLISH_AOTEnables Native AOT compilation.
Publish ReadyToRunPublishSettings.PublishReadyToRunBoolean.NET project defaultPARCEL_NET_PUBLISH_READY_TO_RUNPrecompiles assemblies to improve startup performance.
Publish Self-ContainedPublishSettings.PublishSelfContainedBooleantruePARCEL_NET_PUBLISH_SELF_CONTAINEDIncludes the .NET runtime. This advanced field is not shown in the GUI.
MSBuild PropertiesPublishSettings.ExtraBuildPropertiesString dictionaryEmptyAdditional properties passed to dotnet publish.
Exclude FilesPublishSettings.ExcludeFilePatternsList of glob patternsEmptyRemoves matching files and directories from the published output before packaging.
note

Parcel respects .NET publish properties defined in the *.csproj file. There is no need to duplicate them in the Parcel config.

Windows settings

Installer and MSIX

Setting.parcel propertyTypeDefaultEnvironment variableDescription
Installer IconWin32Settings.InstallerIconPath to ICO or SVGApplication IconPARCEL_WINDOWS_INSTALLER_ICONOverrides the shared icon for the NSIS installer and generated MSIX assets.
Create Company FolderWin32Settings.CompanyFolderBooleanfalsePARCEL_WINDOWS_COMPANY_FOLDERAdds a company directory to the NSIS installation and Start Menu paths.
License FileWin32Settings.InstallerLicensePath to TXT or RTFNonePARCEL_WINDOWS_INSTALLER_LICENSEDisplays a license acceptance page in the NSIS installer.
Requires AdminWin32Settings.InstallerRequiresAdminBooleantruePARCEL_WINDOWS_INSTALLER_REQUIRES_ADMINInstalls NSIS packages under Program Files with elevation. When disabled, installs for the current user.
Include uninstaller with the appWin32Settings.IncludeUninstallerBooleantruePARCEL_WINDOWS_INCLUDE_UNINSTALLERIncludes an NSIS uninstaller and registers the application in Windows installed-app listings.
PublisherWin32Settings.MsixPublisherDistinguished nameCompany or application namePARCEL_WINDOWS_MSIX_PUBLISHERMSIX publisher identity. For signed packages, it must exactly match the certificate subject.

Signing

Win32Settings.SigningType accepts None, LocalCertificate, WindowsCertificateStore, AzureTrustedSigning, AzureKeyVault, AwsKeyManagementService, DigiCert, GoogleKeyManagementService, or ESigner. The GUI names AzureTrustedSigning Azure Artifact Signing.

Setting.parcel propertyTypeDefaultEnvironment variableDescription
Signing TypeWin32Settings.SigningTypeSigning typeNonePARCEL_WINDOWS_SIGNING_TYPESelects the Authenticode signing provider.
Sign InstallerWin32Settings.SignInstallerBooleantruePARCEL_WINDOWS_SIGN_INSTALLERSigns the generated NSIS or MSIX package and the application files. Disable it when a store or later pipeline signs the package.
Additional signing patternsWin32Settings.AdditionalSignPatternsList of glob patternsEmptyIncludes additional code files in application signing.
Timestamp Server URLWin32Settings.SigningTimestampServerURLNonePARCEL_WINDOWS_SIGNING_TIMESTAMP_SERVERTimestamp authority used with a local certificate or the Windows certificate store.
Local Signing Certificate FileWin32Settings.LocalSigningCertificatePath to PFX or P12Required for local certificatePARCEL_WINDOWS_LOCAL_SIGNING_CERTIFICATECertificate and private key used for local signing.
Local Signing Certificate PasswordWin32Settings.LocalSigningCertificatePasswordSecret stringEmptyPARCEL_WINDOWS_LOCAL_SIGNING_CERTIFICATE_PASSWORDPassword protecting the local certificate.
Store Certificate NameWin32Settings.StoreCertificateNameStringRequired for certificate storePARCEL_WINDOWS_STORE_CERTIFICATE_NAMECertificate subject or thumbprint in the Windows certificate store.
Use Local Machine Certificate StoreWin32Settings.UseLocalMachineCertificateStoreBooleanfalsePARCEL_WINDOWS_USE_LOCAL_MACHINE_CERTIFICATE_STORESearches Local Machine instead of Current User. Windows only.
Auto-Detect Matching CertificateWin32Settings.AutoDetectMatchingCertificateBooleanfalsePARCEL_WINDOWS_AUTO_DETECT_MATCHING_CERTIFICATEAllows SignTool to choose a matching certificate. Windows only.
Azure Artifact Signing EndpointWin32Settings.TrustedSigningEndpointAzure signing URLRequiredPARCEL_WINDOWS_TRUSTED_SIGNING_ENDPOINTAzure Artifact Signing service endpoint.
Azure Artifact Signing Certificate Profile NameWin32Settings.TrustedSigningCertificateProfileNameStringRequiredPARCEL_WINDOWS_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAMEAzure Artifact Signing certificate profile.
Azure Artifact Signing Account NameWin32Settings.TrustedSigningCodeSigningAccountNameStringRequiredPARCEL_WINDOWS_TRUSTED_SIGNING_CODE_SIGNING_ACCOUNT_NAMEAzure Artifact Signing account.
Azure Key Vault NameWin32Settings.AzureKeyVaultNameStringRequired unless URL identifies itPARCEL_WINDOWS_AZURE_KEY_VAULT_NAMEAzure Key Vault name.
Azure Key Vault URLWin32Settings.AzureKeyVaultUrlAbsolute HTTP(S) URLPublic Azure endpointPARCEL_WINDOWS_AZURE_KEY_VAULT_URLFull vault URL, including sovereign-cloud endpoints.
Azure Key Vault Certificate NameWin32Settings.AzureKeyVaultCertificateNameStringRequiredPARCEL_WINDOWS_AZURE_KEY_VAULT_CERTIFICATE_NAMECertificate stored in Azure Key Vault.
AWS Region CodeWin32Settings.AwsSigningRegionCodeStringRequiredPARCEL_WINDOWS_AWS_SIGNING_REGION_CODEAWS region containing the signing key.
AWS Signing Certificate FileWin32Settings.AwsSigningCertificateFilePathRequiredPARCEL_WINDOWS_AWS_SIGNING_CERTIFICATE_FILECertificate corresponding to the private key in AWS KMS.
AWS Signing Key ID or AliasWin32Settings.AwsSigningKeyIdOrAliasStringRequiredPARCEL_WINDOWS_AWS_SIGNING_KEY_ID_OR_ALIASAWS KMS key identifier or alias.
DigiCert API KeyWin32Settings.DigiCertApiKeySecret stringRequiredPARCEL_WINDOWS_DIGI_CERT_API_KEYDigiCert ONE API key.
DigiCert KeystoreWin32Settings.DigiCertKeystorePath to PKCS#12RequiredPARCEL_WINDOWS_DIGI_CERT_KEYSTOREClient-authentication keystore.
DigiCert StorepassWin32Settings.DigiCertStorepassSecret stringRequiredPARCEL_WINDOWS_DIGI_CERT_STOREPASSPassword for the DigiCert keystore.
DigiCert Certificate Name or IDWin32Settings.DigiCertCertificateNameOrIdStringRequiredPARCEL_WINDOWS_DIGI_CERT_CERTIFICATE_NAME_OR_IDCertificate name or ID in DigiCert ONE.
DigiCert HostWin32Settings.DigiCertHostHTTP(S) URLUS DigiCert ONE hostPARCEL_WINDOWS_DIGI_CERT_HOSTOverrides the DigiCert ONE service host.
Google Access TokenWin32Settings.GoogleAccessTokenSecret stringRequiredPARCEL_WINDOWS_GOOGLE_ACCESS_TOKENOAuth 2.0 access token for Google Cloud KMS.
Google Signing KeyringWin32Settings.GoogleSigningKeyringKeyring resource pathRequiredPARCEL_WINDOWS_GOOGLE_SIGNING_KEYRINGResource path through projects, locations, and keyRings.
Google Signing Certificate FileWin32Settings.GoogleSigningCertificateFilePathRequiredPARCEL_WINDOWS_GOOGLE_SIGNING_CERTIFICATE_FILECertificate corresponding to the Google Cloud KMS key.
Google Signing Certificate VersionWin32Settings.GoogleSigningCertificateVersionStringLatestPARCEL_WINDOWS_GOOGLE_SIGNING_CERTIFICATE_VERSIONSpecific key version to use.
eSigner User NameWin32Settings.ESignerUserNameStringRequiredPARCEL_WINDOWS_E_SIGNER_USER_NAMESSL.com account username.
eSigner PasswordWin32Settings.ESignerPasswordSecret stringRequiredPARCEL_WINDOWS_E_SIGNER_PASSWORDSSL.com account password.
eSigner Key PasswordWin32Settings.ESignerKeyPasswordSecret stringRequiredPARCEL_WINDOWS_E_SIGNER_KEY_PASSWORDBase64-encoded TOTP secret.
eSigner Credential IDWin32Settings.ESignerCredentialIdStringRequiredPARCEL_WINDOWS_E_SIGNER_CREDENTIAL_IDSSL.com signing credential identifier.
eSigner SandboxWin32Settings.ESignerSandboxBooleanfalsePARCEL_WINDOWS_E_SIGNER_SANDBOXUses the SSL.com sandbox service.

macOS settings

Bundle, DMG, and PKG

Setting.parcel propertyTypeDefaultEnvironment variableDescription
Create BundleMacOsSettings.CreateBundleBooleantrue for new projectsPARCEL_MACOS_CREATE_BUNDLECreates a macOS .app bundle. DMG, PKG, permissions, and associations require a bundle.
Bundle IdentifierMacOsSettings.BundleIdentifierReverse-DNS stringDerived from company and package namePARCEL_MACOS_BUNDLE_IDENTIFIERCFBundleIdentifier used for signing and distribution.
Team IDMacOsSettings.TeamId10 uppercase letters or digitsNonePARCEL_MACOS_TEAM_IDApple Developer team identifier used for signing and notarization.
App CategoryMacOsSettings.BundleCategoryApple bundle categoryOtherPARCEL_MACOS_BUNDLE_CATEGORYmacOS and App Store application category.
Application IconMacOsSettings.AppIconPath to ICNS or SVGApplication IconPARCEL_MACOS_APP_ICONOverrides the shared icon for the app bundle.
PermissionsMacOsSettings.PermissionsPermission-description dictionaryEmptyAdds macOS usage descriptions for Camera, Microphone, Location, Contacts, Calendars, Desktop, Documents, Downloads, and Network.
Resource file patternsMacOsSettings.BundleResourcePatternsList of glob patternsEmptyMoves matching files to Contents/Resources and replaces their original locations with symlinks.
Automatically Move Bundle FrameworksMacOsSettings.AutomaticallyMoveBundleFrameworksBooleanfalsePARCEL_MACOS_AUTOMATICALLY_MOVE_BUNDLE_FRAMEWORKSAdvanced compatibility option for relocating frameworks. Not shown in the GUI.
Automatically Move Bundle ResourcesMacOsSettings.AutomaticallyMoveBundleResourcesBooleanfalsePARCEL_MACOS_AUTOMATICALLY_MOVE_BUNDLE_RESOURCESAdvanced compatibility option for relocating resources. Not shown in the GUI.
DMG Background ImageMacOsSettings.DmgBackgroundPath to TIFFNonePARCEL_MACOS_DMG_BACKGROUNDBackground displayed in the DMG window.
DMG LayoutMacOsSettings.DmgLayoutLayout objectStandard Parcel layoutWindow, grid, icon, text, background color, app position, and Applications-link position settings.
DMG License FileMacOsSettings.DmgLicensePathNonePARCEL_MACOS_DMG_LICENSEFile embedded at the root of the DMG.
Install LocationMacOsSettings.InstallerLocationAbsolute path/ApplicationsPARCEL_MACOS_INSTALLER_LOCATIONPKG installation directory. This advanced field is not shown in the GUI.
Install Scripts DirectoryMacOsSettings.InstallerScriptsDirectory pathNonePARCEL_MACOS_INSTALLER_SCRIPTSDirectory containing executable preinstall and postinstall scripts. This advanced field is not shown in the GUI.
Package IdentifierMacOsSettings.InstallerIdentifierReverse-DNS stringBundle identifierPARCEL_MACOS_INSTALLER_IDENTIFIERIdentifier registered by the PKG installer. This advanced field is not shown in the GUI.

The DMG layout object supports these advanced properties:

.parcel propertyTypeDefaultDescription
MacOsSettings.DmgLayout.BackgroundColorRedNumber1Red component of the window background color.
MacOsSettings.DmgLayout.BackgroundColorGreenNumber1Green component of the window background color.
MacOsSettings.DmgLayout.BackgroundColorBlueNumber1Blue component of the window background color.
MacOsSettings.DmgLayout.GridOffsetXInteger0Horizontal grid offset.
MacOsSettings.DmgLayout.GridOffsetYInteger0Vertical grid offset.
MacOsSettings.DmgLayout.GridSpacingInteger100Spacing between grid positions.
MacOsSettings.DmgLayout.XInteger100Horizontal position of the DMG window.
MacOsSettings.DmgLayout.YInteger100Vertical position of the DMG window.
MacOsSettings.DmgLayout.WidthInteger660DMG window width.
MacOsSettings.DmgLayout.HeightInteger422DMG window height.
MacOsSettings.DmgLayout.IconSizeInteger128Icon size in pixels.
MacOsSettings.DmgLayout.TextSizeInteger12Icon-label text size.
MacOsSettings.DmgLayout.BundlePositionXInteger173Horizontal position of the app bundle.
MacOsSettings.DmgLayout.BundlePositionYInteger231Vertical position of the app bundle.
MacOsSettings.DmgLayout.ApplicationsPositionXInteger485Horizontal position of the Applications link.
MacOsSettings.DmgLayout.ApplicationsPositionYInteger231Vertical position of the Applications link.

Application signing

MacOsSettings.SigningCredentialsType accepts None, AdHoc, KeyChainIdentity, P12Certificate, or PemCertificate.

Setting.parcel propertyTypeDefaultEnvironment variableDescription
Signing CredentialsMacOsSettings.SigningCredentialsTypeCredential typeAdHocPARCEL_MACOS_SIGNING_CREDENTIALS_TYPESelects how the app bundle, code, and optionally DMG are signed.
Enable App SandboxMacOsSettings.EnableSandboxBooleanfalsePARCEL_MACOS_ENABLE_SANDBOXRuns the application in the macOS App Sandbox. The application can access only resources covered by its entitlements. Required for Mac App Store distribution.
Sign DMGMacOsSettings.SignDmgBooleantruePARCEL_MACOS_SIGN_DMGSigns the generated DMG using the application-signing credentials.
Additional signing patternsMacOsSettings.AdditionalSignPatternsList of glob patternsEmptyIncludes additional code files in bundle signing.
Signing IdentityMacOsSettings.SigningIdentityKeychain identityRequired for KeychainPARCEL_MACOS_SIGNING_IDENTITYApplication-signing identity in the macOS Keychain.
Signing P12 CertificateMacOsSettings.SigningP12CertificatePath to P12Required for P12PARCEL_MACOS_SIGNING_P12_CERTIFICATEPortable application-signing certificate and private key.
Signing PasswordMacOsSettings.SigningP12PasswordSecret stringEmptyPARCEL_MACOS_SIGNING_P12_PASSWORDPassword protecting the application P12 certificate.
Signing PEM CertificateMacOsSettings.SigningPemCertificatePath to PEMRequired for PEMPARCEL_MACOS_SIGNING_PEM_CERTIFICATEPEM application-signing certificate.
Deep SigningMacOsSettings.SignDeepBooleanfalsePARCEL_MACOS_SIGN_DEEPAdvanced compatibility option for deep signing. Not shown in the GUI.

Installer signing

A PKG installer requires a separate installer certificate. MacOsSettings.InstallerSigningCredentialsType accepts the same credential types as application signing. Ad hoc signing cannot create a signed PKG.

Setting.parcel propertyTypeDefaultEnvironment variableDescription
Installer Signing CredentialsMacOsSettings.InstallerSigningCredentialsTypeCredential typeNonePARCEL_MACOS_INSTALLER_SIGNING_CREDENTIALS_TYPESelects the certificate used to sign PKG installers.
Installer Signing IdentityMacOsSettings.InstallerSigningIdentityKeychain identityRequired for KeychainPARCEL_MACOS_INSTALLER_SIGNING_IDENTITYInstaller identity in the macOS Keychain.
Installer Signing P12 CertificateMacOsSettings.InstallerSigningP12CertificatePath to P12Required for P12PARCEL_MACOS_INSTALLER_SIGNING_P12_CERTIFICATEPortable installer certificate and private key.
Installer Signing PasswordMacOsSettings.InstallerSigningP12PasswordSecret stringEmptyPARCEL_MACOS_INSTALLER_SIGNING_P12_PASSWORDPassword protecting the installer P12 certificate.
Installer Signing PEM CertificateMacOsSettings.InstallerSigningPemCertificatePath to PEMRequired for PEMPARCEL_MACOS_INSTALLER_SIGNING_PEM_CERTIFICATEPEM installer-signing certificate.

Notarization

MacOsSettings.NotaryCredentialsType accepts None, KeyChainProfile, or AppleAccount.

Setting.parcel propertyTypeDefaultEnvironment variableDescription
Notary CredentialsMacOsSettings.NotaryCredentialsTypeCredential typeNonePARCEL_MACOS_NOTARY_CREDENTIALS_TYPESelects authentication for Apple's notary service.
Notary Keychain ProfileMacOsSettings.NotaryKeychainProfileStringRequired for Keychain profilePARCEL_MACOS_NOTARY_KEYCHAIN_PROFILEnotarytool profile stored in the macOS Keychain.
Notary Apple IDMacOsSettings.NotaryAppleIdEmail addressRequired for Apple accountPARCEL_MACOS_NOTARY_APPLE_IDApple ID used for notarization.
Notary App PasswordMacOsSettings.NotaryAppPasswordSecret stringRequired for Apple accountPARCEL_MACOS_NOTARY_APP_PASSWORDApp-specific password used by the notary service.

Linux settings

Setting.parcel propertyType or valuesDefaultEnvironment variableDescription
Install Directory NameLinuxSettings.InstallDirNameLowercase package-directory nameapp-{package-name}PARCEL_LINUX_INSTALL_DIR_NAMEDirectory created under /usr/share. It must start and end with a letter or number. Maximum 100 characters.
Application IconLinuxSettings.AppIconPath to PNG or SVGApplication IconPARCEL_LINUX_APP_ICONOverrides the shared icon for DEB and RPM packages.
MaintainerLinuxSettings.MaintainerStringCompany, then package namePARCEL_LINUX_MAINTAINERPackage maintainer, preferably in Name <[email protected]> format. Maximum 255 characters.
CopyrightLinuxSettings.CopyrightFilePathNonePARCEL_LINUX_COPYRIGHT_FILECopyright file included in DEB and RPM metadata.
Desktop CategoryLinuxSettings.DesktopCategoryLinux desktop categoryApplicationPARCEL_LINUX_DESKTOP_CATEGORYCategory used in desktop menus and mapped to package-manager metadata.
Create /usr/bin/ symlinkLinuxSettings.CreateBinSymlinkBooleantruePARCEL_LINUX_CREATE_BIN_SYMLINKCreates a command-line symlink to the application executable.
Additional DEB DependenciesLinuxSettings.AdditionalDebDependenciesListEmptyAdds Debian package dependencies. Separate alternatives with a vertical bar.
Additional RPM DependenciesLinuxSettings.AdditionalRpmDependenciesListEmptyAdds RPM package names or capabilities.

You can use the main freedesktop categories and common additional categories, e.g., Development, Education, Game, Graphics, Network, Office, Science, Settings, System, Utility, WebBrowser, TextEditor, TerminalEmulator.

See also