Share via

DISM App Package (.appx or .appxbundle) Servicing Command-Line Options

  • Article

You can use app package servicing commands to add, remove, and list provisioned app packages (.appx or .appxbundle) in a Windows image. An .appxbundle is a collection of app and resource packages used together to enrich the app experience, while minimizing the disk footprint on a given PC. For detailed information about .appxbundle packages and the Microsoft Store pipeline, see App packaging. Only a subset of the packages within an .appxbundle might be added to the image when a bundle is provisioned using DISM. For more information, see Understanding How DISM Adds .appxbundle Resource Packages to an Image.

Provisioned app packages are added to a Windows image and then installed for every new or existing user profile the next time the user logs on. For more information, including requirements for app package provisioning, see Sideload Apps with DISM.

You can also use PowerShell to add, remove, and list app packages (.appx or .appxbundle) per image or per user in a Windows installation. For more information, see Deployment Imaging Servicing Management (DISM) Cmdlets in Windows PowerShell and App Installation Cmdlets in Windows PowerShell.

DISM servicing syntax

The base syntax for servicing a Windows image using DISM is:

DISM.exe {/Image:<path_to_image_directory>|/Online} [dism_global_options] {servicing_option} <servicing_argument>]

Options for offline images

The following app package (.appx or .appxbundle) servicing options are available for an offline image.

DISM.exe /Image:<path_to_image_directory> [/Get-ProvisionedAppxPackages | /Add-ProvisionedAppxPackage | /Remove-ProvisionedAppxPackage | /Set-ProvisionedAppxDataFile | /StubPackageOption]

Options for online images

The following app package (.appx or .appxbundle) servicing options are available for a running operating system.

DISM.exe /Online [/Get-ProvisionedAppxPackages | /Add-ProvisionedAppxPackage | /Remove-ProvisionedAppxPackage | /Set-ProvisionedAppxDataFile | /StubPackageOption]

/Get-Help /?

When used immediately after an app package servicing command-line option, information about the option and the arguments is displayed. Additional topics might become available when an image is specified.

Dism /image:C:\test\offline /Add-ProvisionedAppxPackage /?

Dism /online /Get-ProvisionedAppxPackages /?

/Get-ProvisionedAppxPackages

Displays information about app packages (.appx or .appxbundle), in an image, that are set to install for each new user.

Dism /Image:C:\test\offline /Get-ProvisionedAppxPackages

/Add-ProvisionedAppxPackage

Adds one or more app packages to the image.

The app will be added to the Windows image and registered for each existing or new user profile the next time the user logs in. If the app is added to an online image, the app will not be registered for the current user until the next time the user logs in.

Provision apps on an online operating system in Audit mode so that appropriate hard links can be created for apps that contain the exact same files (to minimize disk space usage) while also ensuring no apps are running for a successful installation.

Syntax:

