If you want to submit a software package to the Windows Package Manager community repository, start by creating a package manifest. The manifest is a YAML file that describes the app to install.
You can use the Windows Package Manager manifest builder, the YAMLCreate PowerShell script, or you can create a manifest manually by following the instructions below.
Options for
creating manifests
using the
WinGetCreate
utility You can install the wingetcreate utility
using the following command
. winget install wingetcreate
After installation, you can run wingetcreate new to create a new package and populate the prompts. The last option for WinGetCreate messages is to send the manifest to the package repository. If you choose yes, it will automatically send your pull request (PR) to the Windows Package Manager community repository.
Using
YAMLCreate.ps1
To help create manifest files, we have provided a YAMLCreate.ps1 PowerShell script located in the Tools folder of the Windows Package Manager community repository. You can use the script by cloning the repository on your PC and running the script directly from the Tools folder. The script will ask you for the installer URL, and then ask you to fill in the metadata. Similar to using WinGetCreate, this script will offer the option to send the manifest automatically.
YAML
Basics
The YAML format was chosen for package manifests because of its relative ease of human readability and consistency with other Microsoft development tools. If you’re not familiar with YAML syntax, you can learn the basics in Learn YAML in Y minutes.
Conventions
These conventions are used in this article
: To the left of : is
- a literal keyword used in manifest definitions. To the
- right of : is a data type. The data type can be a primitive type such as string or a reference to a rich structure defined elsewhere in this article.
- The notation [ datatype ] indicates an array of the mentioned data type. For example, [ string ] is an array of strings.
- The notation { datatype : datatype } indicates a mapping of one data type to another. For example, { string: string } is a string-to-string mapping.
Contents
of the manifest
A package manifest consists of required elements and optional elements that can help improve the customer experience when installing software. This section provides a brief summary of the required manifest schema and complete manifest schemas with examples of each.
Each field in the manifest file must be Pascal case and cannot be duplicated.
For a complete list and descriptions of the elements in a manifest, see the manifest specification in the Windows Package Manager community repository.
Minimum
schema required
As specified in the singleton JSON schema, only certain fields are required. The minimum supported YAML file would look like the example below. The singleton format is only valid for packages that contain a single installer and a single locale. If more than one installer or locale is provided, the multiple schema and YAML file format must be used.
The partitioning scheme was added to help with the GitHub user experience. Folders with thousands of children do not render well in the browser.
Multiple manifest files
To provide the best user experience, manifests should contain as much metadata as possible. To separate concerns about validating installers and providing localized metadata, manifests should be split into multiple files. The minimum number of YAML files for this manifest type is three. Additional locales must also be provided.
A version file. The default locale file
- .
- An installer file
- Additional locale files
.
. The following example shows many optional metadata fields and multiple locales.
Note that the default locale has more requirements than additional locales. In the show command, required fields that are not provided for additional locales will display fields from the default locale.
Installation switches
You can often find out which silent switches are available to an installer by passing a -? to the installer from the command line. Here are some common silent switches that can be used for different types of installer.
MSI /q installer command documentation MSI InstallShield /s command-line options InstallShield command-line parameters Inno Setup /SILENT or /VERYSILENT Inno Setup Nullsoft /s Nullsoft Silent Documentation
Installers/Uninstallers Tips and best practices
- The package identifier must be unique. You cannot have multiple shipments with the same package ID. Only one pull request is allowed per package version.
- Avoid creating multiple editor folders. For example, do not create “Contoso Ltd.” if there is already a “Contoso” folder.
- All tools must support silent installation. If you have an executable file that does not support a silent installation, we cannot provide that tool at this time.
- Provide as many fields as possible. The more metadata you provide, the better the user experience. In some cases, the fields may not yet be supported by the Windows Package Manager client (winget.exe). For example, the AppMoniker field is optional. However, if you include this field, clients will see results associated with the Moniker value when they run the search command (for example, vscode for Visual Studio Code). If there is only one application with the specified Moniker value, clients can install the application by specifying the moniker instead of the full package ID.
- The length of strings in this specification must be limited to 100 characters before a line break.
- PackageName must match the entry made in Add or Remove Programs to help correlate with manifests to support export and update.
- The publisher must match the entry made in Add or Remove Programs to help correlate with manifests to support export and update.
- Package installers in MSI format use product codes to uniquely identify applications. The product code for a particular version of a package should be included in the manifest to help ensure the best upgrade experience.
- Limit the length of manifest strings to 100 characters before a line break.
- When more than one type of installer exists for the specified version of the package, an instance of InstallerType can be placed below each of the installers.
Frequently asked questions
about the manifesto
What is a manifesto? Manifests
are YAML files that contain metadata used by Windows Package Manager to install and update software on the Windows operating system. There are thousands of these files partitioned in the manifest directory in the winget-pkgs repository on GitHub. The directory structure of Windows Package Manager had to be partitioned so that you didn’t have to scroll around the site as much when looking for a manifest.
What is a package?
Think of a package as an application or a software program. The Windows Package Manager uses a “PackageIdentifier” to represent a single package. These are usually in the form of Publisher.Package. Sometimes you may see additional values separated by a second period.
What is a version?
Package versions are associated with a specific version. In some cases, you will see perfectly formed semantic version numbers and in other cases you may see something different. These can be controlled by date or they can have other characters with some specific meaning of the package. The YAML key for a package version is “PackageVersion”.
For more information about understanding directory structure and creating the first manifest, see Create manifests in the winget-pkgs repository on GitHub.