dism.exe /Add-ProvisionedAppxPackage {/FolderPath:<App_folder_path> [/SkipLicense\] [/CustomDataPath:<custom_file_path>]  /PackagePath:<main_package_path> [/DependencyPackagePath:<dependency_package_path>] {[/LicensePath:<license_file_path>] [/SkipLicense\]} [/CustomDataPath:<custom_file_path>]} [/Region:<region>]

  • Use /FolderPath to specify a folder of unpacked app files containing a main package, any dependency packages, and the license file. This is only supported for an unpacked app package.

  • Use /PackagePath to specify an app package (.appx or .appxbundle). You can use /PackagePath when provisioning a line-of-business app online.

    Important

    Use the /PackagePath parameter to provision .appxbundle packages. Also, dependency packages cannot be provisioned with /PackagePath, they must be provisioned with the /DependencyPackagePath parameter for an app.

  • /PackagePath is not supported from a host PC that is running Windows Preinstallation Environment (WinPE) 4.0, Windows Server 2008 R2, or an earlier version of Windows.

  • Use /Region to specify what regions an app package (.appx or .appxbundle) must be provisioned in. The region argument can either be:

    • all, indicating that the app should be provisioned for all regions, or
    • A semi-colon delimited list of regions. The regions will be in the form of ISO 3166-1 Alpha-2 or ISO 3166-1 Alpha-3 codes. For example, the United States can be specified as either "US" or "USA" (case-insensitive). When a list of regions is not specified, the package will be provisioned only if it is pinned to start layout.

  • Use /DependencyPackagePath to specify each depencency package needed for the app to be provisioned. The necessary dependency packages of an app can be found by looking at the <PackageDependency> elements in the AppxManifest.xml in the root of the .appx package of the app. If multiple apps all share the same dependency, the latest minor version of each major version of the dependency package should be installed. For example, App1, App2, and App3 all have a dependency on Microsoft.NET.Native.Framework. App1 specifies Microsoft.NET.Native.Framework.1.6 with minor version 25512.0, App2 specifies Microsoft.NET.Native.Framework.1.6 with minor version 25513.0, and App3 specifies Microsoft.NET.Native.Framework.1.3 with minor version 24202.0. Because both App1 and App2 both specify the same major version of the dependency package, only the latest minor version 25513.0 should be installed, while App3 specifies a different major version of the dependency package, so it must also be installed. So the dependency packages that should be installed are Microsoft.NET.Native.Framework.1.6 with minor version 25513.0 and Microsoft.NET.Native.Framework.1.3 with minor version 24202.0.

    If the package has dependencies that are architecture-specific, you must install all of the applicable architectures for the dependency on the target image. For example, on an x64 target image, include a path to both the x86 and x64 dependency packages or include them both in the folder of unpacked app files. If the Arm dependency package is also specified or included, DISM will ignore it since it does not apply to the target x64 image.

    Computer ArchitectureDependencies to install:
    x64x64 and x86
    x86x86
    ArmArm only

  • Use /CustomDataPath to specify an optional custom data file for an app. You can specify any file name. The file will be renamed to Custom.dat when it is added to the image.

  • Use /LicensePath with the /PackagePath option to specify the location of the .xml file containing your application license.

  • Only use /SkipLicense with apps that do not require a license on a sideloading-enabled computer. Using /SkipLicense in other scenarios can compromise an image.

Examples:

Dism /Image:C:\test\offline /Add-ProvisionedAppxPackage /FolderPath:c:\Test\Apps\MyUnpackedApp /CustomDataPath:c:\Test\Apps\CustomData.xml

Dism /Online /Add-ProvisionedAppxPackage /PackagePath:C:\Test\Apps\MyPackedApp\MainPackage.appx /DependencyPackagePath:C:\Test\Apps\MyPackedApp\Framework-x86.appx /DependencyPackagePath:C:\Test\Apps\MyPackedApp\Framework-x64.appx /LicensePath:C:\Test\Apps\MyLicense.xml

Dism /Online /Add-ProvisionedAppxPackage /FolderPath:C:\Test\Apps\MyUnpackedApp /SkipLicense

Dism /Image:C:\test\offline /Add-ProvisionedAppxPackage /PackagePath:C:\Test\Apps\MyPackedApp\MainPackage.appxbundle /SkipLicense

Dism /Online /Add-ProvisionedAppxPackage /PackagePath:C:\Test\Apps\MyPackedApp\MainPackage.appxbundle /Region:"all"

Dism /Online /Add-ProvisionedAppxPackage /PackagePath:C:\Test\Apps\MyPackedApp\MainPackage.appxbundle /Region:"US;GB"

/Remove-ProvisionedAppxPackage

Removes provisioning for app packages (.appx or .appxbundle) from the image. App packages will not be registered to new user accounts that are created.

Syntax:

/Remove-ProvisionedAppxPackage /PackageName:<PackageName>

Important

This option will only remove the provisioning for a package if it is registered to any user profile. Use the Remove-AppxPackage cmdlet in PowerShell to remove the app for each user that it is already registered to in order to fully remove the app from the image. If the app has not been registered to any user profile, the /Remove-ProvisionedAppxPackage option will remove the package completely. To remove app packages from a Windows Server 2012, or later, image that has the Desktop Experience installed, you must remove the app packages before you remove the Desktop Experience. The Desktop Experience is a requirement of the /Remove-ProvisionedAppxPackage option for Server Core installations of Windows Server.

Example:

Dism /Image:C:\test\offline /Remove-ProvisionedAppxPackage /PackageName:microsoft.devx.appx.app1_1.0.0.0_neutral_ac4zc6fex2zjp

/Optimize-ProvisionedAppxPackages

Optimizes the total file size of provisioned packages on the image by replacing identical files with hardlinks. Once an image with provisioned AppX packages is online, /optimize-provisionedappxpackages won't be able to optimize provisioned AppX packages. If you take an image offline and add packages, only the packages that are provisioned after the image was brought back offline will be optimized.

This command is not supported against an online image.

DISM.exe /Image:C:\test\offline /Optimize-ProvisionedAppxPackages

/Set-ProvisionedAppxDataFile

Adds a custom data file into the specified app package (.appx or .appxbundle).

Syntax

/Set-ProvisionedAppxDataFile [/CustomDataPath<custom_file_path>] /PackageName<PackageName>

The specified app (.appx or .appxbundle) package must already be added to the image prior to when you add the custom data file with this option. You can also add a custom data file when you use the /Add-ProvisionedAppxPackage option.

  • Use /CustomDataPath to specify an optional custom data file for an app. You can specify any file name. The file will be renamed to Custom.dat when it is added to the image. If a Custom.dat file already exists, it will be overwritten.

  • Use /PackageName to specify an app package (.appx or .appxbundle).

Example:

DISM.exe /Image:C:\test\offline /Set-ProvisionedAppxDataFile /CustomDataPath:c:\Test\Apps\Custom.dat /PackageName:microsoft.appx.app1_1.0.0.0_neutral_ac4zc6fex2zjp

/StubPackageOption

Used in conjunction with app package servicing options to specify the stub preference of the package.

Syntax:

/StubPackageOption:{installstub | installfull}
  • InstallStub sets the provision package to the stub version. Implicitly sets the stub preference to stub.
  • InstallFull sets the provision package to the provision the full version. Implicitly sets the stub preference to full.

If no stub package option is specified than the provisioned package version is set to the predefined stub preferences.

Example:

Dism /image:C:\test\offline /add-provisionedappxpackage /packagepath:"C:\dism\stub\appwithresources.appxbundle" /stubpackageoption:installstub

Understanding How DISM Adds .appxbundle Resource Packages to an Image

When an .appxbundle is added to the image, not all resource packages within the bundle are applicable. For example, if an app is being added to a Windows image with a Spanish (Spain) default language, French (France) resources should not be included. To determine what resources are added to the image, the package applicability is determined using:

  • Language Resource Packs: If an operating system language is not present, the corresponding app language resource pack is not added. For example, you might have an image that is a Windows 10 with English (US) as the default language, and a Spanish (Spain) language pack included. English (US) and Spanish (Spain) app resource packs will be added to the image. If a French (France) resource pack (or any other language) is available in the app bundle, it will not be added.

  • Scale and DirectX (DXFL) Resource Packs: Scale and DirectX (DXFL) resource packs depend upon the hardware configuration of the Windows device. Because the type of target hardware can’t be known at the time the DISM commands are run, all scale and DXFL resource packages are added to the image at provisioning time. For more information about developing an app with scaling resources, see Guidelines for scaling to pixel density (Microsoft Store apps).

For an image containing multiple language packs, app resource packages will be added to the image for each language. Once the first user has signed in to the PC with the deployed image and the user has chosen a language during OOBE, the inapplicable resource packages, (language resource packs, scale resource packs and DXFL resource packages) that do not match the user profile settings are removed.

For example, an app might support English (US), French (France), and Spanish (Spain) languages. If the app is added to an image with English (US) and Spanish (Spain) language packs present, only English (US) and Spanish (Spain) resource packs will be added these to the image. Then, if a user signs in for the first time and, during OOBE, selects English (US) as their operating system language, the Spanish (Spain) resource packages will be removed after sign in completes.

Important

If you add or remove a language pack from an image, you change the applicability context which may result in leaving an incorrect or incomplete set of resource packages in the image. When a language pack is added or removed, you must, once again, add all .appxbundle packages (including any dependency packages and Microsoft Store license file) to the image. This will ensure that the correct set of resource packages is provisioned.

Limitations

  • You cannot install an app package (.appx) on an operating system that does not support Windows 8 apps. You can’t install an app bundle package (.appxbundle) on an operating system that does not support at least Windows 8.1 apps. Apps aren't supported on WinPE 4.0, the Windows Server 2012 Server Core installation option, or on any versions of Windows older than Windows 8 and Windows Server 2012.

    To install and run apps on Windows Server 2012, you must install the Desktop Experience.

  • The /FolderPath option is only supported for app packages based on the .appx format.

  • /PackagePath must always be used for .appxbundle packages.

What is DISM?

DISM Image Management Command-Line Options

Deployment Image Servicing and Management (DISM) Command-Line Options

Sideload Apps with DISM