Tell us about your PDF experience.

Set up your development environment

on Windows
Article • 09/28/2023

Windows invites you to code as you are. Use whatever coding language or framework
you prefer - whether developing with tools on Windows or with Linux tools on the
Windows Subsystem for Linux, this guide will help you get set up and install what you
need to start coding, debugging, and accessing services to put your work into
production.

Developer tools

Dev Home
Monitor your work in the centralized dashboard, GitHub and System performance
widgets. Get setup and onboard new projects with the Machine configuration tool.
Install Dev Home
Dev Drive
Improve performance by storing project files on a Dev Drive and keep files secure with
trust designation, antivirus configuration, and attached filters.
Create a Dev Drive

WinGet Configuration
Consolidate manual machine setup and project onboarding to a single command that is
reliable and repeatable.
Author a configuration file
Windows Subsystem for Linux
Use your favorite Linux distribution fully integrated with Windows (no more need for
dual-boot).
Install WSL

Windows Terminal
Customize your terminal environment to work with multiple command line shells.
Install Terminal
Windows Package Manager
Use the winget.exe client, a comprehensive package manager, with your command line
to install applications on Windows.
Install Windows Package Manager

Microsoft PowerToys
Tune and streamline your Windows experience for greater productivity with this set of
power user utilities.
Install PowerToys
Windows Subsystem for Android
Windows Subsystem for Android™️support ends March 5, 2025.
Learn more

Sudo for Windows

Sudo for Windows is a new way for users to run elevated commands directly from an
unelevated console session.
Enable and configure Sudo for Windows
Windows AI
A new era of AI has arrived at Microsoft. See how AI is being integrated in Windows 11.
Explore Windows AI

https://learn-video.azurefd.net/vod/player?id=54e6c532-a86c-4a39-81ab-
40e28ce2ba96&locale=en-us&embedUrl=%2Fwindows%2Fdev-environment%2F

Windows Copilot
The first PC platform to provide centralized AI assistance and designed to help people
easily take action and get things done is coming soon! See the Blog announcement .

Sign up to receive updates

https://learn-video.azurefd.net/vod/player?id=72ad293b-b7aa-4a78-9111-
46eb0e072d7b&locale=en-us&embedUrl=%2Fwindows%2Fdev-environment%2F

Development paths
Get started with JavaScript
Get started with JavaScript by setting up your development environment on Windows or
Windows Subsystem for Linux and install Node.js, React, Vue, Express, Gatsby, Next.js, or
Nuxt.js.

Get started with Python

Install Python and get your development environment setup on Windows or Windows
Subsystem for Linux.

Get started with Android

Install Android Studio, or choose a cross-platform solution like .NET MAUI, React, or
creating a PWA, and get your development environment setup on Windows.
Get started building Windows apps
Get started building desktop apps for Windows using the Windows App SDK, UWP,
Win32, WPF, Windows Forms, or updating and deploying existing desktop apps with
MSIX and XAML Islands.

Get started with C++ and C

Get started with C++, C, and assembly to develop apps, services, and tools.

Get started with C#

Get started building apps using C# and .NET.
Get started with F#
Get started building apps using F# and .NET.

Get started with Rust

Get started programming with Rust—including how to set up Rust for Windows by
consuming the windows crate.

Get started with PowerShell

Get started with cross-platform task automation and configuration management using
PowerShell, a command-line shell and scripting language.
Get started with Docker Desktop for Windows
Create remote development containers with support from Visual Studio, VS Code, .NET,
Windows Subsystem for Linux, or a variety of Azure services.

Get started with Blazor

Get started with Blazor, a client-side UI framework within ASP.NET Core. Use HTML, CSS,
and C# (rather than JavaScript) to create UI components and single page applications
for the web.

More for developers

VS Code
A lightweight source code editor with built-in support for JavaScript, TypeScript, Node.js,
a rich ecosystem of extensions (C++, C#, Java, Python, PHP, Go) and runtimes (such as
.NET and Unity).
Install VS Code

Visual Studio
An integrated development environment that you can use to edit, debug, build code,
and publish apps, including compilers, intellisense code completion, and many more
features.
Install Visual Studio
Azure
A complete cloud platform to host your existing apps and streamline new development.
Azure services integrate everything you need to develop, test, deploy, and manage your
apps.
Set up an Azure account

.NET
An open source development platform with tools and libraries for building any type of
app, including web, mobile, desktop, gaming, IoT, cloud, and microservices.
Install .NET

Run Windows and Linux

Windows Subsystem for Linux (WSL) allows developers to run a Linux operating system
right alongside Windows. Both share the same hard drive (and can access each other’s
files), the clipboard supports copy-and-paste between the two naturally, there's no need
for dual-booting. WSL enables you to use BASH and will provide the kind of
environment most familiar to Mac users.

Learn more in the WSL docs.

https://learn.microsoft.com/shows/One-Dev-Minute/What-can-I-do-with-WSL--One-
Dev-Question/player?format=ny

You can also use Windows Terminal to open all of your favorite command line tools in
the same window with multiple tabs, or in multiple panes, whether that's PowerShell,
Windows Command Prompt, Ubuntu, Debian, Azure CLI, Oh-my-Zsh, Git Bash, or all of
the above.

Learn more in the Windows Terminal docs.

https://learn.microsoft.com/shows/One-Dev-Minute/What-are-the-main-features-of-
the-new-Terminal--One-Dev-Question/player?format=ny

Transitioning between Mac and Windows

Check out our guide to transitioning between a Mac and Windows (or Windows
Subsystem for Linux) development environment. It can help you map the difference
between:

Keyboard shortcuts
Trackpad shortcuts
Terminal and shell tools
Apps and utilities

Game development documentation

Microsoft's Game Dev documentation
６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
What is Dev Home?
Article • 05/10/2024

Dev Home is a new control center for Windows providing the ability to monitor projects
in your dashboard using customizable widgets, set up your dev environment by
downloading apps, packages, or repositories, connect to your developer accounts and
tools (such as GitHub), and create a Dev Drive for storage all in one place.

Use the centralized dashboard with customizable widgets to monitor workflows,

track your dev projects, coding tasks, Azure DevOps queries, GitHub issues, pull
requests, available SSH connections, and system CPU, GPU, Memory, and Network
performance.
Use the Machine configuration tool to set up your development environment on a
new device or onboard a new dev project.
Use Dev Home extensions to set up widgets that display developer-specific
information. Create and share your own custom-built extensions.
Create a Dev Drive to store your project files and Git repositories.

Install Dev Home (Preview)

To update Dev Home to the latest version, run the following command in Windows
Terminal: winget upgrade Microsoft.DevHome
Dev Home Machine configuration
To set up a new machine or onboard a new project with Dev Home, select Machine
configuration. Dev Home can manage everything you need to get to your machine's
development environment to a ready-to-code state, whether you want an end-to-end
setup process, want to use a WinGet Configuration file, or just want to perform a quick
step, like cloning a Git repository, installing a specific application, or adding a Dev Drive
to improve the performance of your project's storage volume.

Learn more about how to get started with the Dev Home Machine configuration tool.

Dev Home dashboard widgets

Monitor your workflows using customizable widgets on the Dev Home dashboard. By
default, Dev Home provides widgets for:

GPU: Monitor the performance of your machine's GPU.

SSH keychain: Lists the SSH connections available in your ssh/.config file. Select
one of these SSH items to open that connection in Windows Terminal.
Memory: Monitor the performance of your machine's memory.
Network: Monitor the performance of your machine's network.
CPU: Monitor the performance of your machine's CPU.
 GitHub: The Dev Home GitHub extension can be connected to your GitHub
credentials to provide both customizable widgets and notifications.
Azure DevOps: The Dev Home Azure extension can be connected to your Azure
account to provide customizable widgets for queries and pull requests.

System widgets
The Dev Home system widgets can provide real-time information on:

Memory: Amount in use, total available, total committed, total cached, paged
pool, non-paged pool.
Network: Bandwidth measurements, including total kilobits per second for both
sending and receiving data, along with the network name.
CPU: Total utilization, speed, and active processes.
GPU: Total utilization, temperature, and graphics chip name.
GitHub extension widgets
The Dev Home GitHub extension enables you to connect your GitHub account to Dev
Home and create customized widgets that integrate with your GitHub repositories. To
connect your GitHub account to Dev Home and begin creating GitHub widgets:

1. Once you've installed Dev Home, the GitHub extension will be available by default,
but you will need to log-in to your GitHub account to gain access to the integrated
features. Currently Dev Home supports only a single GitHub account. (See the
DevHome Extension repo on GitHub for updates on adding support for multiple
accounts.)

2. Select Add a widget from the top-right of your Dev Home dashboard. A list of
widget options will appear that you can pin and then customize to your
preference.

Learn more about the Dev Home GitHub extension and how to create customized
widgets and set up Windows notifications.

Dev Home Extensions

Dev Home Extensions power the functionality of Dev Home's customizable widgets. By
default, Dev Home includes the GitHub extension, but you can also create and share
your own custom-built extensions.

Learn more about Dev Home extensions, including how to create customized GitHub
widgets, set up GitHub notifications, create custom ADO widgets, or build and share
your own Dev Home extensions.

Dev Home Azure extension

The Dev Home Azure extension provides integration with Azure DevOps directly into
Dev Home and provides customizable widgets to allow you to display your queries and
pull requests. To connect your Azure account to Dev Home and begin creating Azure
Developer Operations (ADO) widgets:

1. Install the Dev Home Azure extension from the Microsoft Store.​Once installed, if
your machine is connected to a work account already, Dev Home will connect
automatically. Otherwise, you can sign into your Azure account in Dev Home's
account settings.

2. Select Add a widget from the top-right of your Dev Home dashboard. A list of
widget options will appear that you can pin and then customize to your liking.

Dev Home Environments

Dev Home Environments can help you to centralize your interactions with virtual or
cloud environments in a single place. Quickly launch, start, stop, or sync virtual
environments, seamlessly integrating with the Windows OS. Learn more about Dev
Home Environments.
Dev Home open source repos
Both Dev Home and Dev Home GitHub extension are open source and welcome your
contributions.

Dev Home repository on GitHub .

Dev Home GitHub extension repository on GitHub
Dev Home Azure extension repository on GitHub

You can also contribute to the open source documentation for Dev Home by visiting the
Windows Dev Docs open source repo on GitHub .

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Dev Home Machine Configuration - Set
up your Windows development
environment
Article • 05/10/2024

The Dev Home machine configuration tool brings all of your dev environment set up
tasks into one place, enabling you to efficiently set up a new machine or onboard new
projects.

Avoid all of the fractured and tedious processes typically involved in getting your
machine ready for development. Dev Home streamlines the process of searching for
project requirements, cloning repositories, and finding specific versions of software and
tools to install. Manage multiple tool sign-ins, minimize context switching, and reach
productivity faster so you can focus on what you do best - developing.

Machine configuration
Dev Home Machine configuration can manage everything you need to get to your
machine's development environment to a ready-to-code state.
When you select Machine configuration, Dev Home will provide multiple set up
options:

Set up a local machine: Install applications, clone repositories, and add all of the
requirements for a new development project using the built-in graphical
configuration interface to enable unattended setup of your environment. The step-
by-step tool will walk you through everything you need, including suggestions for
popular dev tools or known repositories. At the end of the process you can
generate a WinGet Configuration file to make it easy to apply these same steps to
any machine. Once you've made all of your choices, sit back and let Dev Home
handle the rest. If you've cloned any repositories that contain a WinGet
Configuration file, Dev Home will detect that and let you continue to complete
your set up.

Set up an environment: Experimental Feature. Target an existing environment to

configure by selecting applications to install and public repositories to clone in
your specified development environment. From Hyper-V to Microsoft Dev Box
support, Dev Home makes it easy to set up any other environment as easily as you
can your local machine.

Run a configuration file for an existing setup: Use a WinGet Configuration file to
consolidate all of your machine setup and project onboarding tasks into a single
file, making the process of setting up your development environment reliable and
repeatable. WinGet Configuration files use a YAML format with a JSON schema
applying Windows Package Manager and PowerShell Desired State Configuration
(DSC) Resource modules to handle every aspect of your machine set up. Remove
any worry over finding the right software version, packages, tools, frameworks, and
settings when onboarding to a new team or project. In this experience you can
switch between a summary view or check out the raw contents of the YAML file. Be
sure to check the trustworthiness of a WinGet Configuration file before running it.

Create environment: Experimental Feature. Create a new local or cloud

environment for development. Once created you can launch it from the
environments page, or select it for configuration.

Clone repositories: Once you have connected your credentials using the Dev
Home GitHub extension or the Dev Home Azure extension, you can use Dev Home
to clone repositories on to your machine.

Install applications: Use Dev Home to discover and install software applications --
one at a time or have Dev Home install several while you take a snack break.
 Add a Dev Drive: To add a storage volume that utilizes ReFS and optimized
security settings to be more performant for development-focused scenarios,
consider adding Dev Drive. You must currently be running a Windows Insider
Program Build on the Dev Channel in order to use Dev Drive. Learn more in the
Dev Drive docs.

Clone a repo and store it on a Dev Drive

When using Dev Home to clone a repository, once you have selected a repo (or multiple
repos), you can select which storage drive to clone them to. If you have already set up a
Dev Drive, it will be used as the default path when cloning a repository.

If you have not yet created a Dev Drive, you will have the option to create one using Dev
Home. Check the box to optimize the performance of your workloads with a Dev Drive.
Then you can customize a few options, such as the drive letter, name, size, and location
of the dynamic VHDX on which the Dev Drive will be created. The name will be used for
both the VHDX file and the Dev Drive. By default, the options are the next available drive
letter, size of 50GB, and created at %userprofile%\DevDrives .

Learn more about what you can do with Dev Home.

６ Collaborate with us on Windows developer

feedback
GitHub Windows developer is an open
source project. Select a link to
The source for this content can provide feedback:
be found on GitHub, where you
can also create and review  Open a documentation issue
issues and pull requests. For
more information, see our  Provide product feedback
contributor guide.
Dev Home extensions
Article • 02/20/2024

Dev Home supports both default and custom-built extensions. Learn more about the
Dev Home GitHub extension, how to customize Git widgets and notifications in the Dev
Home dashboard, and how to build your own Dev Home extension.

The GitHub extension is currently the only extension included with Dev Home by
default, however new extensions are in active development.

Dev Home GitHub extension

The Dev Home GitHub extension provides GitHub integration into the existing features
of Dev Home. These features include the ability to recommend repositories to add when
using the Machine Configuration and the ability to add Dev Home widgets customized
to display your GitHub content.

To add the GitHub extension, select the Extensions tab in Dev Home, then select Get on
the GitHub extension from the list of Dev Home extensions Available in the Microsoft
Store.

When signing into GitHub using the Dev Home GitHub Extension, your GitHub
credentials are added to the Credential Manager . This is how Dev Home is able to
access information relevant to your GitHub account. Currently DevHome supports only a
single GitHub account. (See the DevHome Extension repo on GitHub for updates on
adding support for multiple accounts.)

Want to contribute to or file an issue on this extension? See the open source GitHub
extension repository for Dev Home .

Dev Home widgets customized using the GitHub

extension
The Dev Home GitHub extension powers widgets that can be customized and display on
the Dev Home dashboard. These widgets can display:

Issues associated with a specific GitHub repo

Pull Requests (PRs) associated with a specific GitHub repo
Only issues that are assigned to you in a specific GitHub repo
Only issues or pull requests that you’ve been mentioned in
PRs that have a request for your review

Notifications using the Dev Home GitHub extension

The Dev Home GitHub extension has the ability to send Windows notifications based on
GitHub events. As of now, the only supported notification event is when checks fail on a
pull request that has been authored by the account that’s signed into the extension.
Notifications can be disabled from the Windows notification settings .
Dev Home Azure extension
The Dev Home Azure extension provides Azure DevOps (ADO) integration into Dev
Home's dashboard and machine configuration tool. The extension provides
recommended repositories to clone and also adds ADO widgets for queries and pull
requests.

To add the Azure extension, select the Extensions tab in Dev Home, then select Get on
the Azure extension from the list of Dev Home extensions Available in the Microsoft
Store.

If you're logged into Windows with an Azure work account, the extension will
automatically detect your account after installation.

Want to contribute to or file an issue on this extension? See the open source Azure
extension repository for Dev Home .

Customize Azure extension widgets in Dev Home

The Dev Home Azure extension provides customizable widgets for the Dev Home
dashboard. These widgets display:

Query results
Query tiles with counts of items per query
Pull requests for a specific ADO repo that are created by you, assigned to you, or
assigned to your team

Build your own custom Dev Home extension

If you are interested in building your own extension to use with Dev Home, visit the Dev
Home repo on GitHub to find documentation on how to get started.

６ Collaborate with us on
GitHub
The source for this content can
be found on GitHub, where you
can also create and review
issues and pull requests. For
more information, see our
contributor guide.
Windows developer
feedback
Windows developer is an open
source project. Select a link to
provide feedback:

 Open a documentation issue

 Provide product feedback

Dev Home Environments
Article • 05/10/2024

A virtual environment is a self-contained workspace that allows you to maintain

separate dependencies and settings for different projects, effectively isolating them
from each other. The type of virtual environments supported currently include:

Local Hyper-V virtual machine (VM)

Microsoft Dev Box

Dev Home Environments can help you to centralize your interactions with these virtual
or cloud environments in a single place.

Create and configure virtual environments associated with GitHub repositories,

apps, and packages.
Perform quick actions such as launch, snapshot, start, stop, or pinning
environments to Windows Start menu or taskbar.

Get started with Environments in Dev Home

1. Ensure that you have the latest version of Dev Home by running the command:
winget upgrade Microsoft.DevHome .

2. Enable the Environments features in the Dev Home Experimental settings (Settings
> Experimental features > toggle to On).
3. Each type of virtual environment in Dev Home is supported by a Dev Home
extension. To add a new environment, you must first ensure that the supporting
extension is installed.

Hyper-V extension: Installed by default in Dev Home. By default, your local

Hyper-V VMs will be visible on the Dev Home Environments page.
Microsoft Dev Box: To display Dev Box virtual environments, install the Dev
Home Azure extension. Once installed, each Dev Box that you have set up on
your Azure account will be visible on the Dev Home Environments page.
Manage your Dev Home Environments
Each virtual environment that has been installed in Dev Home can display some key
information:

1. The type of virtual environment (such as Hyper-V VM, Microsoft Dev Box, more
coming soon).

2. The name of the virtual environment instance (whatever name you have chosen for
the environment).

3. Status of the virtual environment: started, stopped, running.

4. Environment specific information, such as the project name for a Microsoft Dev
Box, the vCPU usage, the RAM usage, the storage capacity, the uptime, or
checkpoints.

Each virtual environment offers the following quick actions:

 1. Launch: Connect to or launch the environment.

Microsoft Dev Box will launch in the web browser by default. To launch the
Dev Box in the new Windows App RDP client, install Windows App from
Microsoft Store.

2. Start or Stop: Select the drop-drown arrow beside the Launch button to find the
start and stop actions.

3. Delete, Restart, Pin to taskbar: Select the 3-dots above the Launch button to
delete, restart, or pin this virtual environment to the Windows Taskbar.

The "Pin to Taskbar" and "Pin to Start menu" actions will not appear unless
Windows App is installed from Microsoft Store.

4. Sync: Select the Sync button on the top of the Dev Home Environments window if
your virtual environment has been installed, but is not displayed. For example, if
you have Dev Home open and simultaneously delete a Hyper-V VM outside of Dev
Home, or create a new Microsoft Dev Box in the Azure portal, these changes may
not be reflected in Dev Home until you select Sync or Dev Home relaunches.

Create a new virtual environment using Dev

Home
To create a new virtual environment:

1. Select Create Environment in the Environments or Machine Configuration window

of Dev Home.

2. Select the type of environment you would like to create (only supported and
installed environment types will be available).

3. Each environment can have different creation parameters, such as name, pool,
project, image, and more. These specifications depend on the environment type.

For Hyper-V VMs, currently quick-creation images are supported. Custom

images (.iso, .vhd, .vhdx) for VM creation are not yet supported, but are in
development.
Create a WinGet Configuration file for your Dev
Home Environment
If your virtual environment has Dev Home installed, you can launch the environment and
use the Machine Configuration local setup tool.

Alternatively, you can remotely configure your environment:

1. On the Machine Configuration page in Dev Home, select Configure an

environment.

2. Choose your existing environment to configure.

3. Select repositories to clone.

4. Select apps to install.

5. Review your configuration. Once complete, the virtual environment will be

configured with your selected resources. You may be asked to enter user
credentials for the specific environment to apply these changes.
Build a Dev Home Environment Extension
If there is a type of virtual environment that you regularly use that is currently
unsupported by Dev Home, you can build your own Dev Home Environment Extension
to display the virtual environment in Dev Home.

To build an environment extension, see our guidance and API documentation on

GitHub: Developer environments in Dev Home .

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Dev Home Windows Customization
Article • 05/10/2024

Windows Customization in Dev Home enables you to configure your Windows

environment to suit your development needs.

Adjust advanced Windows settings, such as showing file extensions, hidden and
system files, full paths in the title bar, empty drives, and more in File Explorer.
Optimize the performance of your Windows machine using Dev Drive insights.
New experimental features.

Get started with Windows Customization

1. Ensure that you have the latest version of Dev Home by running the command:
winget upgrade Microsoft.DevHome .

2. Enable any Windows Customization experimental features that you wish to use in
the Dev Home Experimental settings (Settings > Experimental features > toggle
to On).

File Explorer settings

Adjust the default File Explorer settings in Windows for a more developer-friendly
experience, including:

Show file extensions: Display the file extension (for example .docx or .png ) when
listing files in File Explorer.
Show hidden and system files: Display all files in File Explorer even if they are
marked as a hidden or system file.
 Show full path in title bar: Display the full file path in File Explorer rather than
using abbreviated paths.
Show files after extraction is complete: Displays all files after an unzip (extract)
action is performed on files or folders from a zipped (compressed) folder.
Show empty drives: All attached drives will display in File Explorer, even if empty.
End Task: Enable the ability to end a task using a right-click selection from the
Windows taskbar.

Dev Drive Insights

Dev Drive insights provides you with information and suggestions to optimize the use
of Dev Drive volumes specific to an individual machine and workstream.

Check Dev Drive information at a glance, such as total size, amount of storage space
used and amount of storage space available.

Dev Drive Insights will also list suggestions for moving package caches, such as the Pip
cache or NuGet cache location, in order to improve your machine's performance. This
suggestion may look something like: "Move contents of C:\Users\user-
name\AppData\Local\npm-cache to a directory on the Dev Drive, such as G:\packages\npm

and set NPM_CONFIG_CACHE to that chosen directory location on Dev Drive.

Quiet Background Processes

Turning on Quiet Background Processes will deprioritize deferrable tasks by sending
pause and resume notifications to applications that have registered their preferred
execution policies with the Activity Coordinator API.

Deprioritized tasks will be paused for a maximum of 2 hours in order to prioritize

development-focused performance.

After ending a "Quiet Background Processes" session, you can review an Analytic
summary to see how this setting may have impacted CPU usage during your
development time.

*The Quiet Background Processes feature in Dev Home is only available on modern
versions of Windows 11 and will not be displayed or available as an experimental feature
on unsupported versions of Windows.

Feedback and feature requests

Dev Home is open source and welcomes your contributions and feedback. File new
feature requests for Windows Customization on GitHub .

６ Collaborate with us on
GitHub
The source for this content can
be found on GitHub, where you
can also create and review
issues and pull requests. For
more information, see our
contributor guide.
Windows developer
feedback
Windows developer is an open
source project. Select a link to
provide feedback:

 Open a documentation issue

 Provide product feedback

Set up a Dev Drive on Windows 11
Article • 02/26/2024

Dev Drive is a new form of storage volume available to improve performance for key
developer workloads.

Dev Drive builds on ReFS technology to employ targeted file system optimizations and
provide more control over storage volume settings and security, including trust
designation, antivirus configuration, and administrative control over what filters are
attached.

See the blog post: Dev Drive for Performance Improvements in Visual Studio and Dev
Boxes for some average improvement measurements across common dev operations.

How to set up a Dev Drive

To set up a new Dev Drive, open Windows Settings and navigate to System > Storage >
Advanced Storage Settings > Disks & volumes. Select Create dev drive. *Before setting
up a Dev Drive, ensure that the prerequisites are met. You can also set up a Dev Drive
using Dev Home's Machine configuration.
Prerequisites
Windows 11, Build #10.0.22621.2338 or later (Check for Windows updates)
Recommend 16gb memory (minimum of 8gb)
Minimum 50gb free disk space
Dev Drives are available on all Windows SKU versions.

When updating to the latest Windows 11 release, you may need an additional reboot
before the Dev Drive feature becomes available. If you are working in a business
enterprise environment, your security administrator will need to Configure Dev Drive
security policy in order to enable Dev Drive.

２ Warning

Dev Drive is intended only for key developer scenarios and any custom settings
will still be covered by Group Policy settings in Business or Enterprise work
environments. Learn more about how to Configure Dev Drive security policy.

Set up options
You will be given three options:

1. Create new VHD - Build volume on a new virtual hard disk

2. Resize an existing volume - Create new unallocated space to build on
3. Unallocated space on disk - Use the unallocated space on an existing disk. *This
option will only display if you have previously set up unallocated space in your
storage.
Create new VHD
When choosing the Create new VHD option to set up a Dev Drive, you will then need to
determine the following:

Virtual hard disk name: Give a name to your VHD (Dev Drive).
Location: Assign a directory path where the Dev Drive VHD will be located on your
machine. The default location is C:\ , unless creating a Dev Drive using Dev Home,
in which case the default location is %userprofile%\DevDrives . We recommend
using a per-user directory path location to store your Dev Drive to avoid any
unintentional sharing.
Virtual hard disk size: Assign the amount of disk space that will be allocated for
the volume to use, minimum size is 50GB.
Virtual hard disk format:
VHD: Supports virtual disks up to 2040 GB in size.
VHDX (Recommended): Supports a maximum of 64 TB and offers more resilient
protection against unexpected IO failure caused by issues like power outage.
Learn more about Managing VHDs.
Disk type:
Fixed size - This virtual hard disk file is allocated to the maximum size when
created.
 Dynamically expanding - The virtual hard disk file grows to its maximum size as
data is written to the disk. (Recommended)

Once you complete the process of selecting between these options, your Dev Drive will
be created.

Existing storage volumes cannot be converted to be a Dev Drive. The Dev Drive
designation happens only at the original format time.

Resize an existing volume or use unallocated space on an

existing disk
To Resize an existing volume:

1. Choose a volume to resize.

2. Choose a new size for the volume. You will need to have at least 50GB of
unallocated space available, the minimum size needed for a Dev Drive. Once the
size is set, select Next.
 3. To format a Dev Drive on the new free space, specify the Label (drive name), Drive
Letter, and Size allocation. The maximum size will be the amount of free space you
allocated in the previous step, the minimum size for a Dev Drive is 50GB.

Congratulations! You've now resized your Dev Drive.

To find and use unallocated space on an existing drive, you can open System >
Storage > Disks & volumes, look through the page to see whether any storage space is
listed as "Unallocated". Select Create volume and you will be given the choices to
Create Simple Volume (a standard NTFS storage volume) or Create Dev Drive. To create
a Dev Drive, the steps are the same as above, you will need to add a Label (drive name),
Drive Letter, and confirm the Size allocation.
Format a storage volume as a Dev Drive from the
command line
As an alternative to using Windows Settings, there are two options for creating Dev
Drive storage volumes from the command line. Both options require that you open the
command line as an Administrator. You must be a member of the Admin group to
format a hard drive. These command line formatting methods may be preferred when
creating multiple Dev Drives or as an admin for multiple machines.

1. Using the Format command line tool from Windows CMD or PowerShell:

CMD

Format D: /DevDrv /Q

2. Using the Format-Volume cmdlet from PowerShell:

PowerShell

Format-Volume -DriveLetter D -DevDrive

These code samples require that you replace D: with the drive location you wish to
target. See the links for more options and command parameters.
How does Dev Drive work?
A Storage Volume specifies how data is stored on the file system, via directories and
files, in a particular format. Windows uses NTFS for the system drive and, by default, for
most non-removable drives. The Resilient File System (ReFS) is a newer Microsoft file
system format, designed to maximize data availability, scale efficiently to large data sets
across diverse workloads, and provide data integrity with resiliency to corruption. It
seeks to address an expanding set of storage scenarios and establish a foundation for
future innovations.

The Dev Drive utilizes ReFS enabling you to initialize a storage volume specifically for
development workloads, providing faster performance, and customizable settings that
are optimized for development scenarios. ReFS contains several file system specific
optimizations to improve the performance of key developer scenarios.

Learn more about how Dev Drive handles security.

What should I put on my Dev Drive?

The Dev Drive is intended for:

Source code repositories and project files

Package caches
Build output and intermediate files

Dev Drive is not intended to store developer tools, such as:

Visual Studio
MSBuild
.NET SDK
Windows SDK, etc.

These tools should be stored on your main C:\ drive.

７ Note

IT Admins will want to create per-user Access Control List (ACL) folders for multi-
user devices as a best practice to avoid EOP attacks.

Storing package cache on Dev Drive

A package cache is the global folder location used by applications to store files for
installed software. These source files are needed when you want to update, uninstall, or
repair the installed software. Visual Studio is one such application that stores a large
portion of its data in the Package Cache.

Npm cache (NodeJS): Create an npm cache directory in your Dev Drive, e.g.
D:\packages\npm , then set a global environment variable npm_config_cache to that

path, e.g. setx /M npm_config_cache D:\packages\npm . If you have already installed

NodeJS on your machine, move the contents of %AppData%\npm-cache to this
directory. (On some systems the npm cache may be in %LocalAppData%\npm-cache ).
Learn more in the npm docs: npm-cache and npm config: cache .

NuGet global-packages folder: The NuGet global-packages folder is used by

dotnet, MSBuild, and Visual Studio. Create a user specific NuGet directory in your
CopyOnWrite (CoW) filesystem. For example: D:\<username>\.nuget\packages . Use
one of the following ways to change the global-packages folder from the default
location to your newly created folder (to manage the globally installed packages):

Set a global environment variable NUGET_PACKAGES to that path. For example:

setx /M NUGET_PACKAGES D:\<username>\.nuget\packages .

Set globalPackagesFolder , when using PackageReference , or repositoryPath ,

when using packages.config , to that path in configuration settings.

Set the RestorePackagesPath MSBuild property (MSBuild only) to that path.

To verify the global-packages folder, run the dotnet nuget locals command:
dotnet nuget locals global-packages --list . The restore will install and

download packages into the new path. The default NuGet global-packages
folder can be deleted. Learn more in the NuGet docs: Managing the global
packages, cache, and temp folders.

vcpkg cache: Create a vcpkg cache directory in your Dev Drive, e.g.
D:\packages\vcpkg , then set a global environment variable

VCPKG_DEFAULT_BINARY_CACHE to that path, e.g. setx /M VCPKG_DEFAULT_BINARY_CACHE

D:\packages\vcpkg . If you have already installed packages, move the contents of

%LOCALAPPDATA%\vcpkg\archives or %APPDATA%\vcpkg\archives to this directory.

Learn more in the vcpkg docs: vcpkg Binary Caching.

Pip cache (Python): Create a pip cache directory in your Dev Drive, e.g.
D:\packages\pip , then set a global environment variable PIP_CACHE_DIR to that

path, e.g. setx /M PIP_CACHE_DIR D:\packages\pip . If you have already restored pip
 packages and Wheels on your machine, move the contents of
%LocalAppData%\pip\Cache to this directory. Learn more in the pip docs: pip

caching and see StackOverflow to Change directory of pip cache on Linux? .

Cargo cache (Rust): Create a Cargo cache directory in your Dev Drive, e.g.
D:\packages\cargo , then set a global environment variable CARGO_HOME to that

path, e.g. setx /M CARGO_HOME D:\packages\cargo . If you have already restored

Cargo packages on your machine, move the contents of %USERPROFILE%\.cargo to
this directory. Learn more in the Cargo docs: Cargo Environmental Variables .

Maven cache (Java): Create a Maven cache directory in your Dev Drive, e.g.
D:\packages\maven , then set a global environment variable MAVEN_OPTS to add a

configuration setting to that path, e.g. setx /M MAVEN_OPTS "-

Dmaven.repo.local=D:\packages\maven %MAVEN_OPTS%" . Move the contents of

%USERPROFILE%\.m2 to this directory. Learn more in the Maven docs and see
StackOverflow for How to specify an alternate location for the .m2 folder or
settings.xml permanently? .

Gradle cache (Java): Create a Gradle cache directory in your Dev Drive, for
example, D:\packages\gradle . Then, set a global environment variable
GRADLE_USER_HOME to point to that path, for example, use setx /M GRADLE_USER_HOME
"D:\packages\gradle" in the command line to set it system-wide. After setting this

variable, Gradle will use the specified directory ( D:\packages\gradle ) for its caches
and configuration files. If you have existing Gradle files, move the contents of
%USERPROFILE%\.gradle to this new directory. For more detailed information, you

can refer to the Gradle documentation and explore community resources like
StackOverflow for tips on managing Gradle configurations and cache directories .

Understanding security risks and trust in

relation to Dev Drive
Security and trust are important considerations when working with project files.
Typically, there is a tradeoff between performance and security. Using a Dev Drive places
control over this balance in the hands of developers and security administrators, with a
responsibility for choosing which filters are attached and the settings for Microsoft
Defender Antivirus scans.

Antivirus filters, including both Microsoft Defender and 3rd-party antivirus filters, are
attached to a Dev Drive by default. Microsoft Defender Antivirus defaults to the new
"performance mode" setting on Dev Drives, taking speed and performance into account,
while providing a secure alternative to folder exclusions. For an increased level of
protection, Microsoft Defender also offers "Real-time protection mode".

Any product or features requiring additional filters will not work unless the filter is
added to Dev Drive.

２ Warning

Dev Drives can be run with no antivirus filters attached. Exercise extreme caution!
Removing antivirus filters is a security risk and means that your storage drive will
not be covered by the standard security scans. You are responsible for evaluating
the risks associated with detaching antivirus filters and should only do so when
confident that your files stored on the Dev Drive will not be exposed to malicious
attacks.

Microsoft recommends using the default performance mode setting when using a
trusted Dev Drive.

What is a “trusted” Dev Drive?

Dev Drives are automatically designated as trusted using a flag stored in the system
registry during the original formatting time, providing the best possible performance by
default. A trusted Dev Drive means that the developer using the volume has high
confidence in the security of the content stored there.

Similar to when a developer chooses to Add an exclusion to Windows Security , the

developer takes on the responsibility for managing the security of the content stored in
order to gain additional performance.

A Dev Drive marked as trusted is a signal for Microsoft Defender to run in performance
mode. Running Microsoft Defender in performance mode provides a balance between
threat protection and performance. Real-time protection will still be enabled on all other
storage volumes.

Due to the security considerations of having filters detached, transporting a dev drive
between machines will result in the volume being treated as an ordinary volume without
special filter attach policies. The volume needs to be marked as trusted when it is
attached to a new machine. See How do I designate a Dev Drive as trusted?.

An untrusted Dev Drive will not have the same privileges as a trusted Dev Drive. Security
will run in real-time protection mode when a Dev Drive is untrusted. Exercise caution if
designating trust to a Dev Drive outside of the time that it is first created.
How do I designate a Dev Drive as trusted?
To designate a Dev Drive as trusted:

1. Open PowerShell (or CMD) with elevated permissions by right-clicking and

selecting "Run as Administrator".
2. To designate your Dev Drive as trusted enter the command below, replacing
<drive-letter> with the letter of the storage drive you are designating trust to.

For example, fsutil devdrv trust D: .

PowerShell

fsutil devdrv trust <drive-letter>:

To confirm whether a Dev Drive is trusted, enter the command:

PowerShell

fsutil devdrv query <drive-letter>:

The C: drive on your machine cannot be designated as a Dev Drive. Developer tools,
such as Visual Studio, MSBuild, .NET SDK, Windows SDK, etc, should be stored on your
C:/ drive and not in a Dev Drive.

What is Microsoft Defender performance mode?

Performance mode is now available on Windows 11 as a new Microsoft Defender
Antivirus capability. This capability reduces the performance impact of Microsoft
Defender Antivirus scans for files stored on a designated Dev Drive.

To learn more about performance mode and how it compares with real-time protection,
see Microsoft Defender: Protecting Dev Drive using performance mode.

For performance mode to be enabled, the Dev Drive must be designated as trusted and
Microsoft Defender Real-time protection must be set to "On".

How do I configure additional filters on Dev Drive?

By default, Filter Manager will turn OFF all filters on a Dev Drive, with the exception of
antivirus filters. An antivirus filter is a filter that's attached in the FSFilter Anti-Virus
altitude range (i.e., 320000-329999). FSFilter Anti-Virus includes filters that detect and
disinfect viruses during file I/O.
The default policy can be configured not to attach antivirus filters to Dev Drive using
fsutil . CAUTION: This policy applies to ALL Dev Drives on the system.

PowerShell

fsutil devdrv enable /disallowAv

The command, fsutil devdrv enable [/allowAv|/disallowAv] , includes the following

two options:

disallowAv : Specifies that your Dev Drive(s) do not have any attached filters (not

even antivirus). Filters can be added back using fsutil devdrv setfiltersallowed
<Filter-1> command. (Replacing <Filter-1> with the name of your desired filter.)

allowAv : Specifies that Dev Drives are to be protected by the default antivirus

filter.

For help, enter the command: fsutil devdrv enable /? . If neither /allowAv nor
/disallowAv is specified, the antivirus policy for your Dev Drive is not configured and

the system default is to have Dev Drives protected by antivirus filter.

２ Warning

Exercise extreme caution when detaching filters. Detaching antivirus filters is a

security risk and means that your storage will not be covered by the standard
Microsoft Defender real-time protection or performance mode scans. You are
responsible for evaluating the risks associated with detaching antivirus filters and
should only do so when confident that your files will not be exposed to malicious
attacks.

To learn more about filters, see About file system filter drivers, Installing a filter driver,
Filter Manager Concepts, Load order groups and altitudes for minifilter drivers.

Allowing select filters to attach on Dev Drive

If you are working in a Business or Enterprise environment, your company's group policy
may be configured for select filters to attach on Dev Drives, in addition to the above
policy. A system administrator may also choose to attach additional filters to a specific
Dev Drive or all Dev Drives using an allow list.
A system admin may want to add a filter called "Foo", we will refer to it as FooFlt . They
may only want that filter enabled on the Dev Drive mounted as D: . They do not need
this filter on another Dev Drive mounted as E: . The admin can make changes to an
allow list of filters on the Dev Drive using fsutil.exe, a system-supplied command line
utility.

Filters specifically set as Allowed can attach to a Dev Drive in addition to antivirus filter
policy discussed above.

Allow list filter examples

The following examples demonstrate an administrator's ability to set filters allowed on
all Dev Drives on a machine, using an allow list.

To use the setfiltersallowed command to allow Filter-01 and Filter-02 on all Dev
Drives, use the command:

PowerShell

fsutil devdrv setfiltersallowed Filter-01, Filter-02

To display the filter attach policy for all Dev Drives, use the command:

PowerShell

fsutil devdrv query

The result will display the following:

Developer volumes are enabled.

Developer volumes are protected by antivirus filter.
Filters allowed on any Dev Drive: Filter-01 , Filter-02

To change this Dev Drive configuration to allow only Filter-03 on your Dev Drive(s),
with Filter-01 and Filter-02 no longer allowed to attach, use the command:

PowerShell

fsutil devdrv setfiltersallowed Filter-03

See fsutil devdrv /? for other related commands.

Filters for common scenarios
The following filters may be used with Dev Drive:

ﾉ Expand table

Scenario: Description Filter Name

GVFS: Sparse enlistments of Windows PrjFlt

MSSense: Microsoft Defender for Endpoint for EDR Sensor MsSecFlt

Defender: Windows Defender Filter WdFilter

Docker: Running containers out of Dev Drive bindFlt, wcifs

Windows Performance Recorder: Measure file system operations FileInfo

Resource Monitor: Shows resource usage. Required to show file names in Disk FileInfo
Activity

Process Monitor - Sysinternals: Monitor file system activities ProcMon24

Windows Upgrade: Used during OS Upgrade. Required if user moves TEMP WinSetupMon
environment variable to Dev Drive

The WdFilter is attached by default. The following command is an example

demonstrating how to attach all of these additional filters to a Dev Drive:

PowerShell

fsutil devdrv setfiltersallowed PrjFlt, MsSecFlt, WdFilter, bindFlt, wcifs,

FileInfo, ProcMon24

 Tip

To determine the filters required for a specific scenario, you may need to
temporarily mark a Dev Drive as untrusted. Then, run the scenario and make note of
all filters that attached to the volume. Designate the Dev Drive as trusted again and
then add the filters to the Allow list for that Dev Drive to ensure the scenario
succeeds. Finally, remove any filters that may not be needed, one at a time, while
ensuring that the scenario works as expected.

 Tip
 The filter name for Process Monitor may change. If adding the filter name
"ProcMon24" doesn't seem to capture file system activities on a Dev Drive, list the
filters using the command fltmc filters , find the filter name for Process Monitor,
and use that name instead of "ProcMon24".

What scenarios are unsupported by Dev Drive?

What are the limitations?
There are a few scenarios in which we do not recommend using a Dev Drive. These
include:

Reformatting an existing storage volume to be a "Dev Drive" will destroy any

content stored in that volume. Reformatting an existing volume while preserving
the content stored there is not supported.
When you create a Virtual Hard Disk (VHD) hosted on a fixed disk (HDD or SSD), it
is not recommended to copy the VHD, move it to a different machine, and then
continue using it as a Dev Drive.
A volume stored on a removable or hot-pluggable disk (such as a USB, HDD, or
SSD external drive) does not support designation as a Dev Drive.
A volume in a VHD hosted by a removable or hot-pluggable disk does not support
designation as a Dev Drive.
The C: drive on your machine cannot be designated as a Dev Drive.
The purpose of a Dev Drive is to host files for building and debugging software
projects designated to store repositories, package caches, working directories, and
temp folders. We do not recommend installing applications on a Dev Drive.
Using Dev Drive on Dynamic Disks is unsupported. Instead, use Storage Spaces ,
which will help protect your data from drive failures and extend storage over time
as you add drives to your PC.

How to delete a Dev Drive

You can delete a Dev Drive in the Windows 11 System Settings: System > Storage >
Disks & volumes .

Open Windows Settings menu, then choose Storage, then Advanced Storage Settings,
then Disks & volumes, where you will find a list of the storage volumes on your device.
Select Properties next to the Dev Drive storage volume that you want to delete. In the
drive's properties, you will find the option to Delete under the Format label.
The Dev Drive will now be deleted. However, if the Dev Drive was created as a new VHD,
the VHD will need to be deleted to reclaim the storage space used by that VHD. To
accomplish this, you must detach the virtual disk so that the VHD file hosting the Dev
Drive can be deleted, following these steps:

1. Open the Disk Management tool by entering "Computer Management" in the

search box on the taskbar. Select Disk Management under the Storage heading.
Select the Disk (not the Volume) of the Dev Drive. Right-click the selected Disk
hosting the Dev Drive and, from the resulting menu, select Detach VHD.
2. A pop-up window will appear informing you that detaching a virtual hard disk will
make it unavailable.
3. Once detached, the VHD can be deleted.
Dev Drive FAQs
Some frequently asked questions about Dev Drive, include:

How can I customize a Dev Drive to meet my needs?

The Dev Drive default settings have been optimized for common development
scenarios, but can be customized, allowing control over drivers and services run on the
storage volume. To customize Dev Drive settings, open the Settings menu. Under
System > Storage > Disks & volumes, go to Properties.

） Important

If working for a business or enterprise, the Dev Drive would still be managed by
your enterprise settings. Some customizations may therefore be unavailable
depending on the company policy.

Do I need to reinstall my applications to use a Dev Drive?

No, applications or tools installed on your machine’s C: drive can utilize files from a Dev
Drive. For development projects, however, we recommend storing any project-specific
directories, files, and package caches inside the Dev Drive. The Dev Drive can be pinned
to File Explorer’s Quick Access as a reminder.
Does ReFS use more memory than NTFS does?
Yes, ReFS uses slightly more memory than NTFS. We recommend a machine with at least
8gb of memory, ideally 16gb.

Can I have more than one Dev Drive on my machine?

Yes. If you have the space, you can create as many Dev Drives as you would like. Using a
separate Dev Drive for each software development project would allow you to simply
delete the drive at the end of development, rather than repartitioning your disk again.
However, keep in mind that the minimum size for a Dev Drive is 50GB.

What do I need to know about using Dev Drive with

Visual Studio?
Once you have a Dev Drive created, Visual Studio will automatically recognize it when
you're creating a new project, or cloning an existing project, and pick that filepath by
default. To optimize performance when using Visual Studio, we recommend moving any
project code, package caches, and Copy on write MS Build tasks to the Dev Drive that
may have previously been saved elsewhere. (See How to change the build output
directory in the Visual Studio docs.) We also recommend that you consider redirecting
%TEMP% and %TMP% envvars to Dev Drive. Many programs use these, so beware of

potential side effects. We also recommend using performance mode for Microsoft
Defender for asychronous performance gains using Dev Drive. Turning Microsoft
Defender completely off may result in the most maximum performance gains, but this
may increase security risks and is a setting controlled by the system admin.

For more information, see the blog post: Dev Drive for Performance Improvements in
Visual Studio and Dev Boxes .

Does Dev Drive work with WSL project files?

You can access Dev Drive project files, which run on the Windows file system, from a
Linux distribution running via WSL. However, WSL runs in a VHD and for the best
performance files should be stored on the Linux file system. WSL is out of the scope of
Windows file system so you should not expect to see any performance improvement
when accessing project files in Dev Drive from a Linux distribution running via WSL.

What method is used to format a Windows storage

volume?
See MSFT_Volume class in the Windows Driver docs.

How to configure and use Live Unit Testing with a Dev

Drive?
You can find guidance on How to configure and use Live Unit Testing in the Visual
Studio documentation. However, be aware that there is a dependency on ProjFS. You will
need to move the Live Unit Testing workspace root to the Dev Drive and add Windows
Projected File System to the allowed filter list. You can do so using the following
command in PowerShell:

PowerShell

fsutil devdrv setfiltersallowed PrjFlt

Will a VHD created for use as a Dev Drive be encrypted

when the drive storing it is BitLocker enabled?
Yes, the Dev Drive VHD will be included in the BitLocker encryption of the hosting
volume.

Can Dev Drive make Java development faster on

Windows?
Yes, using a Dev Drive can enhance efficiency and reduce build times when working on a
Java development project. See the blog post "Speed up your Java Development on
Windows with Dev Drive" .

How to contribute to these docs and FAQs?

If you find any issues in this documentation or would like to contribute additional FAQ
suggestions, visit the Windows Dev Docs open source repo on GitHub .

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For  Open a documentation issue
more information, see our
contributor guide.  Provide product feedback
How to configure Dev Drive security
policy for enterprise business devices
Article • 09/26/2023

Enterprise-level administrators are often responsible for managing security across many
different Windows devices within an organization. There are multiple ways to configure
the policies that control whether new features are enabled as the become available in
new Windows releases. This guide covers important information about Windows 11 Dev
Drive storage volume features and how to configure Group Policy for your organization
to enable developers to use this performance-optimized storage format while
maintaining security and control over attaching file system filters.

Guidance on how to enable Group Policy can be found below using your preferred
policy management tool:

Microsoft Intune,
Microsoft Configuration Manager (ConfigMgr, formerly MEMCM/SCCM), or
Windows 11 Local Group Policy Editor.

Prerequisites
Windows 11, Build #10.0.22621.2338 or later (Check for Windows updates)
Recommend 16gb memory (minimum of 8gb)
Minimum 50gb free disk space
Dev Drives are available on all Windows SKU versions.

Temporary enterprise feature control disables

Dev Drive
New features and enhancements are introduced through the monthly cumulative
update to provide continuous innovation for Windows 11. To give organizations time to
plan and prepare, some of these new features are temporarily turned off by default
using Temporary enterprise feature control in Windows 11.

Dev Drive will be automatically disabled for devices that have their Windows updates
managed by policies. Disabling the ability to create a Dev Drive is only temporary to
allow security administrators time to decide on and roll out new policy updates.
Guidance for determining and configuring those policy updates is outlined below.
Determine Group Policy for Dev Drive storage
enablement and antivirus filter security
Group Policy is a Windows feature that lets enterprise administrators manage the
settings of work devices and have some control over what setting changes user
accounts (local administrators) are allowed to make in a business environment.

Antivirus filters, including both Microsoft Defender and 3rd-party antivirus filters, are
attached to a Dev Drive by default. The default settings for Dev Drive storage volumes
also allow local device administrators to control what filters are attached. This means
that a local device administrator could configure the system to remove default antivirus
filters, so that no antivirus filters are attached to the Dev Drive. If this is a concern, Group
Policy may be configured to ensure that antivirus filters remain attached when Dev Drive
is enabled. Additionally, an allowed file system filter list may be defined.

Update Group Policy to enable Dev Drive

The Enable Dev Drive policy settings include:

Not Configured: By default, the Dev Drive storage volume option will be turned off
under the Temporary enterprise feature control policy until enabled by an
enterprise administrator in the Group Policy.
Enabled: Enabling turns on the option to create Dev Drive storage volumes.
Options - Let antivirus filter protect Dev Drives: Dev Drives are optimized for
performance in developer scenarios, allowing the local administrator (user
account) to choose which file system filters are attached. This also allows local
administrators to detach the default antivirus features, unless the option to "Let
antivirus filter protect Dev Drives" is checked. Checking this option forces default
antivirus filters to remain attached.
Disabled: Disabling this setting turns off the ability to create and use Dev Drive
storage volumes.

Update Dev Drive filter attach policy

Additionally, there is a Dev Drive filter attach policy setting, which offers enterprise
administrators control over what filters can be attached to a Dev Drive. Settings include:

Not Configured: By default, Dev Drive is optimized for performance, with

Microsoft Defender and 3rd-party antivirus filters attached, but with no other file
system filters. This default setting allows local administrators to attach or detach
 filters, including the default antivirus filters. Checking the optional "Let antivirus
filter protect Dev Drives" in the Enable Dev Drive policy above will force antivirus
filters to remain attached even if no further filter policy is defined.
Enabled: Local administrators (user accounts) are allowed to attach or detach
filters. Adding a Filter list enables enterprise administrators (at the Group Policy
Domain level) to define what filters can be attached. Not including a filter list will
enable any filter to be attached.
Disabled: Local administrators (user accounts) are not allowed to attach or detach
filters.

There are a few ways to enable the Dev Drive feature and update Group Policy:

Update Group Policy using Microsoft Intune

Update Group Policy using Microsoft Configuration Manager
Update Group Policy using Windows 11 Local Group Policy Editor

Use Microsoft Intune to update Group Policy

for Dev Drive
To update Group Policy and enable Dev Drive using Microsoft Intune):

1. Open the Intune portal (https://endpoint.microsoft.com ) and log in with your

credentials.

2. Create a profile:
a. Devices > Windows > Configuration profiles > Create profile
b. Select Platform > Windows 10 and later
c. Select Profile type > Settings catalog
3. Set a custom profile name and description.

4. Configure Dev Drive related settings:

a. Search “Dev Drive” in settings picker or navigate to “Administrative
Templates\System\Filesystem”
b. Select Dev Drive related policies: Enable Dev Drive and Let antivirus filter
protect Dev Drives, Dev Drive filter attach policy and Filter list

5. Configure the Dev Drive policy settings, complete the remaining configuration of
Scope tags and Assignments, then select Create
Use Microsoft Configuration Manager to
update Group Policy for Dev Drive
To update Group Policy and enable Dev Drive using Microsoft Configuration Manager
(ConfigMgr, formerly MEMCM/SCCM), you can use the following PowerShell scripts.
(What is Configuration Manager?)

The Configuration Manager console has an integrated ability to run PowerShell scripts
to update Group Policy settings across all computers in your network.

1. Open the Microsoft Configuration Manager console. Select Software Library >
Scripts > Create Script.
2. Enter the script name (for example, Dev Drive demo), description (Demo
configuration to enable Dev Drive settings), language (PowerShell), timeout
seconds (180), and then paste in the following "Dev Drive demo" script example to
use as a template.

PowerShell

######
#ConfigMgr Management of Dev Drive
#Dev Drive is a new form of storage volume available to improve
performance for key developer workloads.
#Check Log File for enforcement status -
C:\Windows\temp\ConfigDevDrive-<TimeStamp>.log
######

Function Set-RegistryKeyValue{
param (
$KeyPath,
$ValueName,
$Value,
$PropertyType,
$LogFile
)
Try {
If (!(Test-path $KeyPath)) {
$Path = ($KeyPath.Split(':'))[1].TrimStart("\")

([Microsoft.Win32.RegistryKey]::OpenRemoteBaseKey([Microsoft.Win32.Regi
stryHive]::LocalMachine,$env:COMPUTERNAME)).CreateSubKey($Path)
New-ItemProperty -path $KeyPath -name $ValueName -value $Value -
PropertyType $PropertyType -Force | Out-Null
 }
Else {
New-ItemProperty -path $KeyPath -name $ValueName -value $Value -
PropertyType $PropertyType -Force | Out-Null
}
$TestValue = (Get-ItemProperty -Path $KeyPath)."$ValueName"
If ($TestValue -eq $Value){ Add-Content -Path $LogFile -Value
"$KeyPath,$ValueName,$Value,$PropertyType,$TestValue,Success" }
Else { Add-Content -Path $LogFile -Value
"$KeyPath,$ValueName,$Value,$PropertyType,$TestValue,Failure" }
}
Catch {
$ExceptionMessage = $($PSItem.ToString()) -replace
[Environment]::NewLine,"";
Add-Content -Path $LogFile -Value
"$KeyPath,$ValueName,$Value,$PropertyType,$TestValue,Failure -
$ExceptionMessage"
}
}
$ExecutionTime = Get-Date
$StartTime = Get-Date $ExecutionTime -Format yyyyMMdd-HHmmss
$LogFile = "C:\Windows\temp\ConfigDevDrive-$StartTime.log"
Add-Content -Path $LogFile -Value "------------------------------------
V 1.0 $ExecutionTime - Execution Starts -------------------------------
------------"
Add-Content -Path $LogFile -Value
"RegistryKeyPath,ValueName,ExpectedValue,PropertyType,CurrentValue,Comp
arisonResult"
#Set up a Dev Drive
Set-RegistryKeyValue -KeyPath
"HKLM:\System\CurrentControlSet\Policies\" -ValueName
"FsEnableDevDrive" -Value "1" -PropertyType "Dword" -LogFile $LogFile
Set-RegistryKeyValue -KeyPath
"HKLM:\System\CurrentControlSet\Policies\" -ValueName
"FltmgrDevDriveAllowAntivirusFilter" -Value "1" -PropertyType "Dword" -
LogFile $LogFile
Set-RegistryKeyValue -KeyPath
"HKLM:\System\CurrentControlSet\Policies\" -ValueName
"FltmgrDevDriveAttachPolicy" -Value "PrjFlt, MsSecFlt, WdFilter,
bindFlt, wcifs, FileInfo" -PropertyType "MultiString" -LogFile $LogFile
$ExecutionTime = Get-Date
Add-Content -Path $LogFile -Value "------------------------------------
$ExecutionTime - Execution Ends ---------------------------------------
----"
--------------------

3. When adding a new script, you must select and approve it. The approval state will
change from "Waiting for approval" to "Approved".

4. Once approved, right-click a single device or device collection and select Run
script.
 5. On the script page of the Run Script wizard, choose your script from the list (Dev
Drive demo in our example). Only approved scripts are displayed. Select Next and
complete the wizard.

See Query policies with FsUtil to check that Group Policy settings were accurately
updated.

To learn more, see Create and run PowerShell scripts from the Configuration Manager
console.

Use Windows 11 Local Group Policy Editor to

update Group Policy for Dev Drive
To update Group Policy and enable Dev Drive using Windows 11 Local Group Policy
Editor:

1. Open the Local Group Policy Editor in Windows Control Panel.

 2. Under Computer Configuration, select Administrative Templates > System >
Filesystem and in the Setting list, select Enable dev drive.

3. Select Enabled to enable Dev Drive in your Group Policy.

To update this filter attach policy, select Dev Drive filter attach policy from the Local
Group Policy Editor in Windows Control Panel.
Query policies with FsUtil
FSUtil can be used to query the Group Policy configured for Dev Drive. Here is the
output from an FsUtil query for a Dev Drive Group Policy configured to:

Enable Dev Drive

Let antivirus filters protect Dev Drives ( MsSecFlt )
FileInfo minifilter has been added to the Filter list as an allowed filter

Enter the FSUtil command:

PowerShell

fsutil devdrv query

Result:

PowerShell

Developer volumes are enabled.

Developer volumes are protected by antivirus filter, by group policy.
Filters allowed on any developer volume, by group policy:
MsSecFlt
Filters allowed on any developer volume:
FileInfo

This same query can be run on a specific Dev Drive to see the attached filters. To run the
command on a specific Dev Drive, enter the command:
 PowerShell

fsutil devdrv query d:

Result:

PowerShell

This is a trusted developer volume.

Developer volumes are protected by antivirus filter, by group policy.
Filters allowed on any developer volume, by group policy:
MsSecFlt
Filters allowed on any developer volume:
FileInfo
Filters currently attached to this developer volume:
MsSecFlt, WdFilter, FileInfo

Additional resources
Delivering continuous innovation in Windows 11 (Microsoft Support)

Temporary enterprise feature control in Windows 11

Manage additional Windows Update settings (Windows Deployment)

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Windows Package Manager
Article • 10/31/2023

Windows Package Manager is a comprehensive package manager solution that consists

of a command line tool (WinGet) and set of services for installing applications on
Windows devices.

Windows Package Manager is a helpful tool for:

Developers who want to manage their software applications using the command
line.
Independent Software Vendors (ISVs) who want to distribute software.
Enteprise organizations who want to automate device set up and maintain a secure
work environment.

Understanding package managers

A package manager is a system or set of tools used to automate installing, upgrading,
configuring and using software. Most package managers are designed for discovering
and installing developer tools.

Ideally, developers use a package manager to specify the prerequisites for the tools they
need to develop solutions for a given project. The package manager then follows the
declarative instructions to install and configure the tools. The package manager reduces
the time spent getting an environment ready, and it helps ensure the same versions of
packages are installed on their machine.

Third party package managers can leverage the Microsoft Community Package Manifest
Repository to increase the size of their software catalog.

Windows Package Manager for developers

Developers use the winget command line tool to discover, install, upgrade, remove and
configure a curated set of applications. After it is installed, developers can access winget
via the Windows Terminal, PowerShell, or the Command Prompt.

For more information, see Use the winget tool to install and manage applications.

For a video demo of winget, see Intro to Windows Package Manager.

For the latest announcements and version updates, see the Windows Command Line
Blog , including:

Windows Package Manager 1.4

Windows Package Manager 1.3
Windows Package Manager 1.2
Windows Package Manager 1.1
Windows Package Manager 1.0

Windows Package Manager for ISV software

distribution
Independent Software Vendors (ISVs) can use Windows Package Manager as a
distribution channel for software packages containing their tools and applications. To
submit software packages (containing .msix, .msi, or .exe installers) to Windows Package
Manager, we provide the open source Microsoft Community Package Manifest
Repository on GitHub where ISVs can upload package manifests to have their software
packages considered for inclusion with Windows Package Manager. Manifests are
automatically validated and may also be reviewed manually.

For more information, see Submit packages to Windows Package Manager.

Windows Package Manager for Enterprise

Security
The WinGet client can be used in the command line to install and manage applications
across multiple machines. Those responsible for setting up enterprise work
environments, such as IT Administrators or Security Analysts, with the goal of
maintaining a consistent level of security settings across everyone’s work machine may
also be using Microsoft Intune to manage security using “Group Policy” settings.

To maintain ongoing security updates, the WinGet client is released using the Microsoft
Store and installs applications from the Microsoft Store using the “msstore” source and
applying “certificate pinning” to ensure that the connection is secure and established
with the proper endpoint.

The Group Policy applied by your enterprise organization may be using SSL inspection
via a firewall between the WinGet client and the Microsoft Store source that causes a
connection error to appear in the WinGet client.
For this reason, the Windows Package Manager desktop installer supports a policy
setting called: “BypassCertificatePinningForMicrosoftStore”. This policy controls whether
the Windows Package Manager will validate the Microsoft Store certificate hash matches
to a known Microsoft Store certificate when initiating a connection to the Microsoft
Store Source. The options for this policy include:

Not configured (default): If you do not configure this policy, the Windows Package
Manager administrator settings will be adhered to. We recommend leaving this
policy in the not configured default unless you have a specific need to change it.
Enable: If you enable this policy, the Windows Package Manager will bypass the
Microsoft Store certificate validation.
Disable: If you disable this policy, the Windows Package Manager will validate the
Microsoft Store certificate used is valid and belongs to the Microsoft Store before
communicating with the Microsoft Store source.

“Certificate Pinning” ensures that the package manager connection to the Microsoft
Store is secure, helping to avoid risks associated with attacks such as Man-in-the-Middle
(MITM) attacks involving a third party inserting themselves between a client (user) and
server (application) to secretly intercept communication flows to steal sensitive data
such as login credentials, etc. Disabling “Certificate Pinning” (enabling the bypass) can
expose your organization to risk in this area and should be avoided.

To learn more about setting up Group Policy for your enterprise organization, see the
Microsoft Intune documentation.

Related topics
Use the winget tool to install and manage software packages
Submit packages to Windows Package Manager
Use the winget tool to install and
manage applications
Article • 05/04/2023

The winget command line tool enables users to discover, install, upgrade, remove and
configure applications on Windows 10 and Windows 11 computers. This tool is the
client interface to the Windows Package Manager service.

Install winget
Windows Package Manager winget command-line tool is available on Windows 11 and
modern versions of Windows 10 as a part of the App Installer.

You can get App Installer from the Microsoft Store . If it's already installed, make sure it
is updated with the latest version.

７ Note

The winget command line tool is only supported on Windows 10 1709 (build
16299) or later at this time. The winget tool will not be available until you have
logged into Windows as a user for the first time, triggering Microsoft Store to
register Windows Package Manager as part of an asynchronous process. If you
have recently logged in as a user for the first time and find that winget is not yet
available, you can open PowerShell and enter the following command to request
this winget registration: Add-AppxPackage -RegisterByFamilyName -MainPackage
Microsoft.DesktopAppInstaller_8wekyb3d8bbwe .

Install winget preview version [Developers Only]

WinGet is included in the Windows App Installer. To try the latest Windows Package
Manager features, you can install a preview build one of the following ways:

Download the latest winget preview version . Read the Release notes for winget
preview to learn about any new features. Installing this package will give you the
preview version of the WinGet client, but it will not enable automatic updates of
new preview versions from the Microsoft Store.

Use a Microsoft Account (MSA), work, school or Azure Active Directory (AAD)
account to sign up for the Windows Insider Dev Channel . The Windows Insider
 Dev Channel includes automatic updates of new preview versions from the
Microsoft Store.

Use a Microsoft Account (MSA) to sign up for the Windows Package Manager
Insiders Program . Once your Microsoft Account (MSA) has been added (a few
days after you receive e-mail notification) you will receive automatic updates of
new preview versions from the Microsoft Store.

Install winget on Windows Sandbox

Windows Sandbox provides a lightweight desktop environment to safely run
applications in isolation. Software installed inside the Windows Sandbox environment
remains "sandboxed" and runs separately from the host machine. Windows Sandbox
does not include winget, nor the Microsoft Store app, so you will need to download the
latest winget package from the winget releases page on GitHub.

To install the stable release of winget on Windows Sandbox, follow these steps from a
Windows PowerShell command prompt:

PowerShell

$progressPreference = 'silentlyContinue'
Write-Information "Downloading WinGet and its dependencies..."
Invoke-WebRequest -Uri https://aka.ms/getwinget -OutFile
Microsoft.DesktopAppInstaller_8wekyb3d8bbwe.msixbundle
Invoke-WebRequest -Uri
https://aka.ms/Microsoft.VCLibs.x64.14.00.Desktop.appx -OutFile
Microsoft.VCLibs.x64.14.00.Desktop.appx
Invoke-WebRequest -Uri https://github.com/microsoft/microsoft-ui-
xaml/releases/download/v2.8.6/Microsoft.UI.Xaml.2.8.x64.appx -OutFile
Microsoft.UI.Xaml.2.8.x64.appx
Add-AppxPackage Microsoft.VCLibs.x64.14.00.Desktop.appx
Add-AppxPackage Microsoft.UI.Xaml.2.8.x64.appx
Add-AppxPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe.msixbundle

If you would like a preview or different version of the Package Manager, go to

https://github.com/microsoft/winget-cli/releases . Copy the URL of the version you
would prefer and update the above Uri.

For more information on Windows Sandbox, including how to install a sandbox and
what to expect from it's usage, see the Windows Sandbox docs.

Administrator considerations
Installer behavior can be different depending on whether you are running winget with
administrator privileges.

When running winget without administrator privileges, some applications may

require elevation to install. When the installer runs, Windows will prompt you to
elevate. If you choose not to elevate, the application will fail to install.

When running winget in an Administrator Command Prompt, you will not see
elevation prompts if the application requires it. Always use caution when running
your command prompt as an administrator, and only install applications you trust.

Use winget
After App Installer is installed, you can run winget by typing 'winget' from a Command
Prompt.

One of the most common usage scenarios is to search for and install a favorite tool.

1. To search for a tool, type winget search <appname> .

2. After you have confirmed that the tool you want is available, you can install the
tool by typing winget install <appname> . The winget tool will launch the installer
and install the application on your PC.

3. In addition to install and search, winget provides a number of other commands

that enable you to show details on applications, change sources, and validate
 packages. To get a complete list of commands, type: winget --help .

Some users have reported issues with the client not being on their PATH.

Commands
The current preview of the winget tool supports the following commands.

ﾉ Expand table

Command Description

info Displays metadata about the system (version numbers, architecture, log location,
etc). Helpful for troubleshooting.

install Installs the specified application.

show Displays details for the specified application.

source Adds, removes, and updates the Windows Package Manager repositories accessed
by the winget tool.

search Searches for an application.

list Display installed packages.

upgrade Upgrades the given package.

uninstall Uninstalls the given package.

 Command Description

hash Generates the SHA256 hash for the installer.

validate Validates a manifest file for submission to the Windows Package Manager
repository.

settings Open settings.

features Shows the status of experimental features.

export Exports a list of the installed packages.

import Installs all the packages in a file.

pin Manage package pins.

configure Configures the system into a desired state.

download Downloads the specified application's installer.

Options
The winget tool supports the following options.

ﾉ Expand table

Option Description

-v, -- Returns the current version of winget.

version

--info Provides you with all detailed information on winget, including the links to the
license, privacy statement, and configured group policies.

-?, --help Shows additional help for winget.

Supported installer formats

The winget tool supports the following types of installers:

EXE (with Silent and SilentWithProgress flags)

ZIP
INNO
NULLSOFT
MSI
WIX
 APPX
MSIX
BURN
PORTABLE

Scripting winget
You can use the following syntax to install multiple applications in a single command.

USAGE: winget install <query1> <query2> ...

Example
CMD

winget install Microsoft.WindowsTerminal Microsoft.PowerToys

Microsoft.VisualStudioCode

７ Note

When scripted, winget will launch the applications in the specified order. When an
installer returns success or failure, winget will launch the next installer. If an installer
launches another process, it is possible that it will return to winget prematurely.
This will cause winget to install the next installer before the previous installer has
completed.

Debugging and troubleshooting

winget provides logging to help diagnose issues. For troubleshooting and details on
logging, see Debugging and troubleshooting.

Missing tools
If the community repository does not include your tool or application, please submit a
package to our repository . By adding your favorite tool, it will be available to you and
everyone else.

Customize winget settings

You can configure the winget command line experience by modifying the settings.json
file. For more information, see https://aka.ms/winget-settings . Note that the settings
are still in an experimental state and not yet finalized for the preview version of the tool.

Open source details

The winget tool is open source software available on GitHub in the repo
https://github.com/microsoft/winget-cli/ . The source for building the client is located
in the src folder .

The source for winget is contained in a Visual Studio 2019 C++ solution. To build the
solution correctly, install the latest Visual Studio with the C++ workload .

We encourage you to contribute to the winget source on GitHub. You must first agree
to and sign the Microsoft CLA.

Troubleshooting
The winget-cli repo maintains a list of common issues and common errors, along with
recommendations on how to resolve:

common issues -- not recognized, failed to run, App Installer version or PATH
variable need updating
common errors -- Error 0x801901a0, 0x80d03002, 0x80070490

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
configure command (winget)
Article • 09/28/2023

The configure command of the winget tool uses a WinGet Configuration file to begin
setting up your Windows machine to a desired development environment state.

２ Warning

Do not run a WinGet Configuration file without first reviewing the contents of the
file and verifying the credibility of the related resources. See How to check the
trustworthiness of a WinGet Configuration file.

Prerequisites
Windows 10 RS5 or later, and Windows 11.
WinGet version v1.6.2631 or later .

Aliases
The following aliases are available for this command:

configuration

Usage
winget configure -f <C:/Users/<username>/winget-configs/config-file-name.dsc.yaml>

Once you have identified the winget configuration file that you are interested in using,
confirmed the safety and trustworthiness of that file, and downloaded the file to your
local machine, you can use the winget configure command to initiate the set up of your
configuration.

Arguments and options

The following arguments are available:

Argument Description

-f,--file The path to the winget configuration file.

 Argument Description

-?, --help Gets additional help on this command.

--wait Prompts the user to press any key before exiting.

--verbose, --verbose-logs Enables verbose logging for winget.

--disable-interactivity Disable interactive prompts.

configure subcommands
The winget configure command includes a number of subcommands, including:

winget configure show : Displays the details of a configuration file. Usage: winget
configure show -f <C:/Users/<username>/winget-configs/config-file-

name.dsc.yaml> . Running the command: winget configuration show

configuration.dsc.yaml will display the details of the configuration in the current

working directory.
winget configure test : Checks the system against the desired state, displaying

whether the current system state conforms with the desired state defined in the
associated configuration file. Usage: winget configure test -f
<C:/Users/<username>/winget-configs/config-file-name.dsc.yaml> .
winget configure validate : Validates a configuration file. Usage: winget configure

validate [-f] <file> [<options>] .

Related topics
WinGet Configuration overview
How to author a WinGet Configuration file
How to check the trustworthiness of a WinGet Configuration file
Use the winget tool to install and manage applications
Submit packages to Windows Package Manager
download command (winget)
Article • 11/16/2023

The download command of the winget tool downloads the installer from the selected
package. Use the search command and the show command to identify the package
installer you want to download .

The download command requires that you specify the exact string to download. If there
is any ambiguity, you will be prompted to further filter the download command to an
exact application.

７ Note

By default, the download command will download the appropriate installer to the
user's Downloads folder. Use the --download-directory option to specify a custom
download path.

７ Note

As of March 2024, the download option does not support the msstore source.

Usage
winget download [[-q] <query>] [\<options>]
Arguments
The following arguments are available.

ﾉ Expand table

Argument Description

-q,--query The query used to search for an app.

７ Note

The query argument is positional. Wild-card style syntax is not supported. This is
most often the string of characters you expect to uniquely identify the package you
wish to download.

Options
The options allow you to customize the download experience to meet your needs.

ﾉ Expand table
Option Description

-d, --download- Directory where the installers are downloaded to.

directory

-m, --manifest Must be followed by the path to the manifest (YAML) file.

--id Limits the download to the ID of the application.

--name Limits the search to the name of the application.

--moniker Limits the search to the moniker listed for the application.

-v, --version Enables you to specify an exact version to install. If not specified, latest
will download the highest versioned application.

-s, --source Restricts the search to the source name provided. Must be followed by
the source name.

--scope Allows you to specify if the installer should target user or machine scope.
See known issues relating to package installation scope.

-a, --architecture Select the architecture to download.

--installer-type Select the installer type to download.

-e, --exact Uses the exact string in the query, including checking for case-sensitivity.
It will not use the default behavior of a substring.

--locale Specifies which locale to use (BCP47 format).

-o, --log Directs the logging to a log file. You must provide a path to a file that you
have the write rights to.

--ignore-security- Ignore the installer hash check failure. Not recommended.

hash

--accept-package- Used to accept the license agreement, and avoid the prompt.
agreements

--accept-source- Used to accept the source license agreement, and avoid the prompt.
agreements

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs
 Option Description

--disable- Disable interactive prompts.

interactivity

Example queries
The following example downloads a specific version of an application from its ID.

CMD

winget download --id Microsoft.PowerToys --version 0.15.2

The following example downloads an application with a specific installer type.

CMD

winget download --id Microsoft.WingetCreate --installer-type msix

The following example downloads an application by architecture and scope to a specific

download directory.

CMD

winget install --id Microsoft.PowerToys --scope machine --architecture x64 -

-download-directory <Path>

Related topics
Use the winget tool to install and manage applications
Submit packages to Windows Package Manager

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
export command (winget)
Article • 07/28/2023

The export command of the winget tool exports a JSON file of apps to a specified file.
The export command uses JSON as the format. You can find the schema for the JSON
file used by winget in the Windows Package Manager Client repo on GitHub .

The export combined with the import command allows you to batch install applications
on your PC.

The export command is often used to create a file that you can share with other
developers, or for use when restoring your build environment.

Usage
winget export [-o] <output> [<options>]

Arguments
The following arguments are available.

Argument Description

-o,--output Path to the JSON file to be created

Options
The options allow you to customize the export experience to meet your needs.

Option Description

-s, --source [Optional] Specifies a source to export files from. Use this option when you
only want files from a specific source.

--include-versions [Optional] Includes the version of the app currently installed. Use this
option if you want a specific version. By default, unless specified, import will
use latest.

--accept-source- Used to accept the source license agreement, and avoid the prompt.
agreements

-?,--help Shows help about the selected command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs

--disable- Disable interactive prompts.

interactivity

JSON schema
The driving force behind the export command is the JSON file. You can find the schema
for the JSON file in the Windows Package Manager Client repo on GitHub .

The JSON file includes the following hierarchy.

Entry Description

Sources The sources application manifests come from.

Packages The collection of packages to install.

PackageIdentifier The Windows Package Manager package identifier used to specify the
package.

Version [Optional] The specific version of the package to install.

Exporting files
When the Windows Package Manager exports the JSON file, it attempts to export all the
applications installed on the PC. If the winget export command is not able to match an
application to an application from an available source, the export command will show a
warning.

７ Note

Matching an application depends on metadata in the manifest from a configured

source, and metadata in Add / Remove Programs in Windows based on the
package installer.

After the export is complete, you can edit the resulting JSON file in your favorite editor.
You can remove apps you do not wish to import in the future.

Related topics
Use the winget tool to install and manage applications
features command (winget)
Article • 07/26/2023

The features command of the winget tool displays a list of the experimental features
available with your version of the Windows Package Manager. Experimental features are
only available in preview builds. Instructions for obtaining a preview build can be found
in the GitHub repository .

Each feature can be turned on individually by enabling the features through settings.

You can find the latest up to date information features on the experimental features
web page.

Usage
winget features

Notice above that the status of each feature is listed. If the feature is disabled you will
not be able to use it. If the feature is enabled you will notice that the command will be
available to you through winget.

To enabled any disabled features, go to settings and enable the feature.

７ Note

Features may be managed by group policy. You can use the winget --info
command to view any policies in effect on your system.
hash command (winget)
Article • 07/28/2023

The hash command of the winget tool generates the SHA256 hash for an installer. This
command is used if you need to create a manifest file for submitting software to the
Microsoft Community Package Manifest Repository on GitHub.

In addition, the hash command also supports generating a SHA256 certificate hash for
MSIX files.

Usage
winget hash [--file] \<file> [\<options>]

The hash sub-command can only run on a local file. To use the hash sub-command,
download your installer to a known location. Then pass in the file path as an argument
to the hash sub-command.
Arguments
The following arguments are available:

Argument Description

-f,--file The path to the file to be hashed.

Options
The options allow you to customize the hash experience to meet your needs.

Option Description

-m,--msix Specifies that the hash command will also create the SHA-256
SignatureSha256 for use with MSIX installers.

-?, --help Gets additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs

--disable- Disable interactive prompts.

interactivity

Related topics
Use the winget tool to install and manage applications
Submit packages to Windows Package Manager
help command (winget)
Article • 11/01/2021

The help command of the winget tool displays help for all the supported commands
and sub commands. In addition, you can pass the --help argument to any other
command to get details about all additional command options.

Usage
Display help for all commands: winget --help or winget -?
View options for a command: winget <command> --help or winget <command> -?

Related topics
Use the winget tool to install and manage applications
import command (winget)
Article • 07/28/2023

The import command of the winget tool imports a JSON file of apps to install. The
import command combined with the export command allows you to batch install
applications on your PC.

The import command is often used to share your developer environment or build up
your PC image with your favorite apps.

Usage
winget import [-i] <import-file> [<options>]

Arguments
The following arguments are available.

Argument Description

-i,--import-file JSON file describing the packages to install.

Options
The options allow you to customize the import experience to meet your needs.
 Option Description

--ignore-unavailable Suppresses errors if the app requested is unavailable.

--ignore-versions Ignores versions specified in the JSON file and installs the latest
available version.

--no-upgrade Skips upgrade if an installed version already exists.

--accept-package- Used to accept the license agreement, and avoid the prompt.
agreements

--accept-source- Used to accept the source license agreement, and avoid the
agreements prompt.

-?,--help Shows help about the selected command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

JSON Schema
The driving force behind the import command is the JSON file. You can find the schema
for the JSON file in the Windows Package Manager Client repo on GitHub .

The JSON file includes the following hierarchy.

Entry Description

Sources The sources application manifests come from.

Packages The collection of packages to install.

PackageIdentifier The Windows Package Manager package identifier used to specify the
package.

Version [optional] The specific version of the package to install.

Importing files
When the Windows Package Manager imports the JSON file, it attempts to install the
specified applications in a serial fashion. If the application is not available or the
application is already installed, it will notify the user of that case.

In the previous example, the Microsoft.WindowsTerminal was already installed.

Therefore the import command skipped the installation.
info command (winget)
Article • 08/04/2022

The info command of the winget tool displays metadata about the system, including
version numbers, system architecture, log location, links to legal agreements, and Group
Policy state.

When submitting an issue to the winget repository on GitHub, this information is

helpful for troubleshooting. It may also explain why the winget client behaves differently
than expected in the case of Group Policy configuration.

Usage
winget --info

Result fields include:

Windows Package Manager version number installed

System architecture type
MSIX package version number (winget is delivered as a part of the "App Installer"
package)
Log file location
Links to privacy statement, license agreement, third party notices, homepage, and
store terms
 Group policy and state - this will only appear if a policy has been manually
configured. (Learn more about how to configure Group Policies for Windows
Package Manager ).

Related topics
Use the winget tool to install and manage applications
install command (winget)
Article • 11/15/2023

The install command of the winget tool installs the specified application. Use the search
command to identify the application you want to install.

The install command requires that you specify the exact string to install. If there is any
ambiguity, you will be prompted to further filter the install command to an exact
application.

Usage
winget install [[-q] \<query> ...] [\<options>]

Aliases
The following aliases are available for this command:

add

Arguments
The following arguments are available.
 Argument Description

-q,--query The query used to search for an app.

７ Note

The query argument is positional. Wild-card style syntax is not supported. This is
most often the string of characters you expect to uniquely identify the package you
wish to install.

Options
The options allow you to customize the install experience to meet your needs.

Option Description

-m, --manifest Must be followed by the path to the manifest (YAML) file. You can use
the manifest to run the install experience from a local YAML file.

--id Limits the install to the ID of the application.

--name Limits the search to the name of the application.

--moniker Limits the search to the moniker listed for the application.

-v, --version Enables you to specify an exact version to install. If not specified, latest
will install the highest versioned application.

-s, --source Restricts the search to the source name provided. Must be followed by
the source name.

--scope Allows you to specify if the installer should target user or machine
scope. See known issues relating to package installation scope.

-a, --architecture Select the architecture to install.

--installer-type Select the installer type to install. See supported installer types for
WinGet client.

-e, --exact Uses the exact string in the query, including checking for case-
sensitivity. It will not use the default behavior of a substring.

-i, --interactive Runs the installer in interactive mode. The default experience shows
installer progress.

-h, --silent Runs the installer in silent mode. This suppresses all UI. The default
experience shows installer progress.
 Option Description

--locale Specifies which locale to use (BCP47 format).

-o, --log Directs the logging to a log file. You must provide a path to a file that
you have the write rights to.

--custom Arguments to be passed on to the installer in addition to the defaults.

--override A string that will be passed directly to the installer.

-l, --location Location to install to (if supported).

--ignore-security-hash Ignore the installer hash check failure. Not recommended.

--ignore-local-archive- Ignore the malware scan performed as part of installing an archive

malware-scan type package from local manifest.

--dependency-source Find package dependencies using the specified source.

--accept-package- Used to accept the license agreement, and avoid the prompt.
agreements

--accept-source- Used to accept the source license agreement, and avoid the prompt.
agreements

--no-upgrade Skips upgrade if an installed version already exists.

--header Optional Windows-Package-Manager REST source HTTP header.

-r, --rename The value to rename the executable file (portable)

--uninstall-previous Uninstall the previous version of the package during upgrade

--force Direct run the command and continue with non security related issues.

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose- Used to override the logging setting and create a verbose log.
logs

--disable-interactivity Disable interactive prompts.

Example queries
The following example installs a specific version of an application.
 CMD

winget install powertoys --version 0.15.2

The following example installs an application from its ID.

CMD

winget install --id Microsoft.PowerToys

The following example installs an application by version and ID.

CMD

winget install --id Microsoft.PowerToys --version 0.15.2

Multiple selections
If the query provided to winget does not result in a single application, then winget will
display the results of the search. This will provide you with the additional data necessary
to refine the search for a correct install.

The best way to limit the selection to one file is to use the id of the application
combined with the exact query option. For example:

CMD

winget install --id Git.Git -e

If multiple sources are configured, it is possible to have duplicate entries. Specifying a

source is required to further disambiguate.

CMD

winget install --id Git.Git -e --source winget

The msstore source uses unique identifiers as the "Id" for packages. These do not
require the exact query toption. For example:

CMD

winget install XP9KHM4BK9FZ7Q -s msstore

Local install
The manifest option enables you to install an application by passing in a YAML file
directly to the client. If the manifest is a multi-file manifest, the directory containing the
files must be used. The manifest option has the following usage.

Usage: winget install --manifest \<path>

Option Description

-m, --manifest The path to the manifests of the application to install.

７ Note

Installing packages from local manifest files may have risks. As an extra measure of
precaution this feature needs to be enabled by an administrator. To enable this
feature run winget settings --enable LocalManifestFiles . To disable this feature
run winget settings --disable LocalManifestFiles .

Log files
The log files for winget unless redirected, will be located in the following folder:
%temp%\AICLI\*.log

License Agreements
Some applications when installed will require the user to agree to the license or other
agreements before installing. When this occurs, the Windows Package Manager will
prompt the user to agree to the agreements. If the user does not agree, the application
will not install.

From the command line, you can auto accept the agreements by passing the following
option --accept-package-agreements on the command line. This can be beneficial
when scripting the Windows Package Manager.

Related topics
Use the winget tool to install and manage applications
list command (winget)
Article • 07/28/2023

The list command of the winget tool displays a list of the applications currently installed
on your computer. The list command will show apps that were installed through the
Windows Package Manager as well as apps that were installed by other means.

The list command will also display if an update is available for an app, and you can use
the upgrade command to update the app.

The list command also supports filters which can be used to limit your list query.

Aliases
The following aliases are available for this command:

ls

Usage
winget list [[-q] \<query>] [\<options>]

７ Note

If you want to list all apps with available updates use winget upgrade (without any
arguments).
Arguments
The following arguments are available.

Argument Description

-q,--query The query used to search for an app.

７ Note

The query argument is positional. Wild-card style syntax is not supported. This is
most often the string of characters you expect to help find the installed package
you are searching for.

Options
The options allow you to customize the list experience to meet your needs.

Option Description

--id Limits the list to the ID of the application.

--name Limits the list to the name of the application.

--moniker Limits the list to the moniker listed for the application.

-s, --source Restricts the list to the source name provided. Must be followed by the
source name.

--tag Filters results by tags.

--cmd, --command Filters results by command specified by the application.

-n, --count Limits the number of apps displayed in one query.

-e, --exact Uses the exact string in the list query, including checking for case-
sensitivity. It will not use the default behavior of a substring.

--scope Select installed package scope filter (user or machine).

--header Optional Windows-Package-Manager REST source HTTP header.

--accept-source- Used to accept the source license agreement, and avoid the prompt.
agreements

--upgrade-available Lists only packages which have an upgrade available.

 Option Description

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs

--disable- Disable interactive prompts.

interactivity

Example queries
The following example lists a specific version of an application.

The following example lists all application by ID from a specific source.

The following example limits the output of list to 9 apps.

List with update

As stated above, the list command allows you to see what apps you have installed that
have updates available.

In the image below, you will notice the preview version of Terminal has an update
available.

The list command will show not only the update version available, but the source that
the update is available from.

If there are no updates available, list will only show you the currently installed version
and the update column will not be displayed.

Use the winget tool to list and manage applications

pin command (winget)
Article • 07/28/2023

The winget pin command allows you to limit the Windows Package Manager from
upgrading a package to specific ranges of versions, or it can prevent it from upgrading a
package altogether. A pinned package may still upgrade on its own and be upgraded
from outside the Windows Package Manager.

Pin Types
WinGet supports three types of package pins:

Pinning: The package is excluded from winget upgrade --all but allows winget
upgrade <package> . You can use the --include-pinned argument to let winget

upgrade --all include pinned packages.

Blocking: The package is blocked from winget upgrade --all or winget upgrade
<package> , you will have to unpin the package to let WinGet perform an upgrade.

The --force option can be used to override the pin's behavior.

Gating: The package is pinned to a specific version or version range. You can
specify an exact version you want a package to be pinned to or you can utilize the
wildcard character * as the last version part to specify a version range. For
example, if a package is pinned to version 1.2.* , any version between 1.2.0 to
1.2.x is considered valid. The --force option can be used to override the pin's

behavior.

Usage
Windows Command Prompt

winget pin <subcommand> <options>

Options
The following options are available.
 Option Description

-?, --help Gets additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

Subcommands
The pin command supports the following subcommands.

Subcommand Description

add Add a new pin.

remove Remove a package pin.

list List current pins.

reset Reset pins

add
The add subcommand adds a new pin. This subcommand requires that you specify the
exact package to pin. If there is any ambiguity, you will be prompted to further filter the
add subcommand to an exact application.

Usage:

Windows Command Prompt

winget pin add [[-q] <query>] [<options>]

Arguments

Argument Description

-q,--query The query used to search for an app.

Options
The options allow you to customize adding pins to meet your needs.

Option Description

--id Limits the search to the ID of the application.

--name Limits the search to the name of the application.

--moniker Limits the search to the moniker listed for the application.

--tag Limits the search to the tag listed for the application.

--cmd, --command Limits the search to the command of the application.

-v, --version Enables you to specify an exact version to pin. The wildcard * can be used
as the last version part. Changes pin behavior to be gating.

-s, --source Restricts the search to the source name provided. Must be followed by the
source name.

-e, --exact Uses the exact string in the query, including checking for case-sensitivity.
It will not use the default behavior of a substring.

--force Direct run the command and continue with non security related issues.

--blocking Block from upgrading until the pin is removed, preventing override
arguments. Changes pin behavior to be blocking.

--installed Pin a specific installed version

--accept-source- Used to accept the source license agreement, and avoid the prompt.
agreements

--header Optional Windows-Package-Manager REST source HTTP header.

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting

--logs, --open-logs Open the default logs location.

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs

--disable- Disable interactive prompts.

interactivity

Examples
The following example adds a pin for an application. Adding this pin will prevent this
package from being upgraded when calling winget upgrade --all . Use the --include-
pinned argument with winget upgrade --all to include any pinned packages.

Windows Command Prompt

winget pin add powertoys

The following example adds a blocking pin for an application using its ID. Adding a
blocking pin will prevent this package from being upgraded when calling winget
upgrade --all or winget upgrade <package> . You will need to unblock the package to let

WinGet perform an upgrade.

Windows Command Prompt

winget pin add --id Microsoft.PowerToys --blocking

The following example adds a gating pin for an application using its ID. Adding a gating
pin will prevent upgrades that upgrade the package version outside of a specific version
or the gated wildcard range.

Windows Command Prompt

winget pin add --id Microsoft.PowerToys --version 0.70.*

remove
The remove subcommand removes a pin. This subcommand requires that you specify
the exact package pin to remove. If there is any ambiguity, you will be prompted to
further filter the remove subcommand to an exact application.

Usage:

Windows Command Prompt

winget pin remove [[-q] <query>] [<options>]

Arguments
 Argument Description

-q,--query The query used to search for an app.

Options
The options allow you to customize removing pins to meet your needs.

Option Description

--id Limits the search to the ID of the application.

--name Limits the search to the name of the application.

--moniker Limits the search to the moniker listed for the application.

--tag Limits the search to the tag listed for the application.

--cmd, --command Limits the search to the command of the application.

-s, --source Restricts the search to the source name provided. Must be followed by
the source name.

-e, --exact Uses the exact string in the query, including checking for case-sensitivity.
It will not use the default behavior of a substring.

--installed Pin a specific installed version

--accept-source- Used to accept the source license agreement, and avoid the prompt.
agreements

--header Optional Windows-Package-Manager REST source HTTP header.

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting

--logs, --open-logs Open the default logs location.

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs

--disable- Disable interactive prompts.

interactivity

Examples
The following example removes a pin for an application.
 Windows Command Prompt

winget pin remove powertoys

The following example removes a pin for an application using its ID.

Windows Command Prompt

winget pin remove --id Microsoft.PowerToys

list
The list subcommand lists all current pins.

Usage:

Windows Command Prompt

winget pin list [[-q] <query>] [<options>]

Arguments

Argument Description

-q,--query The query used to search for an app.

Options
The options allow you to customize listing pins to meet your needs.

Option Description

--id Limits the search to the ID of the application.

--name Limits the search to the name of the application.

--moniker Limits the search to the moniker listed for the application.

--tag Limits the search to the tag listed for the application.

--cmd, --command Limits the search to the command of the application.

-s, --source Restricts the search to the source name provided. Must be followed by
the source name.
 Option Description

-e, --exact Uses the exact string in the query, including checking for case-sensitivity.
It will not use the default behavior of a substring.

--accept-source- Used to accept the source license agreement, and avoid the prompt.
agreements

--header Optional Windows-Package-Manager REST source HTTP header.

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting

--logs, --open-logs Open the default logs location.

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs

--disable- Disable interactive prompts.

interactivity

Examples
The following example lists all current pins.

Windows Command Prompt

winget pin list

The following example lists a specific package pin.

Windows Command Prompt

winget pin list --id Microsoft.PowerToys

reset
The reset subcommand resets all pins.

Using this subcommand without the --force argument will show the pins that would be
removed.

To reset all pins, include the --force argument.

Usage:
The following example shows all pins that would be reset.

Windows Command Prompt

winget pin reset

The following example resets all existing pins.

Windows Command Prompt

winget pin reset --force

search command (winget)
Article • 07/31/2023

The search command of the winget tool can be used to show all applications available
for installation. It can also be used to identify the string or ID needed to install a specific
application.

For example, the command winget search vscode will return all applications available
that include "vscode" in the description or tag.

The search command includes parameters for filtering down the applications returned
to help you identify the specific application you are looking for, including: --id , --name ,
--moniker , --tag , --command , or --source . See descriptions below or use winget search
--help in your command line.

Usage
winget search [[-q] \<query>] [\<options>]

Aliases
The following aliases are available for this command:

find
Arguments
The following arguments are available.

Argument Description

-q,--query The query flag is the default argument used to search for an app. It does not need to
be specified. Entering the command winget search foo will default to using --query
so including it is unnecessary.

７ Note

The query argument is positional. Wild-card style syntax is not supported. This is
most often the string of characters you expect to help find the package you are
searching for.

Show all
To show all of the winget packages available, use the command:

winget search --query ""

In PowerShell, you will need to escape the quotes, so this command becomes:

PowerShell

winget search -q `"`"

７ Note

This is a change from previous versions of winget which supported winget search
with no filters or options displaying all available packages. You can also search for
all applications in another source by passing in the source option.

Search strings
Search strings can be filtered with the following options.
 Option Description

--id Limits the search to the ID of the application. The ID includes the
publisher and the application name.

--name Limits the search to the name of the application.

--moniker Limits the search to the moniker specified.

--tag Limits the search to the tags listed for the application.

--cmd, --command Limits the search to the commands listed for the application.

-s, --source Find package using the specified source name.

-n, --count Show no more than specified number of results (between 1 and 1000).

-e, --exact Uses the exact string in the query, including checking for case-sensitivity.
It will not use the default behavior of a substring.

--header Optional Windows-Package-Manager REST source HTTP header.

--accept-source- Accept all source agreements during source operations.

agreements

--versions Show available versions of the package.

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs

-?, --help Gets additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--disable- Disable interactive prompts.

interactivity

The string will be treated as a substring. The search by default is also case insensitive.
For example, winget search micro could return the following:

Microsoft
Microscope
MyMicro

Searching across multiple sources

If you want to narrow results down to a specific source, just pass the --source or -s
parameter and specify what you want. For example, you might want to see if Visual
Studio Code is in the store by running winget search “Visual Studio Code” -s msstore .
This search uses "Visual Studio Code" as the query.

Related topics
Use the winget tool to install and manage applications
settings command (winget)
Article • 08/03/2022

The settings command of the winget tool allows you to customize your Windows
Package Manager client experience. You can change defaults and try out experimental
features that are enabled in your client.

The settings command will launch your default text editor. Windows by default will
launch Notepad as an option. We recommend using a tool like Visual Studio code .

７ Note

You can easily install Visual Studio Code by typing winget install
Microsoft.VisualStudioCode

Aliases
The following aliases are available for this command:

config

Use the winget settings command

Launch your default JSON editing tool: winget settings

When you launch the settings for the first time, there will be no settings specified. At the
top of the JSON file we provide a link where you can discover the latest experimental
features and settings.

The code snippet below is an example of what your settings file should look like if you
would like to enable or modify some of these experimental features and settings.

JSON

{
"$schema": "https://aka.ms/winget-settings.schema.json",

// For documentation on these settings, see: https://aka.ms/winget-

settings
"experimentalFeatures": {
"dependencies": true,
"directMSI": false,
 "zipInstall": false,
},
"visual": {
"progressBar": "rainbow"
},
"source": {
"autoUpdateIntervalInMinutes": 5
},
}

We have also defined a schema for the settings file. This allows you to use TAB to
discover settings and syntax if your JSON editor supports JSON schemas.

７ Note

Experimental features are only available in preview builds. Instructions for obtaining
a preview build can be found in the GitHub repository .

Updating settings
The following settings are available for the 1.0 release of the Windows Package
Manager.

source settings
The source settings involve configuration to the WinGet source.

JSON

"source": {
"autoUpdateIntervalInMinutes": 3
},

autoUpdateIntervalInMinutes
A positive integer represents the update interval in minutes. The check for updates only
happens when a source is used. A zero will disable the check for updates to a source.
Any other values are invalid.

Disable: 0
Default: 5

To manually update the source use winget source update .

visual settings
The visual settings involve visual elements that are displayed by WinGet

JSON

"visual": {
"progressBar": "accent"
},

progressBar

Color of the progress bar that WinGet displays when not specified by arguments.

accent (default)
retro
rainbow

installBehavior settings
The installBehavior settings affect the default behavior of installing and upgrading
(where applicable) packages.

disableInstallNotes
The disableInstallNotes behavior affects whether installation notes are shown after a
successful install. Defaults to false if value is not set or is invalid.

JSON

"installBehavior": {
"disableInstallNotes": true
},

portablePackageUserRoot setting
The portablePackageUserRoot setting affects the default root directory where packages
are installed to under User scope. This setting only applies to packages with the
portable installer type. Defaults to %LOCALAPPDATA%/Microsoft/WinGet/Packages/ if value

is not set or is invalid.

 Note: This setting value must be an absolute path.

JSON

"installBehavior": {
"portablePackageUserRoot": "C:/Users/FooBar/Packages"
},

portablePackageMachineRoot setting
The portablePackageMachineRoot setting affects the default root directory where
packages are installed to under Machine scope. This setting only applies to packages
with the portable installer type. Defaults to %PROGRAMFILES%/WinGet/Packages/ if value is
not set or is invalid.

Note: This setting value must be an absolute path.

JSON

"installBehavior": {
"portablePackageMachineRoot": "C:/Program Files/Packages/Portable"
},

preferences and requirements settings

Some of the settings are duplicated under preferences and requirements .

The preferences setting affects how the various available options are sorted when
choosing the one to act on. For example, the default scope of package installs is
for the current user, but if that is not an option then a machine level installer will
be chosen.
The requirements setting filters the options, potentially resulting in an empty list
and a failure to install. In the previous example, a user scope requirement would
result in no applicable installers and an error.

Any arguments passed on the command line will effectively override the matching
requirement setting for the duration of that command.

scope
The scope behavior affects the choice between installing a package for the current user
or for the entire machine. The matching parameter is --scope , and uses the same values
( user or machine ). See known issues relating to package installation scope.

JSON

"installBehavior": {
"preferences": {
"scope": "user"
}
},

locale
The locale behavior affects the choice of installer based on installer locale. The
matching parameter is --locale , and uses bcp47 language tag.

JSON

"installBehavior": {
"preferences": {
"locale": [ "en-US", "fr-FR" ]
}
},

architectures

The architectures behavior affects what architectures will be selected when installing a
package. The matching parameter is --architecture . Note that only architectures
compatible with your system can be selected.

JSON

"installBehavior": {
"preferences": {
"architectures": ["x64", "arm64"]
}
},

installerTypes

The installerTypes behavior affects what installer types will be selected when installing
a package. The matching parameter is --installer-type .
 JSON

"installBehavior": {
"preferences": {
"installerTypes": ["msix", "msi"]
}
},

uninstallBehavior
The uninstallBehavior settings affect the default behavior of uninstalling (where
applicable) packages.

purgePortablePackage
The purgePortablePackage behavior affects the default behavior for uninstalling a
portable package. If set to true , uninstall will remove all files and directories relevant to
the portable package. This setting only applies to packages with the portable installer
type. Defaults to false if value is not set or is invalid.

JSON

"uninstallBehavior": {
"purgePortablePackage": true
},

downloadBehavior
The downloadBehavior settings affect the default behavior of downloading packages.

defaultDownloadDirectory

The defaultDownloadDirectory setting affects the default directory where packages are
downloaded to. Defaults to %USERPROFILE%/Downloads if value is not set or is invalid.

Note: This setting value must be an absolute path.

JSON

"downloadBehavior": {
"defaultDownloadDirectory": "C:/Users/FooBar/Downloads"
 },

telemetry settings
The telemetry settings control whether winget writes ETW events that may be sent to
Microsoft on a default installation of Windows.

See details on telemetry , and our primary privacy statement .

disable

JSON

"telemetry": {
"disable": true
},

If set to true, the telemetry.disable setting will prevent any event from being written by
the program.

network settings
The network settings influence how winget uses the network to retrieve packages and
metadata.

downloader

The downloader setting controls which code is used when downloading packages. The
default is default , which may be any of the options based on our determination.

wininet uses the WinINet APIs, while do uses the Delivery Optimization service.

JSON

"network": {
"downloader": "do"
}

logging settings
The logging settings control the level of detail in log files. --verbose-logs will override
this setting and always creates a verbose log.

JSON

"logging": {
"level": "verbose"
}

level

The following logging levels are available. Defaults to info if the value is not set or is
invalid.

verbose
info
warning
error
critical

Enabling experimental features

To discover which experimental features are available, go to https://aka.ms/winget-
settings where you can see the experimental features available to you.
show command (winget)
Article • 10/17/2023

The show command of the winget tool displays details for the specified application,
including details on the source of the application as well as the metadata associated
with the application.

The show command only shows metadata that was submitted with the application. If
the submitted application excludes some metadata, then the data will not be displayed.

Aliases
The following aliases are available for this command:

view

Usage
winget show [[-q] \<query>] [\<options>]

Arguments
The following arguments are available.
 Argument Description

-q,--query The query used to search for an application.

７ Note

The query argument is positional. Wild-card style syntax is not supported. This is
most often the string of characters you expect to help find the package you are
searching for.

Options
The following options are available.

Option Description

-m,--manifest The path to the manifest of the application to show.

--id Filter results by ID.

--name Filter results by name.

--moniker Filter results by application moniker.

-v,--version Use the specified version. The default is the latest version.

-s,--source Find the application using the specified source.

-e,--exact Find the application using exact match.

--scope Select install scope (user or machine).

-a,--architecture Select the architecture to show.

--installer-type Select the installer type to show. See supported installer types for
WinGet client.

--locale Locale to use (BCP47 format).

--versions Show available versions of the application.

--header Optional Windows-Package-Manager REST source HTTP header.

--accept-source- Used to accept the source license agreement, and avoid the prompt.
agreements

-?,--help Shows help about the selected command.

 Option Description

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

Multiple selections
If the query provided to winget does not result in a single application, then winget will
display the results of the search. This will provide you with the additional data necessary
to refine the search.

Results of show
If a single application is detected, the following data will be displayed.

Metadata

Value Description

Version Version of the application.

Publisher Publisher of the application.

Moniker AppMoniker of the application.

Description Description of the application.

Homepage Homepage of the application.

License License of the application.

LicenseUrl The URL to the license file of the application.

Installer details

Value Description

Type The type of installer.

Download Url The Url of the installer.

Value Description

SHA256 The Sha-256 of the installer.

Related topics
Use the winget tool to install and manage applications
The winget source command
Article • 07/28/2023

The winget tool source command allows you to manage sources for Windows Package
Manager. With the source command, you can add, list, update, remove, reset, or export
repositories.

A source repository provides the data for you to discover and install applications. Only
use secure, trusted source locations.

Windows Package Manager specifies the following two default repositories, which you
can list by using winget source list .

msstore - The Microsoft Store catalog.

winget - The Windows Package Manager app repository.

Usage
Windows Command Prompt

winget source <subcommand> <options>

Arguments
The following arguments are available.

Argument Description

-?, --help Gets additional help on this command.

The following image shows help for the source command:

Options
The following options are available.

Option Description

-?,--help Shows help about the selected command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

Subcommands
The source command supports the following subcommands.

Subcommand Description

add Adds a new source.

list Enumerates the list of enabled sources.

update Updates a source.

remove Removes a source.

reset Resets winget and msstore back to the initial configuration.

 Subcommand Description

export Exports current sources.

add
The add subcommand adds a new source. This subcommand requires the --name and -
-arg options. Because the command changes user access, using add requires
administrator privileges.

Usage:

Windows Command Prompt

winget source add [-n, --name] <name> [-a, --arg] <url> [[-t, --type]
<type>]

Arguments

The following arguments are available.

Argument Description

-n, --name The name to identify the source by.

-a, --arg The URL or UNC of the source.

-t, --type The type of source.

Options

The following options are available.

Option Description

--header Optional Windows-Package-Manager REST source HTTP header.

--accept-source- Used to accept the source license agreement, and avoid the
agreements prompt.

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

 Option Description

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

For example, winget source add --name Contoso https://www.contoso.com/cache adds

the Contoso repository at URL https://www.contoso.com/cache .

Optional type parameter

The add subcommand supports the optional type parameter, which tells the client what
type of repository it is connecting to. The following type is supported.

Type Description

Microsoft.PreIndexed.Package The default source type.

list
The list subcommand enumerates the currently enabled sources, or provides details on
a specific source.

Usage:

Windows Command Prompt

winget source list [[-n, --name] <name>]

Aliases
The following aliases are available for this subcommand:

ls

Arguments

The following arguments are available.

Argument Description

-n, --name The name to identify the source by.

Options
The following options are available.

Option Description

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

list all

The list subcommand by itself, winget source list , provides the complete list of
supported sources:

Output

Name Arg
-----------------------------------------
winget https://winget.azureedge.net/cache

list source details

To get complete details about a source, pass in the name of the source. For example:

Windows Command Prompt

winget source list --name Contoso

Returns the following output:

Output

Name : Contoso
Type : Microsoft.PreIndexed.Package
Arg : https://pkgmgr-int.azureedge.net/cache
Data : AppInstallerSQLiteIndex-int_g4ype1skzj3jy
Updated: 2020-4-14 17:45:32.000
 Name is the name of the source.
Type is the type of repo.

Arg is the URL or path the source uses.

Data is the optional package name, if appropriate.

Updated is the last date and time the source was updated.

update
The update subcommand forces an update to an individual source, or to all sources.

Usage:

Windows Command Prompt

winget source update [[-n, --name] <name>]

Aliases

The following aliases are available for this subcommand:

refresh

Arguments
The following arguments are available.

Argument Description

-n, --name The name to identify the source by.

Options
The following options are available.

Option Description

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.
 Option Description

--disable-interactivity Disable interactive prompts.

update all
The update subcommand by itself, winget source update , requests updates to all repos.

update source

The update subcommand with the --name option directs an update to the named
source. For example: winget source update --name Contoso forces an update to the
Contoso repository.

remove
The remove subcommand removes a source. This subcommand requires the --name
option to identify the source. Because the command changes user access, using remove
requires administrator privileges.

Usage:

Windows Command Prompt

winget source remove [-n, --name] <name>

Aliases
The following aliases are available for this subcommand:

rm

Arguments

The following arguments are available.

Argument Description

-n, --name The name to identify the source by.

Options
The following options are available.

Option Description

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

Examples

Windows Command Prompt

winget source remove --name Contoso

This command removes the Contoso repository.

reset
The reset subcommand resets the client back to its original configuration, and removes
all sources except the default. Only use this subcommand in rare cases. Because the
command changes user access, using reset requires administrator privileges.

Because the reset command removes all sources, you must force the action by using the
--force option.

Usage:

Windows Command Prompt

winget source reset --force

Arguments

The following arguments are available.

Argument Description

-n, --name The name to identify the source by.

Options
The following options are available.

Option Description

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

export
The export sub-command exports the specific details for a source to JSON output.

Arguments
The following arguments are available.

Argument Description

-n, --name The name to identify the source by.

Options
The following options are available.

Option Description

-?, --help Get additional help on this command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

Examples
 Windows Command Prompt

winget source export winget

Returns the following output:

Output

{"Arg":"https://winget.azureedge.net/cache","Data":"Microsoft.Winget.Source_
8wekyb3d8bbwe","Identifier":"Microsoft.Winget.Source_8wekyb3d8bbwe","Name":"
winget","Type":"Microsoft.PreIndexed.Package"}

Source agreement
An individual source might request that the user agree to the terms presented before
adding or using the repository. If a user doesn't accept or acknowledge the agreement,
they won't be able to access the source.

You can use the --accept-source-agreements option to accept the source license
agreement and avoid the prompt.

Related topics
Use the winget tool to install and manage applications
Tab completion (winget)
Article • 05/19/2022

The winget command line tool offers a complete command to provide context-sensitive
tab completion. It supports completion of command names, argument names, and
argument values, dependent on the current command line state.

Enable tab completion

To enable tab completion with winget, you must add the following script to your
$PROFILE in PowerShell.

1. Open PowerShell and enter the following command to open your $PROFILE in
Notepad: notepad.exe $PROFILE

2. Copy and paste the following script into the $PROFILE file that has opened in
Notepad:

PowerShell

Register-ArgumentCompleter -Native -CommandName winget -ScriptBlock {

param($wordToComplete, $commandAst, $cursorPosition)
[Console]::InputEncoding = [Console]::OutputEncoding =
$OutputEncoding = [System.Text.Utf8Encoding]::new()
$Local:word = $wordToComplete.Replace('"', '""')
$Local:ast = $commandAst.ToString().Replace('"', '""')
winget complete --word="$Local:word" --commandline "$Local:ast"
--position $cursorPosition | ForEach-Object {
[System.Management.Automation.CompletionResult]::new($_,
$_, 'ParameterValue', $_)
}
}

3. Save the $PROFILE with your script. Then close and reopen PowerShell. Once
PowerShell has been reopened, winget tab completion will be enabled.

Examples of tab completion

Repeated presses of tab ( ⇥ ) will result in cycling through the possible values.

Input Result Reason

 Input Result Reason

winget ⇥ winget install install is the first command below the

root

winget sh⇥ winget show show is the first command that starts with
sh

winget source l⇥ winget source list list is the first sub-command of source
that starts with l

winget -⇥ winget --version --version is the first argument defined for

the root

winget install winget install "Power "Power Toys" is the first package whose Id,
power⇥ Toys" Name, or Moniker starts with power

winget install "Power winget install "Power 0.19.2 is the highest version of Power Toys
Toys" --version ⇥ Toys" --version 0.19.2 at the time of writing

Command Reference
The complete command takes 3 required arguments:

Argument Description

--word The current word that is being completed; the token that the cursor is located
within. Can be empty to indicate no current value at the cursor, but if provided, it
must appear as a substring in the command line.

-- The entire current command line, including winget . See the examples above;
commandline everything but the tab character ( ⇥ ) should be provided to this argument.

--position The current position of the cursor in the command line. Can be greater than the
length of the command line string to indicate at the end.

When a word value is provided, the completion operates in replacement mode. It will
suggest completions that would fit correctly at this location that also start with the given
word value.

When a word value is not provided (an empty value is provided for word, ex. --word= ),
the completion operates in insertion mode. It will suggest completions that would fit as
a new value in the cursor's location.

Based on the arguments, the completions suggested can be one of:

 1. A sub command :: The cursor is located just after a command and there are sub
commands available.
2. An argument specifier :: The cursor is not positioned after an argument specifier
that expects a value, and there are arguments available.
3. An argument value :: The cursor is positioned after an argument specifier that
expects a value, or a positional argument is expected.

After evaluating all of these cases, the potential completions are output, one on each
line. If the completion string contains a space, it is wrapped in quotations.

Related topics
Use the winget tool to install and manage applications
Submit packages to Windows Package Manager
uninstall command (winget)
Article • 07/28/2023

The uninstall command of the winget tool uninstalls the specified application.

The uninstall command requires that you specify the exact string to uninstall. If there is
any ambiguity, you will be prompted to further filter the uninstall command to an exact
application.

Aliases
The following aliases are available for this command:

remove
rm

Usage
winget uninstall [[-q] \<query>] [\<options>]

７ Note

When using WinGet to uninstall a package, you may encounter a Microsoft Store
agreement. This is due to the way in which WinGet queries package manifest
sources. If you prefer not to have the Microsoft Store policy popup when
uninstalling, you can pass in --source winget to suppress the agreement.
 Alternatively, you can uninstall using Start > Settings > Apps > Apps & features,
finding the app you want to remove, and selecting More > Uninstall.

Arguments
The following arguments are available.

Argument Description

-q,--query The query used to search for an app.

７ Note

The query argument is positional. Wild-card style syntax is not supported. This is
most often the string of characters you expect to help find the package you are
uninstalling.

Options
The options allow you to customize the uninstall experience to meet your needs.

Option Description

-m, --manifest Must be followed by the path to the manifest (YAML) file. You can use the
manifest to run the uninstall experience from a local YAML file.

--id Limits the uninstall to the ID of the application.

--name Limits the search to the name of the application.

--moniker Limits the search to the moniker listed for the application.

--product-code Filters using the product code

-v, --version Enables you to specify an exact version to uninstall. If not specified, latest
will uninstall the highest versioned application.

-s, --source Restricts the search to the source name provided. Must be followed by the
source name.

-e, --exact Uses the exact string in the query, including checking for case-sensitivity. It
will not use the default behavior of a substring.

--scope Select installed package scope filter (user or machine)

 Option Description

-i, --interactive Runs the uninstaller in interactive mode. The default experience shows
uninstaller progress.

-h, --silent Runs the uninstaller in silent mode. This suppresses all UI. The default
experience shows uninstaller progress.

--force Direct run the command and continue with non security related issues.

--purge Deletes all files and directories in the package directory (portable)

--preserve Retains all files and directories created by the package (portable)

-o, --log Directs the logging to a log file. You must provide a path to a file that you
have the write rights to.

--header Optional Windows-Package-Manager REST source HTTP header.

--accept-source- Used to accept the source license agreement, and avoid the prompt.
agreements

-?,--help Shows help about the selected command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs

--disable- Disable interactive prompts.

interactivity

After you have successfully identified the application intended to uninstall, winget will
execute the uninstall command. In the example below, the name 'orca' and the id was
passed in.

Example queries
The following example uninstalls a specific version of an application.

CMD
 winget uninstall --name powertoys --version 0.15.2

The following example uninstalls an application using its ID.

CMD

winget uninstall --id "{24559D0F-481C-F3BE-8DD0-D908923A38F8}"

Multiple selections
If the query provided to winget does not result in a single application to uninstall, then
winget will display multiple results. You can then use additional filters to refine the
search for a correct application.

Uninstalling apps not installed with Windows

Package Manager
As mentioned in list, the winget list command will display more than just apps installed
with the winget. Therefore you can use these commands to quickly and easily remove
apps from your PC.

In this example, list was used to find the application, and then the id was passed in as
part of uninstall.
upgrade command (winget)
Article • 11/16/2023

The upgrade command of the winget tool upgrades the specified application.
Optionally, you may use the list command to identify the application you want to
upgrade.

The upgrade command requires that you specify the exact string to upgrade. If there is
any ambiguity, you will be prompted to further filter the upgrade command to an exact
application.

Aliases
The following aliases are available for this command:

update

Usage
winget upgrade [[-q] \<query> ...] [\<options>]

Arguments
The following arguments are available.
 ﾉ Expand table

Argument Description

-q,--query The query used to search for an app.

７ Note

The query argument is positional. Wild-card style syntax is not supported. This is
most often the string of characters you expect to help find the package you are
upgrading.

Options
The options allow you to customize the upgrade experience to meet your needs.

ﾉ Expand table

Option Description

-m, -- Must be followed by the path to the manifest (YAML) file. You can use the
manifest manifest to run the upgrade experience from a local YAML file.

--id Limits the upgrade to the ID of the application.

--name Limits the search to the name of the application.

--moniker Limits the search to the moniker listed for the application.

-v, --version Enables you to specify an exact version to upgrade. If not specified, latest will
upgrade the highest versioned application.

-s, --source Restricts the search to the source name provided. Must be followed by the
source name.

-e, --exact Uses the exact string in the query, including checking for case-sensitivity. It will
not use the default behavior of a substring.

-i, -- Runs the installer in interactive mode. The default experience shows installer
interactive progress.

-h, --silent Runs the installer in silent mode. This suppresses all UI. The default experience
shows installer progress.

--purge Deletes all files and directories in the package directory (portable)
Option Description

-o, --log Directs the logging to a log file. You must provide a path to a file that you have
the write rights to.

--custom Arguments to be passed on to the installer in addition to the defaults.

--override A string that will be passed directly to the installer.

-l, --location Location to upgrade to (if supported).

--scope Select installed package scope filter (user or machine).

a, -- Select the architecture to install.

architecture

--installer- Select the installer type to upgrade. See supported installer types for WinGet
type client.

--locale Specifies which locale to use (BCP47 format).

--ignore- Ignore the installer hash check failure. Not recommended.

security-hash

--ignore- Ignore the malware scan performed as part of installing an archive type package
local-archive- from local manifest.
malware-scan

--accept- Used to accept the license agreement, and avoid the prompt.
package-
agreements

--accept- Used to accept the source license agreement, and avoid the prompt.
source-
agreements

--header Optional Windows-Package-Manager REST source HTTP header.

-r, --recurse, - Updates all available packages to the latest application.

-all

-u, -- Upgrade packages even if their current version cannot be determined.

unknown, --
include-
unknown

--pinned,-- Upgrade packages even if they have a non-blocking pin.

include-
pinned

--uninstall- Uninstall the previous version of the package during upgrade. Behavior will
previous depend on the individual package. Some installers are designed to install new
 Option Description

versions side-by-side. Some installers include a manifest that specifies

“uninstallPrevious” so earlier versions are uninstalled without needing to use this
command flag. In this case, using the winget upgrade --uninstall-previous
command will tell WinGet to uninstall the previous version regardless of what is
in the package manifest. If the package manifest does not include
“uninstallPrevious” and the --uninstall-previous flag is not used, then the default
behavior for the installer will apply.

--force Direct run the command and continue with non security related issues.

-?,--help Shows help about the selected command.

--wait Prompts the user to press any key before exiting.

--logs,--open- Open the default logs location.

logs

--verbose, -- Used to override the logging setting and create a verbose log.
verbose-logs

--disable- Disable interactive prompts.

interactivity

Example queries
The following example upgrades a specific version of an application.

CMD

winget upgrade powertoys --version 0.15.2

The following example upgrades an application from its ID.

CMD

winget upgrade --id Microsoft.PowerToys

The following example shows upgrading all apps

CMD

winget upgrade --all

Using upgrade
To identify which apps are in need of an update, simply use upgrade without any
arguments to show all available upgrades.

In the example below, you will see winget upgrade shows the user which apps have an
available update. From the available updates, the user identifies that an update is
available for JanDeDobbeleer.OhMyPosh and uses upgrade to update the application.

Using list and upgrade

To search for an available update for a specific app, use to the list command. Once you
have identified that a update is available for your specific app, use upgrade to install the
latest.

The example below shows the list command being used to identify that an update is
available for Microsoft.WindowsTerminalPreview. The user then uses upgrade to update
the application.

upgrade --all
upgrade --all will identify all the applications with upgrades available. When you run
winget upgrade --all the Windows Package Manager will look for all applications that
have updates available and attempt to install the updates.

７ Note

Some applications do not provide a version. They are always latest. Because the
Windows Package Manager cannot identify if there is a newer version of the app,
an upgrade will not be possible.

upgrade --uninstall-previous
upgrade --uninstall-previous will uninstall the previous version prior to installing the
newer version of the package. When using --uninstall-previous , the behavior will
depend on the individual package. Some installers are designed to install new versions
side-by-side while other installers include a manifest that specifies uninstallPrevious as
their default upgrade behavior (so earlier versions are uninstalled without needing to
use the command flag).

If the package manifest does not include uninstallPrevious as the upgrade behavior
and the --uninstall-previous flag is not used with the upgrade command, then the
default behavior for the installer will apply.
validate command (winget)
Article • 07/28/2023

The validate command of the winget tool validates a manifest for submitting software
to the Microsoft Community Package Manifest Repository on GitHub. The manifest
must be a YAML file that follows the specification .

Usage
winget validate [--manifest] \<path>

Arguments
The following arguments are available.

Argument Description

--manifest the path to the manifest to be validated.

Options
The options allow you to customize the validate experience to meet your needs.

Option Description

-?,--help Shows help about the selected command.

--wait Prompts the user to press any key before exiting.

--logs,--open-logs Open the default logs location.

--verbose, --verbose-logs Used to override the logging setting and create a verbose log.

--disable-interactivity Disable interactive prompts.

Related topics
Use the winget tool to install and manage applications
Submit packages to Windows Package Manager
Debugging and troubleshooting issues
with the winget tool
Article • 09/01/2023

When Windows Package Manager is installing, searching or listing applications,

sometimes it is necessary to look at the log files to better understand the behavior.

WinGet Logs
Windows Package Manager by default creates log files when executing commands.
These logs contain information that can aid in debugging issues with WinGet. There is
no maximum size for the log files. They are typically only a few KB in size. When the
number of log files in the directory exceeds 100, the oldest log files will begin being
deleted. There is no time-based removal of logs and these settings are not configurable.
If you have reached the 100 file log capacity, just move any WinGet logs that you wish
to preserve into a different directory.

Use the command winget --info to find the directory path to your WinGet log files. The
default path for WinGet log files is:

CMD

%LOCALAPPDATA%\Packages\Microsoft.DesktopAppInstaller_8wekyb3d8bbwe\LocalSta
te\DiagOutputDir

You can include the --logs or --open-logs option to any command to open the logs
directory after the command completes. Here are some examples of using the --logs
option:

CMD

> winget list --logs

> winget source update --open-logs

--verbose-logs
If you need more comprehensive log files, that provide the complete communication
with the CDNs and sources, include --verbose or --verbose-logs on the command line
as well. Here are some examples of using the --verbose-logs option:
 CMD

> winget install vscode --verbose-logs

> winget search -n visual --verbose-logs
> winget source add -n mysource -t Microsoft.REST -a https://www.contoso.org
--verbose

Known issues
A list of known issues with sources and behaviors is kept up to date in the Windows
Package Manager Client repository . If you encounter issues when using the winget
tool, go here for troubleshooting.

Exit codes
The winget tool returns exit codes to indicate success or failure of the command. Find a
table of exit codes and their meanings in the "Return codes" file of the Windows
Package Manager Client repository .

Scope for specific user vs machine-wide

Not all installers support installing in “user” scope vs. “machine” scope consistently.

MSIX-based packages: Reliable WinGet behavior.

MSI-based packages typically support reliable WinGet configurations, but in some
cases, are nested inside an .exe-based installer so there may be more variability.
EXE-based installers behavior around scope is not necessarily deterministic. In
some cases the arguments to specify scope are not available, and in other cases
the installer may make the determination based on whether the user is a member
of the local administrators group. Packages installed in user scope may still require
UAC (User Account Control) authorization from an administrator.

See more details on scope-related issues in the WinGet product repository on GitHub.
WinGet Configuration
Article • 10/23/2023

Using a WinGet Configuration file, you can consolidate manual machine setup and
project onboarding to a single command that is reliable and repeatable. To achieve this,
WinGet utilizes:

A YAML-formatted WinGet Configuration file that lists all of the software versions,
packages, tools, dependencies, and settings required to set up the desired state of
the development environment on your Windows machine.
PowerShell Desired State Configuration (DSC) to automate the configuration of
your Windows operating system.
The Windows Package Manager winget configure command to initiate the
configuration process.

Benefits for machine setup and project

onboarding
The benefits of using a WinGet Configuration file include:

Unattended setup: Enter the winget configure command and let Windows
Package Manager and PowerShell DSC automate the installation and set up of all
the requirements needed to get the desired development environment configured
on your Windows machine.
Reliable and repeatable: Remove the worry over finding the right versions of
software, packages, tools, frameworks, and configuring the correct machine
settings for your development environment when onboarding to a new team or
project because they are pre-defined in the WinGet Configuration file using a
YAML format (with a JSON schema).
Supports Open Source collaboration: WinGet Configuration files can be hosted in
a GitHub repository where issues or contributions can be filed or can be kept
private in a secure storage location (like OneDrive) and shared via private email or
other secured channels.

２ Warning

WinGet Configuration files and any associated PowerShell DSC Resources should be
checked to ensure that they are trustworthy before applying them.
Use a WinGet Configuration file to configure
your machine
To set up your machine using a WinGet Configuration file, you can:

1. Install Dev Home, go to Machine configuration, select Configuration file, and

choose the WinGet configuration file that you would like to use. (To create a
configuration file, see How to author a WinGet Configuration file).

2. Use winget configure in the command line. To use the winget configure
command, you must be running WinGet version v1.6.2631 or later .

WinGet Configuration FAQs

Find answers to some of the most frequently asked questions about WinGet
Configuration.

How do WinGet Configuration files work?

WinGet Configuration files are written in YAML and define what is installed on the device
to make up your development environment, as well as the configuration state for your
machine and installed applications.

Rather than an imperative sequence of steps to be followed, a WinGet Configuration file

is declarative, defining the desired machine configuration state result. By using Windows
Package Manager and PowerShell DSC Resources, the declarative WinGet Configuration
file can install, configure, and apply settings to your environment resulting in a ready-to-
code state.

WinGet will parse the configuration file to ensure it's valid, then download all associated
PowerShell modules (containing the DSC resources) required to achieve your desired
state. Once these resources have been download and you've checked the
trustworthiness of the WinGet Configuration file, agreeing that you've verified the safety
of the file, WinGet will begin testing all required assertions and applying the desired
state.

The sequence in which the WinGet Configuration file resources are ordered is
inconsequential. Some install and configuration processes may even run in parallel. The
assertions directly correspond with the dependsOn field defined in each Resource. If the
resource includes a dependency on an assertion, the assertion will be checked first. If
the assertion fails, the dependent resource will also fail. However, the configuration file
will continue to run, accomplishing as many tasks as possible, even if some of the
assertions or resource dependencies fail, bringing your machine as far along in the set
up process as possible before completing. Once the configuration has completed, it is
your responsibility to check for any failures.

For example, after running the WinGet Configuration file, you may see a result like:

PowerShell

Assert:: OsVersion
The configuration unit could not be found.
Apply :: DeveloperMode
This configuration unity was not run because an assert failed or was
false.
Apply :: WinGetPackage [vsPackage]
This configuration unity was not run because an assert failed or was
false.

In this example, the assertion checking for the required version of the Operating System
failed, so the DeveloperMode and WinGetPackage resources that included a
dependency on that assertion for the operating system version also failed. However, any
other installation and configuration tasks listed in the configuration file would continue
to move forward.

A benefit to the declarative (non-sequential) nature of WinGet configuration files is that

the position of new resources being added to the file does not matter. This is especially
helpful for long configuration files as you can just add additional resources to the
bottom of the file. As long as you have properly defined the assertions and
dependencies, you do not need to be concerned with the sequence, or which set up
steps occur first, second, etc.
How do I use a WinGet Configuration file?
To run a WinGet Configuration file, use the winget configure command.

How do I author a WinGet Configuration?

To create a WinGet Configuration file, follow the guidance in the How to author a
WinGet Configuration file doc.

How can I assure that a WinGet Configuration file is

trustworthy?
We recommend ALWAYS validating the integrity of a WinGet Configuration file before
running it by reviewing it's contents and testing the configuration in an isolated
environment. See How to check the trustworthiness of a WinGet Configuration file.

Where can I find sample WinGet Configuration files?

You can find sample WinGet Configuration files in the Windows Dev Home repo:
https://aka.ms/dsc.yaml .

Where can I find examples of PowerShell modules

containing DSC resources?
The PowerShell Gallery hosts hundreds of PowerShell Modules containing Desired
State Configuration (DSC) resources. You can filter search results by applying the “DSC
Resource” filter under “Categories”.

Can I set up a policy to block the use of WinGet

Configuration files in my organization?
Yes. Group Policy Objects EnableWindowsPackageManagerConfiguration and
EnableWindowsPackageManagerConfigurationExplanation can be utilized for
disabling WinGet Configuration feature in your organization.

Where can I learn more about using WinGet

Configurations with Dev Home and Dev Drives?
Learn more about using the Machine Configuration tool in Windows 11 Dev Home in
the article Set up your Windows development environment with Dev Home. You may
also be interested in learning how to use the more performance optimized Dev Drive
storage volumes, see Set up a Dev Drive on Windows 11.

Troubleshooting WinGet Configurations

The most common reason for a WinGet Configuration to fail is due to a PowerShell DSC
resource requiring administrative access to apply the desired state. Not all DSC
resources surface explicit reasons for failure.

More common troubleshooting issues will be added soon. In the meantime, check the
related issues filed in the WinGet CLI repo on GitHub .
How to author a WinGet Configuration
file
Article • 09/28/2023

To create a WinGet Configuration file:

1. Create a YAML file following the WinGet Configuration file naming convention.
2. Familiarize yourself with the format of a WinGet Configuration file and link the
current file schema .
3. Determine the list of Assertions (required preconditions) and Resources (the list of
required installations and setting configurations to get the machine's development
environment to the desired state) to include in the file.
4. Identify the PowerShell modules and Desired State Configuration (DSC) Resources
needed to accomplish your desired configuration tasks.
5. Determine the directives and settings needed for each configuration resource.
6. Determine the dependencies for each resource.

Learn more about using the WinGet configure command.

File format
Windows Package Manager uses manifests (YAML files) to locate and install packages
for Windows users. WinGet Configuration files use the same YAML style format, adding
a JSON schema specification to help define the structure and validation of the file. To
further assist in detecting whether the format of your WinGet Configuration file is valid,
we recommend using Visual Studio Code with the YAML extension by RedHat to
support proper syntax, help detect any formatting errors, provide hover support and
auto-completion (when linked to the JSON schema file), and ensure valid formatting.

File naming convention

The convention for naming a WinGet Configuration file is configuration.dsc.yaml . For
Git-based projects the default configuration should be stored in a "configurations"
directory at: ./configurations/configuration.dsc.yaml .

Sections of a WinGet Configuration file

A WinGet Configuration file is separated into two primary sections:
 1. Assertions: The preconditions required to run the configuration.
2. Resources: The list of software and tools to install, the configuration settings for
those installs, and the configurations settings for the Windows operating system.

Assertions section
The list of assertions cover the preconditions (or prerequisites) required for the
resources listed in this WinGet Configuration file to succeed on the machine running the
file. Assertions can be completed in parallel and do not require any sequential order.

An example assertion:

OS version: A minimum version of the operating system* installed on the machine.

As features are added over time to the OS, some are backported to support earlier
versions and some are not. It is always helpful to check for a minimum OS version
to determine whether a specific tool or feature may be supported that is required
for the configuration. For example, WinGet (Windows Package Manager) requires a
minimum of Windows 10, version 1809 or newer. Any older versions of Windows
do not support WinGet. *It is possible for PowerShell DSC Resources to change the
state of the system, but it would not be appropriate to call Windows Update and
modify the OS version in the project configuration for an open-source project.

If an assertion returns “false” to indicate the system is not in the desired state, any
Resource identifying that assertion as a dependency using the dependsOn field will be
skipped and fail to run. In this case, even though no configuration changes were applied
to the Windows environment, this configuration would be considered a successful
outcome.

Resources section
The list of Resources covers all of the software, tools, packages, etc. that need to be
installed and the configurations settings for your Windows operating system or installed
applications. Each resource will need to be given a name, description of the directive to
be carried out and the PowerShell module that will be responsible for carrying out that
directive, as well as any associated settings or dependencies.

Example WinGet Configuration file

The following is an example WinGet Configuration configuration.dsc.yaml formatted
file:
 yml

# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
properties:
assertions:
- resource: Microsoft.Windows.Developer/OsVersion
directives:
description: Verify min OS version requirement
allowPrerelease: true
settings:
MinVersion: '10.0.22000'
resources:
- resource: Microsoft.Windows.Developer/DeveloperMode
directives:
description: Enable Developer Mode
allowPrerelease: true
settings:
Ensure: Present
- resource: Microsoft.WinGet.DSC/WinGetPackage
id: vsPackage
directives:
description: Install Visual Studio 2022 Community
allowPrerelease: true
settings:
id: Microsoft.VisualStudio.2022.Community
source: winget
- resource: Microsoft.VisualStudio.DSC/VSComponents
dependsOn:
- vsPackage
directives:
description: Install required VS workloads from vsconfig file
allowPrerelease: true
settings:
productId: Microsoft.VisualStudio.Product.Community
channelId: VisualStudio.17.Release
vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
includeRecommended: true
configurationVersion: 0.2.0

The components of this file consist of:

1. Schema: The first line in your configuration file should contain the following
comment: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-
schema/<most recent schema version #> to establish the DSC schema being

followed by the file. To find the most recent version of the WinGet Configuration
schema, go to https://aka.ms/configuration-dsc-schema/ . The most recent
schema number at the time of this example is 0.2 , so the schema was entered as:
# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2 .
 2. Properties: The root node for a configuration file is properties which must contain
a configuration version ( configurationVersion: 0.2.0 in this example). This version
should be updated in accordance with updates to the configuration file. The
properties node should contain an assertions node and a resources node.

3. Assertions: List the preconditions (or prerequisites) required for this configuration
in this section.

4. Resources: Both the assertions and resources list sections consist of individual
resource nodes to represent the set up task. The resource should be given the

name of the PowerShell module followed by the name of the module's DSC
resource that will be invoked to apply your desired state:
{ModuleName}/{DscResource} . Each resource must include directives and
settings . Optionally, it can also include an id value. When applying a

configuration, WinGet will know to install the module from the PowerShell
Gallery and invoke the specified DSC resource.

5. Directives: The directives section provides information about the module and the
resource. This section should include a description value to describe the
configuration task being accomplished by the module. The allowPrerelease value
enables you to choose whether or not the configuration will be allowed ( true ) to
use "Prerelease" modules from the PowerShell Gallery .

6. Settings: The settings value of a resource represents the collection of name-value

pairs being passed to the PowerShell DSC Resource. Settings could represent
anything from whether Developer Mode is enabled, to applying a reg key, or to
establishing a particular network setting.

7. Dependencies: The dependsOn value of a resource determines whether any other

assertion or resource must be complete prior to beginning this task. If the
dependency failed, this resource will also automatically fail.

8. ID: A unique identifier for the particular resource instance. The id value can be
used if another resource has a dependency on this resource being applied first.

Organizing the Resources section

There are multiple approaches to consider when determining how to organize the
Resources section of your WinGet Configuration file. You can organize your list of files
by:
 Execution order: Organizing your list of resources according to the logical order in
which they should be executed. This approach can help the user to understand and
follow along with the automation steps being performed once the file is run - what
is installed first, second, what setting is updated third, etc.
Possibility of failure: Organizing your list of resources according to the likelihood
of a potential failure can help users to catch issues early-on in the configuration
process and help them understand why remaining steps may fail, enabling them to
identify and make necessary changes before much time is invested.
Grouping similar resource types: Organizing your list of resources by grouping
together similar resource types is a common approach in software engineering
methodologies and may be the most familiar to you or to other developers
utilizing your configuration file.

We recommend including a README.md file with any Open Source published WinGet
Configuration file that includes the organizational approach of the file structure.

Using the variable ${WinGetConfigRoot}

Certain DSC resources may take in a parameter that specifies the path of a file. Instead
of specifying the full path, you can use the variable ${WinGetConfigRoot} to define the
working directory where the winget configure command is being executed and append
the relative path to point to that file. This is useful for generalizing a configuration file so
that it is machine agnostic. The Microsoft.VisualStudio.DSC/VSComponents resource in
the example above showcases this functionality by utilizing the ${WinGetConfigRoot} to
point to a .vsconfig file in a project's root directory. This also means that the user should
ensure that the target file exists at the relative path based on the current working
directory before executing the winget configure command.

Where to find PowerShell DSC Resource

modules
Check out the list of ready-to-use ("inbox") PowerShell Desired State Configuration
Resources that are supported by Microsoft, including:

Environment: Manage an environment variable for a machine or process.

MsiPackage: Install or uninstall an MSI package.
Registry: Manage a registry key or value.
Script: Run PowerShell script blocks.
Service: Manage a Windows service.
WindowsFeature: Install or uninstall a Windows role or feature.
 WindowsProcess: Start or stop a Windows process.

You can also find PowerShell DSC Resource modules in the PowerShell Gallery . This
gallery hosts hundreds of PowerShell Modules containing Desired State Configuration
(DSC) resources submitted by the user community. You can filter search results by
applying the “DSC Resource” filter under “Categories”. This repository is not verified by
Microsoft and contains resources from a variety of authors and publishers. PowerShell
modules should always be reviewed for security and credibility before being used as any
arbitrary scripting can be included. See How to check the trustworthiness of a WinGet
Configuration file for more tips on creating a trustworthy WinGet Configuration file.
How to check the trustworthiness of a
WinGet Configuration file
Article • 09/28/2023

Prior to running a WinGet Configuration file, it is recommended to review and evaluate

each resource listed in the file, ensuring that you are fully aware of what is being
installed, changed, or applied to your operating system, and that it is coming from a
credible and secure source.

Learn more about using the WinGet configure command.

Security notifications and approvals

Before running a configuration, the user is prompted (unless they explicitly pass the
configuration agreement acceptance parameter) to review and acknowledge their
responsibility to verify a configuration.

Due to the unattended setup benefit that WinGet Configuration files enables, the
number of explicit installation notifications and approvals is significantly reduced.
Instead, using a WinGet Configuration file requires a diligent security check of the file
upfront, prior to running the configuration with the winget configure command. You
are responsible for reviewing each package that will be installed and each PowerShell
Desired State Configuration (DSC) module that will be utilized to ensure that it's coming
from a reliable source.

Be aware that:

Users who run a configuration via winget configure in an administrative shell will
not be prompted for changes to the system made in administrative context.

Users who run a configuration via winget configure in user context may only
receive a single User Account Control (UAC) prompt for elevation for the entire
configuration.

Review configuration resources

WinGet Configuration leverages PowerShell DSC to apply a configuration to the users
system. The configuration file specifies which PowerShell DSC resources will be used to
apply the desired state. Each DSC Resource should be reviewed before agreeing to run
the configuration file.
To review PowerShell DSC Resources:

The PowerShell Get-PSRepository cmdlet can be used to view configured

repositories and determine where resources will be sourced prior to executing the
file.

When reviewing configuration resources, be aware that:

PowerShell DSC Resources can be configured to run any arbitrary code, including
but not limited to pulling down and executing additional DSC Resources and
binaries to the local machine. This requires a diligent integrity check of the
resource and credibility of the publisher. For example, the DSC Script Resource
provides a mechanism to run Windows PowerShell script blocks on target nodes
(using Get, Set, and Test scripts). Do not run script resources from untrusted
publishers without reviewing the scripts contents.

The PowerShell Gallery is a central repository for discovering, sharing, and

acquiring PowerShell modules, scripts, and DSC Resources. This repository is not
verified by Microsoft and contains resources from a variety of authors and
publishers that should not be trusted by default. Each package has a specific page
in the Gallery with associated metadata with Owner field being strongly tied to the
Gallery account (more trustworthy than the Author field). If you discover a package
that you feel isn't published in good faith, select "Report Abuse" on that package's
page. Learn more about the PowerShell Gallery.

Test configuration files

We recommend testing all WinGet Configuration files in a clean and isolated
environment. A few testing options include:

Download a Windows 11 virtual machine to run via virtualization

Create a Windows virtual machine in the Azure portal

Run Windows Sandbox - a lightweight, isolated, temporary desktop environment,

Submit packages to Windows Package
Manager
Article • 11/29/2022

This section provides guidance about submission process for contributing packages to
Windows Package Manager (packages that can be installed with winget).

Independent Software Vendor (ISV) or

Publisher
If you are an ISV or Publisher, you can use Windows Package Manager as a distribution
channel for software packages containing your applications. Windows Package Manager
currently supports installers in the following formats: MSIX, MSI, and EXE.

To submit software packages to Windows Package Manager, follow these steps:

1. Create a package manifest that provides information about your application.

Manifests are YAML files that follow the Windows Package Manager schema.
2. Submit your manifest to the Windows Package Manager repository. This is an open
source repository on GitHub that contains a collection of manifests that the winget
tool can access.

Ensure your submission adheres to the Windows Package Manager repository policies.

Community member
If you are a GitHub community member, you may also submit packages to Windows
Package Manager following the steps above.

Optionally, you may also request help to have a package added to the community
repository . To do so, create a new Package Request/Submission issue.

Related topics
Use the winget tool
Create your package manifest
Submit your manifest to the repository
Create your package manifest
Article • 11/01/2023

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 application to be installed.

You may either use the Windows Package Manager Manifest Creator , the YAMLCreate
PowerShell script, or you can craft a manifest manually following the instructions below.

７ Note

See the Manifest FAQ below for more general high-level information explaining
manifests, packages, and versions.

Options for Manifest Creation

Using WinGetCreate Utility

You can install the wingetcreate utility using the command below.

PowerShell

winget install wingetcreate

After installation, you can run wingetcreate new to create a new package and fill in the
prompts. The last option in the WinGetCreate prompts is to submit the manifest to the
packages repository. If you choose yes, you will automatically submit your Pull Request
(PR) to the Windows Package Manager Community Repository .

Using the YAMLCreate.ps1

To help author manifest files, we have provided a YAMLCreate.ps1 powershell script
located in the Tools folder on the Windows Package Manager Community Repository .
You can use the script by cloning the repo on your PC and running the script directly
from the Tools folder. The script will prompt you for the URL to the installer, then will
prompt you to fill in metadata. Similar to using WinGetCreate, this script will offer the
option to submit your 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 are
not familiar with YAML syntax, you can learn the basics at Learn YAML in Y Minutes .

７ Note

Manifests for Windows Package Manager currently do not support all YAML
features. Unsupported YAML features include anchors, complex keys, and sets.

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 like 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 mapping of strings to strings.

Manifest contents
A package manifest consists of required items and optional items that can help improve
the customer experience of installing your 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-cased and cannot be duplicated.

For a complete list and descriptions of items in a manifest, see the manifest
specification in the Windows Package Manager Community Repository .

Minimal required schema

As specified in the singleton JSON schema , only certain fields are required. The
minimal supported YAML file would look like the example below. The singleton format is
only valid for packages containing a single installer and a single locale. If more than one
installer or locale is provided, the multiple YAML file format and schema must be used.

The partitioning scheme was added to help with GitHub's UX. Folders with thousands of
children do not render well in the browser.

Minimal required schema

YAML

PackageIdentifier: # Publisher.package format.

PackageVersion: # Version numbering format.
PackageLocale: # BCP 47 format (e.g. en-US)
Publisher: # The name of the publisher.
PackageName: # The name of the application.
License: # The license of the application.
ShortDescription: # The description of the application.
Installers:
- Architecture: # Enumeration of supported architectures.
InstallerType: # Enumeration of supported installer types (exe,
msi, msix, inno, wix, nullsoft, appx).
InstallerUrl: # Path to download installation file.
InstallerSha256: # SHA256 calculated from installer.
ManifestType: # The manifest file type
ManifestVersion: 1.6.0

Multiple manifest files

To provide the best user experience, manifests should contain as much meta-data as
possible. In order to separate concerns for validating installers and providing localized
metadata, manifests should be split into multiple files. The minimum number of YAML
files for this kind of manifest is three. Additional locales should also be provided.

A version (JSON Schema ) file.

The default locale (JSON Schema ) file.
An installer (JSON Schema ) file.
Additional locale (JSON Schema ) files.

The example below shows many optional metadata fields and multiple locales. Note the
default locale has more requirements than additional locales. In the show command, any
required fields that aren't provided for additional locales will display fields from the
default locale.

Version file example

 Path: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 /
Microsoft.WindowsTerminal.yaml

YAML

PackageIdentifier: "Microsoft.WindowsTerminal"
PackageVersion: "1.6.10571.0"
DefaultLocale: "en-US"
ManifestType: "version"
ManifestVersion: "1.6.0"

７ Note

If your installer is an .exe and it was built using Nullsoft or Inno, you may specify
those values instead. When Nullsoft or Inno are specified, the client will
automatically set the silent and silent with progress install behaviors for the
installer.

Installer switches
You can often figure out what silent Switches are available for an installer by passing in
a -? to the installer from the command line. Here are some common silent Switches
that can be used for different installer types.

ﾉ Expand table

Installer Command Documentation

MSI /q MSI Command-Line Options

InstallShield /s InstallShield Command-Line Parameters

Inno Setup /SILENT or /VERYSILENT Inno Setup documentation

Nullsoft /S Nullsoft Silent Installers/Uninstallers

Tips and best practices

The package identifier must be unique. You cannot have multiple submissions with
the same package identifier. Only one pull request per package version is allowed.
 Avoid creating multiple publisher folders. For example, do not create "Contoso
Ltd." if there is already a "Contoso" folder.
All tools must support a silent install. If you have an executable that does not
support a silent install, then we cannot provide that tool at this time.
Provide as many fields as possible. The more meta-data you provide the better the
user experience will be. 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, customers will see results associated
with the Moniker value when performing the search command (for example,
vscode for Visual Studio Code). If there is only one app with the specified Moniker
value, customers can install your application by specifying the moniker rather than
the fully qualified package identifier.
The length of strings in this specification should be limited to 100 characters
before a line break.
The PackageName should match the entry made in Add / Remove Programs to help
the correlation with manifests to support export, and upgrade.
The Publisher should match the entry made in Add / Remove Programs to help
the correlation with manifests to support export, and upgrade.
Package installers in MSI format use product codes to uniquely identify
applications. The product code for a given version of a package should be included
in the manifest to help ensure the best upgrade experience.
When more than one installer type exists for the specified version of the package,
an instance of InstallerType can be placed under each of the Installers .

Manifest FAQ

What is a manifest?
Manifests are YAML files containing metadata used by the Windows Package Manager
to install and upgrade software on the Windows operating system. There are thousands
of these files partitioned under the manifests directory in the winget-pkgs repository on
GitHub . The Windows Package Manager directory structure had to be partitioned so
you don't have to scroll as much in the site when looking for a manifest.

What is a package?
Think of a package as an application or a software program. Windows Package Manager
uses a "PackageIdentifier" to represent a unique package. These are generally in the
form of Publisher.Package . Sometimes you might see additional values separated by a
second period.

What is a version?
Package versions are associated with a specific release. In some cases you will see a
perfectly formed semantic version numbers and in other cases you might see something
different. These may be date driven or they might have other characters with some
package-specific meaning. The YAML key for a package version is "PackageVersion".

For more information on understanding the directory structure and creating your first
manifest, see Authoring Manifests in the winget-pkgs repo on GitHub.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Submit your manifest to the repository
Article • 03/01/2023

After you create a package manifest that describes your application, you're ready to
submit your manifest to the Windows Package Manager repository. This is a public-
facing repository that contains a collection of manifests that the winget tool can access.
To submit your manifest, you'll upload it to the open source
https://github.com/microsoft/winget-pkgs repository on GitHub.

After you submit a pull request to add a new manifest to the GitHub repository, an
automated process will validate your manifest file and check to make sure the package
complies with the Windows Package Manager polices and is not known to be malicious.
If this validation is successful, your package will be added to the public-facing Windows
Package Manager repository so it can be discovered by the winget client tool. Note the
distinction between the manifests in the open source GitHub repository and the public-
facing Windows Package Manager repository.

） Important

Microsoft reserves the right to refuse a submission for any reason.

Manifest validation
When you submit a manifest to the https://github.com/microsoft/winget-pkgs
repository on GitHub, your manifest will be automatically validated and evaluated for
the safety of the Windows ecosystem. Manifests may also be reviewed manually.

For more information about the validation process, see the validation process section
below.

How to submit your manifest

To submit a manifest to the repository, follow these steps.

Step 1: Validate your manifest

The winget tool provides the validate command to confirm that you have created your
manifest correctly. To validate your manifest, use this command.
 CMD

winget validate \<path-to-the-manifests>

If your validation fails, use the errors to locate the line number and make a correction.
After your manifest is validated, you can submit it to the repository.

Step 2: Test your manifest with Windows Sandbox

The Windows Package Manager repository includes a script that will install the Windows
Package Manager in a Sandbox for testing manifest submissions. To run the powershell
script, navigate to your winget-pkgs repo. From PowerShell, enter the following
command:

PowerShell

powershell .\Tools\SandboxTest.ps1
manifests\m\Microsoft\VisualStudioCode\1.56.0

You may need to update this script with the correct path to your manifest file:
.\Tools\SandboxTest.ps1 <path to manifest or manifest folder>

See the full sandbox test script in the winget-pkgs repo .

Step 3: Clone the repository

To create a fork of the Windows Package Manager Community repository and clone the
repo to your local machine:

1. Go to https://github.com/microsoft/winget-pkgs in your browser and select

Fork.

2. From Windows Command Prompt or PowerShell, use the following command to

clone your fork.

PowerShell

git clone <your-fork-name>

3. If you are entering multiple submissions, create a branch instead of a fork. We

currently allow only one manifest file per submission.
 PowerShell

git checkout -b <branch-name>

Step 4: Add your manifest to the local repository

You must add your manifest files to the repository in the following folder structure:

manifests / letter / publisher / application / version

The manifests folder is the root folder for all manifests in the repository.
The letter folder is the first letter of the publisher name in the lower case. For
example, m of the publisher Microsoft.
The publisher folder is the name of the company that publishes the software. For
example, Microsoft.
The application folder is the name of the application or tool. For example, VSCode.
The version folder is the version of the application or tool. For example, 1.0.0.

The PackageIdentifier and the PackageVersion values in the manifest must match the
publisher, application names and version in the manifest folder path. For more
information, see Create your package manifest.

Step 5: Submit your manifest to the remote repository

You're now ready to push your new manifest to the remote repository.

1. Use the commit command to add files and commit the change and provide
information on the submission.

PowerShell

git commit -m "Submitting ContosoApp version 1.0.0" --all

2. Use the push command to push the changes to the remote repository.

PowerShell

git push

Step 6: Create a pull request

After you push your changes, return to https://github.com/microsoft/winget-pkgs and
create a pull request to merge your fork or branch to the main branch.

Submission process
When you create a pull request, this will start an automated process that validates the
manifests and verifies your pull request. During this process we will run tests against the
installer and installed binaries to validate the submission.

We add labels to your pull request so you can track its progress. For more information
on labels and the process see the pull request labels section below.

Once complete, your submission will be manually reviewed by a moderator, and after it
is approved, your application will be added to the Windows Package Manager catalog.

If there is ever an error during the process, you will be notified and our labels and bot
will assist you in fixing your submission. For the list of common errors, see the validation
process section below.

Validation process
When you create a pull request to submit your manifest to the Windows Package
Manager repository, this will start an automation process that validates the manifest and
processes your pull request. GitHub labels are used to share progress and allow you to
communicate with us.

Submission expectations
All application submissions to the Windows Package Manager repository should adhere
to the Windows Package Manager repository policies.

Expectations for submissions:

The manifest complies with the schema requirements.

All URLs in the manifest lead to safe websites.
The installer and application are virus free. The package may be identified as
malware by mistake. If you believe it is a false positive you can submit the installer
 to the Microsoft Defender team for analysis .
The application installs and uninstalls correctly for both administrators and non-
administrators.
The installer supports non-interactive modes.
All manifest entries are accurate and not misleading.
The installer comes directly from the publisher's website.

For a complete list of the policies, see Windows Package Manager policies.

Pull request labels

During validation, a series of labels are applied to pull requests to communicate
progress. Some labels will direct you to take action, while others will be directed to the
Windows Package Manager engineering team.

Status labels
The following table describes the status labels you might encounter.

Label Details

Azure- The manifest has completed the test pass. It is waiting for approval. If no issues are
Pipeline- encountered during the test pass it will automatically be approved. If a test fails, it
Passed may be flagged for manual review.

Blocking- This label indicates that the pull request cannot be approved because there is a
Issue blocking issue. You can often tell what the blocking issue is by the included error
label.

Needs- This label indicates that the pull request needs to be investigated by the Windows
Attention Package Manager development team. This is either due to a test failure that needs
manual review, or a comment added to the pull request by the community.

Needs- Indicates there is a failure with the submission. We will reassign the pull request
Author- back to you. If you do not address the issue within 10 days, the bot will close the
Feedback pull request. Needs-Author-Feedback labels are typically added when there was a
failure with the pull request that should be updated, or if the person reviewing the
pull request has a question.

Validation- Indicates that the test pass has been completed successfully and your pull request
Completed will be merged.

Error labels
The following table describes the error labels you might encounter. Not all of the error
cases will be assigned to you immediately. Some may trigger manual validation.

Label Details

Binary- The application included in this pull request failed to pass the Installers Scan test.
Validation- This test is designed to ensure that the application installs on all environments
Error without warnings. For more details on this error, see the Binary validation error
section below.

Error- The Binary-Validation-Test test timed out. The pull request will get assigned to a
Analysis- Windows Package Manager engineer to investigate.
Timeout

Error-Hash- The submitted manifest could not be processed because the InstallerSha256
Mismatch hash provided for the InstallerURL did not match. Update the InstallerSha256 in
the pull request and try again.

Error- The validation service was unable to download the installer. This may be related
Installer- to Azure IP ranges being blocked, or the installer URL may be incorrect. Check
Availability that the InstallerURL is correct and try again. If you feel this has failed in error,
add a comment and the pull request will get assigned to a Windows Package
Manager engineer to investigate.

Manifest- There are either inconsistencies or values not present in the manifest during the
Installer- evaluation of an MSIX package.
Validation-
Error

Manifest- The manifest files must be put into a specific folder structure. This label indicates
Path-Error a problem with the path of your submission. For example, the folder structure
does not have the required format. Update your manifest and path resubmit your
pull request.

Manifest- The submitted manifest contains a syntax error. Address the syntax issue with the
Validation- manifest and re-submit. For details on the manifest format and schema, see
Error required format.

PullRequest- The pull request is invalid because not all files submitted are under manifest
Error folder or there is more than one package or version in the pull request. Update
your pull request to address the issue and try again.

URL- The URLs Validation Test could not locate the URL and responded with a HTTP
Validation- error status code (403 or 404), or the URL reputation test failed. You can identify
Error which URL is in question by looking at the pull request check details. To address
this issue, update the URLs in question to resolve the HTTP error status code. If
the issue is not due to an HTTP error status code, you can submit the URL for
review to avoid the reputation failure.
Label Details

Validation- During dynamic testing, Microsoft Defender reported a problem. To reproduce

Defender- this problem, install your application, then run a Microsoft Defender full scan. If
Error you can reproduce the problem, fix the binary or submit it for analysis for false
positive assistance. If you are unable to reproduce the problem, add a comment
to get the Windows Package Manager engineers to investigate.

Validation- The test has determined the domain if the InstallerURL does not match the
Domain domain expected. The Windows Package Manager policies requires that the
InstallerUrl comes directly from the ISV's release location. If you believe this is a
false detection, add a comment to the pull request to get the Windows Package
Manager engineers to investigate.

Validation- Validation of the Windows Package Manager failed during manual approval. Look
Error at the accompanying comment for next steps.

Validation- During installation testing, the test was unable to locate the primary application.
Executable- Make sure the application installs correctly on all platforms. If your application
Error does not install an application, but should still be included in the repository, add
a comment to the pull request to get the Windows Package Manager engineers
to investigate.

Validation- During installation testing, the application fails to install because the
Hash- InstallerSha256 no longer matches the InstallerURL hash. This can occur if the
Verification- application is behind a vanity URL and the installer was updated without updating
Failed the InstallerSha256. To address this issue, update the InstallerSha256 associated
with the InstallerURL and submit again.

Validation- The URL used for the installer does not use the HTTPS protocol. Update the
HTTP-Error InstallerURL to use HTTPS and resubmit the Pull Request.

Validation- The URL is not coming directly from the ISVs server. Testing has determined a
Indirect-URL redirector has been used. This is not allowed because the Windows Package
Manager policies require that the InstallerUrl comes directly from the ISV's
release location. Remove the redirection and resubmit.

Validation- During manual validation of this package, there was a general error. Look at the
Installation- accompanying comment for next steps.
Error

Validation- This package could not be validated due to a merge conflict. Please address the
Merge- merge conflict and resubmit your pull request.
Conflict

Validation- The MSIX package has a dependency on package that could not be resolved.
MSIX- Update the package to include the missing components or add the dependency
Dependency to the manifest file and resubmit the pull request.
 Label Details

Validation- The test has determined the domain if the InstallerURL does not match the
Unapproved- domain expected. The Windows Package Manager policies requires that the
URL InstallerUrl comes directly from the ISV's release location.

Validation- During installation, the test timed out. This most likely is due to the application
Unattended- not installing silently. It could also be due to some other error being encountered
Failed and stopping the test. Verify that you can install your manifest without user input.
If you need assistance, add a comment to the pull request and the Windows
Package Manager engineers will investigate.

Validation- During uninstall testing, the application did not clean up completely following
Uninstall- uninstall. Look at the accompanying comment for more details.
Error

Validation- The package has a dependency on the C++ runtime that could not be resolved.
VCRuntime- Update the package to include the missing components or add the dependency
Dependency to the manifest file and resubmit the pull request.

Content policy labels

The following table lists content policy labels. If one of these labels is added, something
in the manifest metadata triggered additional manual content review to ensure that the
metadata is following the Windows Package Manager policies.

Label Details

Policy-Test-2.1 See General Content Requirements.

Policy-Test-2.2 See Content Including Names, Logos, Original and Third Party

Policy-Test-2.3 See Risk of Harm.

Policy-Test-2.4 See Defamatory, Libelous, Slanderous and Threatening.

Policy-Test-2.5 See Offensive Content.

Policy-Test-2.6 See Alcohol, Tobacco, Weapons and Drugs.

Policy-Test-2.7 See Adult Content.

Policy-Test-2.8 See Illegal Activity.

Policy-Test-2.9 See Excessive Profanity and Inappropriate Content.

Policy-Test-2.10 See Country/Region Specific Requirements.

Policy-Test-2.11 See Age Ratings.

 Label Details

Policy-Test-2.12 See User Generated Content.

Internal labels

The following table lists internal error labels. When internal errors are encountered, your
pull request will be assigned to the Windows Package Manager engineers to investigate.

Label Details

Internal-Error-Domain An error occurred during the domain validation of the URL.

Internal-Error-Dynamic-Scan An error occurred during the validation of the installed binaries.

Internal-Error-Keyword- An error occurred during the validation of the manifest.

Policy

Internal-Error-Manifest An error occurred during the validation of the manifest.

Internal-Error- An error occurred because the test could not determine the
NoArchitectures architecture if the application.

Internal-Error- An error occurred because the current architecture is not

NoSupportedArchitectures supported.

Internal-Error-PR An error occurred during the processing of the pull request.

Internal-Error-Static-Scan An error occurred during static analysis of the installers.

Internal-Error-URL An error occurred during reputation validation of the installers.

Internal-Error A generic failure or unknown error was encountered during the

test pass.

Binary validation error

If validation of your Pull Request fails the Installers Scan test and receives a Binary-
Validation-Error label, it means that your application failed to install on all
environments.

Installers Scan test

To provide an excellent application installation user experience, the Windows Package
Manager must ensure that all applications install on PCs without errors, regardless of
environment. One key test is to ensure that all applications install without warnings on
various popular antivirus configurations. Windows provides the built-in Microsoft
Defender antivirus program, but many enterprise customers and users use other
antivirus software.

Each submission to the Windows Package Manager Repository is run through several
antivirus programs. These programs all have different virus detection algorithms for
identifying potentially unwanted applications (PUA) and malware.

Address binary validation errors

If an application fails validation, Microsoft first attempts to verify with the antivirus
vendor whether the flagged software is a false positive. In many cases, after notification
and validation, the antivirus vendor updates their algorithm, and the application passes.

In some cases, the antivirus vendor can't determine whether the detected code anomaly
is a false positive. In this case, the application can't be added to the Windows Package
Manager repository. The pull request is rejected with a Binary-Validation-Error label.

If you get a Binary-Validation-Error label on your pull request, update your software to
remove the code detected as PUA.

Sometimes, genuine tools used for debugging and low-level activities appear as PUA to
antivirus software. This is because the necessary debugging code has a similar signature
to unwanted software. Even though this coding practice is legitimate, the Windows
Package Manager repository unfortunately can't allow these applications.

Submission Troubleshooting
If your Windows Package Manager submission fails, you can use the labels described
above to investigate the reason for the failure.

To investigate pull request failures, take the following steps:

1. A pull request failure appears at the bottom of the web page with the string Some
checks were not successful. Select the Details link next to a failed validation to go
to the Azure Pipelines page.
2. On the Azure Pipelines page, select the 0 errors / 0 warnings link.

3. On the next page, select the failed job.

4. The next page shows the output for the failed job. The output should help you
identify the change you need to make to fix the manifest.

In the following example, the failure was during the Installation Validation task.
Submit your manifest to the repository
Article • 03/01/2023

After you create a package manifest that describes your application, you're ready to
submit your manifest to the Windows Package Manager repository. This is a public-
facing repository that contains a collection of manifests that the winget tool can access.
To submit your manifest, you'll upload it to the open source
https://github.com/microsoft/winget-pkgs repository on GitHub.

After you submit a pull request to add a new manifest to the GitHub repository, an
automated process will validate your manifest file and check to make sure the package
complies with the Windows Package Manager polices and is not known to be malicious.
If this validation is successful, your package will be added to the public-facing Windows
Package Manager repository so it can be discovered by the winget client tool. Note the
distinction between the manifests in the open source GitHub repository and the public-
facing Windows Package Manager repository.

） Important

Microsoft reserves the right to refuse a submission for any reason.

Manifest validation
When you submit a manifest to the https://github.com/microsoft/winget-pkgs
repository on GitHub, your manifest will be automatically validated and evaluated for
the safety of the Windows ecosystem. Manifests may also be reviewed manually.

For more information about the validation process, see the validation process section
below.

How to submit your manifest

To submit a manifest to the repository, follow these steps.

Step 1: Validate your manifest

The winget tool provides the validate command to confirm that you have created your
manifest correctly. To validate your manifest, use this command.
 CMD

winget validate \<path-to-the-manifests>

If your validation fails, use the errors to locate the line number and make a correction.
After your manifest is validated, you can submit it to the repository.

Step 2: Test your manifest with Windows Sandbox

The Windows Package Manager repository includes a script that will install the Windows
Package Manager in a Sandbox for testing manifest submissions. To run the powershell
script, navigate to your winget-pkgs repo. From PowerShell, enter the following
command:

PowerShell

powershell .\Tools\SandboxTest.ps1
manifests\m\Microsoft\VisualStudioCode\1.56.0

You may need to update this script with the correct path to your manifest file:
.\Tools\SandboxTest.ps1 <path to manifest or manifest folder>

See the full sandbox test script in the winget-pkgs repo .

Step 3: Clone the repository

To create a fork of the Windows Package Manager Community repository and clone the
repo to your local machine:

1. Go to https://github.com/microsoft/winget-pkgs in your browser and select

Fork.

2. From Windows Command Prompt or PowerShell, use the following command to

clone your fork.

PowerShell

git clone <your-fork-name>

3. If you are entering multiple submissions, create a branch instead of a fork. We

currently allow only one manifest file per submission.
 PowerShell

git checkout -b <branch-name>

Step 4: Add your manifest to the local repository

You must add your manifest files to the repository in the following folder structure:

manifests / letter / publisher / application / version

The manifests folder is the root folder for all manifests in the repository.
The letter folder is the first letter of the publisher name in the lower case. For
example, m of the publisher Microsoft.
The publisher folder is the name of the company that publishes the software. For
example, Microsoft.
The application folder is the name of the application or tool. For example, VSCode.
The version folder is the version of the application or tool. For example, 1.0.0.

The PackageIdentifier and the PackageVersion values in the manifest must match the
publisher, application names and version in the manifest folder path. For more
information, see Create your package manifest.

Step 5: Submit your manifest to the remote repository

You're now ready to push your new manifest to the remote repository.

1. Use the commit command to add files and commit the change and provide
information on the submission.

PowerShell

git commit -m "Submitting ContosoApp version 1.0.0" --all

2. Use the push command to push the changes to the remote repository.

PowerShell

git push

Step 6: Create a pull request

After you push your changes, return to https://github.com/microsoft/winget-pkgs and
create a pull request to merge your fork or branch to the main branch.

Submission process
When you create a pull request, this will start an automated process that validates the
manifests and verifies your pull request. During this process we will run tests against the
installer and installed binaries to validate the submission.

We add labels to your pull request so you can track its progress. For more information
on labels and the process see the pull request labels section below.

Once complete, your submission will be manually reviewed by a moderator, and after it
is approved, your application will be added to the Windows Package Manager catalog.

If there is ever an error during the process, you will be notified and our labels and bot
will assist you in fixing your submission. For the list of common errors, see the validation
process section below.

Validation process
When you create a pull request to submit your manifest to the Windows Package
Manager repository, this will start an automation process that validates the manifest and
processes your pull request. GitHub labels are used to share progress and allow you to
communicate with us.

Submission expectations
All application submissions to the Windows Package Manager repository should adhere
to the Windows Package Manager repository policies.

Expectations for submissions:

The manifest complies with the schema requirements.

All URLs in the manifest lead to safe websites.
The installer and application are virus free. The package may be identified as
malware by mistake. If you believe it is a false positive you can submit the installer
 to the Microsoft Defender team for analysis .
The application installs and uninstalls correctly for both administrators and non-
administrators.
The installer supports non-interactive modes.
All manifest entries are accurate and not misleading.
The installer comes directly from the publisher's website.

For a complete list of the policies, see Windows Package Manager policies.

Pull request labels

During validation, a series of labels are applied to pull requests to communicate
progress. Some labels will direct you to take action, while others will be directed to the
Windows Package Manager engineering team.

Status labels
The following table describes the status labels you might encounter.

Label Details

Azure- The manifest has completed the test pass. It is waiting for approval. If no issues are
Pipeline- encountered during the test pass it will automatically be approved. If a test fails, it
Passed may be flagged for manual review.

Blocking- This label indicates that the pull request cannot be approved because there is a
Issue blocking issue. You can often tell what the blocking issue is by the included error
label.

Needs- This label indicates that the pull request needs to be investigated by the Windows
Attention Package Manager development team. This is either due to a test failure that needs
manual review, or a comment added to the pull request by the community.

Needs- Indicates there is a failure with the submission. We will reassign the pull request
Author- back to you. If you do not address the issue within 10 days, the bot will close the
Feedback pull request. Needs-Author-Feedback labels are typically added when there was a
failure with the pull request that should be updated, or if the person reviewing the
pull request has a question.

Validation- Indicates that the test pass has been completed successfully and your pull request
Completed will be merged.

Error labels
The following table describes the error labels you might encounter. Not all of the error
cases will be assigned to you immediately. Some may trigger manual validation.

Label Details

Binary- The application included in this pull request failed to pass the Installers Scan test.
Validation- This test is designed to ensure that the application installs on all environments
Error without warnings. For more details on this error, see the Binary validation error
section below.

Error- The Binary-Validation-Test test timed out. The pull request will get assigned to a
Analysis- Windows Package Manager engineer to investigate.
Timeout

Error-Hash- The submitted manifest could not be processed because the InstallerSha256
Mismatch hash provided for the InstallerURL did not match. Update the InstallerSha256 in
the pull request and try again.

Error- The validation service was unable to download the installer. This may be related
Installer- to Azure IP ranges being blocked, or the installer URL may be incorrect. Check
Availability that the InstallerURL is correct and try again. If you feel this has failed in error,
add a comment and the pull request will get assigned to a Windows Package
Manager engineer to investigate.

Manifest- There are either inconsistencies or values not present in the manifest during the
Installer- evaluation of an MSIX package.
Validation-
Error

Manifest- The manifest files must be put into a specific folder structure. This label indicates
Path-Error a problem with the path of your submission. For example, the folder structure
does not have the required format. Update your manifest and path resubmit your
pull request.

Manifest- The submitted manifest contains a syntax error. Address the syntax issue with the
Validation- manifest and re-submit. For details on the manifest format and schema, see
Error required format.

PullRequest- The pull request is invalid because not all files submitted are under manifest
Error folder or there is more than one package or version in the pull request. Update
your pull request to address the issue and try again.

URL- The URLs Validation Test could not locate the URL and responded with a HTTP
Validation- error status code (403 or 404), or the URL reputation test failed. You can identify
Error which URL is in question by looking at the pull request check details. To address
this issue, update the URLs in question to resolve the HTTP error status code. If
the issue is not due to an HTTP error status code, you can submit the URL for
review to avoid the reputation failure.
Label Details

Validation- During dynamic testing, Microsoft Defender reported a problem. To reproduce

Defender- this problem, install your application, then run a Microsoft Defender full scan. If
Error you can reproduce the problem, fix the binary or submit it for analysis for false
positive assistance. If you are unable to reproduce the problem, add a comment
to get the Windows Package Manager engineers to investigate.

Validation- The test has determined the domain if the InstallerURL does not match the
Domain domain expected. The Windows Package Manager policies requires that the
InstallerUrl comes directly from the ISV's release location. If you believe this is a
false detection, add a comment to the pull request to get the Windows Package
Manager engineers to investigate.

Validation- Validation of the Windows Package Manager failed during manual approval. Look
Error at the accompanying comment for next steps.

Validation- During installation testing, the test was unable to locate the primary application.
Executable- Make sure the application installs correctly on all platforms. If your application
Error does not install an application, but should still be included in the repository, add
a comment to the pull request to get the Windows Package Manager engineers
to investigate.

Validation- During installation testing, the application fails to install because the
Hash- InstallerSha256 no longer matches the InstallerURL hash. This can occur if the
Verification- application is behind a vanity URL and the installer was updated without updating
Failed the InstallerSha256. To address this issue, update the InstallerSha256 associated
with the InstallerURL and submit again.

Validation- The URL used for the installer does not use the HTTPS protocol. Update the
HTTP-Error InstallerURL to use HTTPS and resubmit the Pull Request.

Validation- The URL is not coming directly from the ISVs server. Testing has determined a
Indirect-URL redirector has been used. This is not allowed because the Windows Package
Manager policies require that the InstallerUrl comes directly from the ISV's
release location. Remove the redirection and resubmit.

Validation- During manual validation of this package, there was a general error. Look at the
Installation- accompanying comment for next steps.
Error

Validation- This package could not be validated due to a merge conflict. Please address the
Merge- merge conflict and resubmit your pull request.
Conflict

Validation- The MSIX package has a dependency on package that could not be resolved.
MSIX- Update the package to include the missing components or add the dependency
Dependency to the manifest file and resubmit the pull request.
 Label Details

Validation- The test has determined the domain if the InstallerURL does not match the
Unapproved- domain expected. The Windows Package Manager policies requires that the
URL InstallerUrl comes directly from the ISV's release location.

Validation- During installation, the test timed out. This most likely is due to the application
Unattended- not installing silently. It could also be due to some other error being encountered
Failed and stopping the test. Verify that you can install your manifest without user input.
If you need assistance, add a comment to the pull request and the Windows
Package Manager engineers will investigate.

Validation- During uninstall testing, the application did not clean up completely following
Uninstall- uninstall. Look at the accompanying comment for more details.
Error

Validation- The package has a dependency on the C++ runtime that could not be resolved.
VCRuntime- Update the package to include the missing components or add the dependency
Dependency to the manifest file and resubmit the pull request.

Content policy labels

The following table lists content policy labels. If one of these labels is added, something
in the manifest metadata triggered additional manual content review to ensure that the
metadata is following the Windows Package Manager policies.

Label Details

Policy-Test-2.1 See General Content Requirements.

Policy-Test-2.2 See Content Including Names, Logos, Original and Third Party

Policy-Test-2.3 See Risk of Harm.

Policy-Test-2.4 See Defamatory, Libelous, Slanderous and Threatening.

Policy-Test-2.5 See Offensive Content.

Policy-Test-2.6 See Alcohol, Tobacco, Weapons and Drugs.

Policy-Test-2.7 See Adult Content.

Policy-Test-2.8 See Illegal Activity.

Policy-Test-2.9 See Excessive Profanity and Inappropriate Content.

Policy-Test-2.10 See Country/Region Specific Requirements.

Policy-Test-2.11 See Age Ratings.

 Label Details

Policy-Test-2.12 See User Generated Content.

Internal labels

The following table lists internal error labels. When internal errors are encountered, your
pull request will be assigned to the Windows Package Manager engineers to investigate.

Label Details

Internal-Error-Domain An error occurred during the domain validation of the URL.

Internal-Error-Dynamic-Scan An error occurred during the validation of the installed binaries.

Internal-Error-Keyword- An error occurred during the validation of the manifest.

Policy

Internal-Error-Manifest An error occurred during the validation of the manifest.

Internal-Error- An error occurred because the test could not determine the
NoArchitectures architecture if the application.

Internal-Error- An error occurred because the current architecture is not

NoSupportedArchitectures supported.

Internal-Error-PR An error occurred during the processing of the pull request.

Internal-Error-Static-Scan An error occurred during static analysis of the installers.

Internal-Error-URL An error occurred during reputation validation of the installers.

Internal-Error A generic failure or unknown error was encountered during the

test pass.

Binary validation error

If validation of your Pull Request fails the Installers Scan test and receives a Binary-
Validation-Error label, it means that your application failed to install on all
environments.

Installers Scan test

To provide an excellent application installation user experience, the Windows Package
Manager must ensure that all applications install on PCs without errors, regardless of
environment. One key test is to ensure that all applications install without warnings on
various popular antivirus configurations. Windows provides the built-in Microsoft
Defender antivirus program, but many enterprise customers and users use other
antivirus software.

Each submission to the Windows Package Manager Repository is run through several
antivirus programs. These programs all have different virus detection algorithms for
identifying potentially unwanted applications (PUA) and malware.

Address binary validation errors

If an application fails validation, Microsoft first attempts to verify with the antivirus
vendor whether the flagged software is a false positive. In many cases, after notification
and validation, the antivirus vendor updates their algorithm, and the application passes.

In some cases, the antivirus vendor can't determine whether the detected code anomaly
is a false positive. In this case, the application can't be added to the Windows Package
Manager repository. The pull request is rejected with a Binary-Validation-Error label.

If you get a Binary-Validation-Error label on your pull request, update your software to
remove the code detected as PUA.

Sometimes, genuine tools used for debugging and low-level activities appear as PUA to
antivirus software. This is because the necessary debugging code has a similar signature
to unwanted software. Even though this coding practice is legitimate, the Windows
Package Manager repository unfortunately can't allow these applications.

Submission Troubleshooting
If your Windows Package Manager submission fails, you can use the labels described
above to investigate the reason for the failure.

To investigate pull request failures, take the following steps:

1. A pull request failure appears at the bottom of the web page with the string Some
checks were not successful. Select the Details link next to a failed validation to go
to the Azure Pipelines page.
2. On the Azure Pipelines page, select the 0 errors / 0 warnings link.

3. On the next page, select the failed job.

4. The next page shows the output for the failed job. The output should help you
identify the change you need to make to fix the manifest.

In the following example, the failure was during the Installation Validation task.
Submit your manifest to the repository
Article • 03/01/2023

After you create a package manifest that describes your application, you're ready to
submit your manifest to the Windows Package Manager repository. This is a public-
facing repository that contains a collection of manifests that the winget tool can access.
To submit your manifest, you'll upload it to the open source
https://github.com/microsoft/winget-pkgs repository on GitHub.

After you submit a pull request to add a new manifest to the GitHub repository, an
automated process will validate your manifest file and check to make sure the package
complies with the Windows Package Manager polices and is not known to be malicious.
If this validation is successful, your package will be added to the public-facing Windows
Package Manager repository so it can be discovered by the winget client tool. Note the
distinction between the manifests in the open source GitHub repository and the public-
facing Windows Package Manager repository.

） Important

Microsoft reserves the right to refuse a submission for any reason.

Manifest validation
When you submit a manifest to the https://github.com/microsoft/winget-pkgs
repository on GitHub, your manifest will be automatically validated and evaluated for
the safety of the Windows ecosystem. Manifests may also be reviewed manually.

For more information about the validation process, see the validation process section
below.

How to submit your manifest

To submit a manifest to the repository, follow these steps.

Step 1: Validate your manifest

The winget tool provides the validate command to confirm that you have created your
manifest correctly. To validate your manifest, use this command.
 CMD

winget validate \<path-to-the-manifests>

If your validation fails, use the errors to locate the line number and make a correction.
After your manifest is validated, you can submit it to the repository.

Step 2: Test your manifest with Windows Sandbox

The Windows Package Manager repository includes a script that will install the Windows
Package Manager in a Sandbox for testing manifest submissions. To run the powershell
script, navigate to your winget-pkgs repo. From PowerShell, enter the following
command:

PowerShell

powershell .\Tools\SandboxTest.ps1
manifests\m\Microsoft\VisualStudioCode\1.56.0

You may need to update this script with the correct path to your manifest file:
.\Tools\SandboxTest.ps1 <path to manifest or manifest folder>

See the full sandbox test script in the winget-pkgs repo .

Step 3: Clone the repository

To create a fork of the Windows Package Manager Community repository and clone the
repo to your local machine:

1. Go to https://github.com/microsoft/winget-pkgs in your browser and select

Fork.

2. From Windows Command Prompt or PowerShell, use the following command to

clone your fork.

PowerShell

git clone <your-fork-name>

3. If you are entering multiple submissions, create a branch instead of a fork. We

currently allow only one manifest file per submission.
 PowerShell

git checkout -b <branch-name>

Step 4: Add your manifest to the local repository

You must add your manifest files to the repository in the following folder structure:

manifests / letter / publisher / application / version

The manifests folder is the root folder for all manifests in the repository.
The letter folder is the first letter of the publisher name in the lower case. For
example, m of the publisher Microsoft.
The publisher folder is the name of the company that publishes the software. For
example, Microsoft.
The application folder is the name of the application or tool. For example, VSCode.
The version folder is the version of the application or tool. For example, 1.0.0.

The PackageIdentifier and the PackageVersion values in the manifest must match the
publisher, application names and version in the manifest folder path. For more
information, see Create your package manifest.

Step 5: Submit your manifest to the remote repository

You're now ready to push your new manifest to the remote repository.

1. Use the commit command to add files and commit the change and provide
information on the submission.

PowerShell

git commit -m "Submitting ContosoApp version 1.0.0" --all

2. Use the push command to push the changes to the remote repository.

PowerShell

git push

Step 6: Create a pull request

After you push your changes, return to https://github.com/microsoft/winget-pkgs and
create a pull request to merge your fork or branch to the main branch.

Submission process
When you create a pull request, this will start an automated process that validates the
manifests and verifies your pull request. During this process we will run tests against the
installer and installed binaries to validate the submission.

We add labels to your pull request so you can track its progress. For more information
on labels and the process see the pull request labels section below.

Once complete, your submission will be manually reviewed by a moderator, and after it
is approved, your application will be added to the Windows Package Manager catalog.

If there is ever an error during the process, you will be notified and our labels and bot
will assist you in fixing your submission. For the list of common errors, see the validation
process section below.

Validation process
When you create a pull request to submit your manifest to the Windows Package
Manager repository, this will start an automation process that validates the manifest and
processes your pull request. GitHub labels are used to share progress and allow you to
communicate with us.

Submission expectations
All application submissions to the Windows Package Manager repository should adhere
to the Windows Package Manager repository policies.

Expectations for submissions:

The manifest complies with the schema requirements.

All URLs in the manifest lead to safe websites.
The installer and application are virus free. The package may be identified as
malware by mistake. If you believe it is a false positive you can submit the installer
 to the Microsoft Defender team for analysis .
The application installs and uninstalls correctly for both administrators and non-
administrators.
The installer supports non-interactive modes.
All manifest entries are accurate and not misleading.
The installer comes directly from the publisher's website.

For a complete list of the policies, see Windows Package Manager policies.

Pull request labels

During validation, a series of labels are applied to pull requests to communicate
progress. Some labels will direct you to take action, while others will be directed to the
Windows Package Manager engineering team.

Status labels
The following table describes the status labels you might encounter.

Label Details

Azure- The manifest has completed the test pass. It is waiting for approval. If no issues are
Pipeline- encountered during the test pass it will automatically be approved. If a test fails, it
Passed may be flagged for manual review.

Blocking- This label indicates that the pull request cannot be approved because there is a
Issue blocking issue. You can often tell what the blocking issue is by the included error
label.

Needs- This label indicates that the pull request needs to be investigated by the Windows
Attention Package Manager development team. This is either due to a test failure that needs
manual review, or a comment added to the pull request by the community.

Needs- Indicates there is a failure with the submission. We will reassign the pull request
Author- back to you. If you do not address the issue within 10 days, the bot will close the
Feedback pull request. Needs-Author-Feedback labels are typically added when there was a
failure with the pull request that should be updated, or if the person reviewing the
pull request has a question.

Validation- Indicates that the test pass has been completed successfully and your pull request
Completed will be merged.

Error labels
The following table describes the error labels you might encounter. Not all of the error
cases will be assigned to you immediately. Some may trigger manual validation.

Label Details

Binary- The application included in this pull request failed to pass the Installers Scan test.
Validation- This test is designed to ensure that the application installs on all environments
Error without warnings. For more details on this error, see the Binary validation error
section below.

Error- The Binary-Validation-Test test timed out. The pull request will get assigned to a
Analysis- Windows Package Manager engineer to investigate.
Timeout

Error-Hash- The submitted manifest could not be processed because the InstallerSha256
Mismatch hash provided for the InstallerURL did not match. Update the InstallerSha256 in
the pull request and try again.

Error- The validation service was unable to download the installer. This may be related
Installer- to Azure IP ranges being blocked, or the installer URL may be incorrect. Check
Availability that the InstallerURL is correct and try again. If you feel this has failed in error,
add a comment and the pull request will get assigned to a Windows Package
Manager engineer to investigate.

Manifest- There are either inconsistencies or values not present in the manifest during the
Installer- evaluation of an MSIX package.
Validation-
Error

Manifest- The manifest files must be put into a specific folder structure. This label indicates
Path-Error a problem with the path of your submission. For example, the folder structure
does not have the required format. Update your manifest and path resubmit your
pull request.

Manifest- The submitted manifest contains a syntax error. Address the syntax issue with the
Validation- manifest and re-submit. For details on the manifest format and schema, see
Error required format.

PullRequest- The pull request is invalid because not all files submitted are under manifest
Error folder or there is more than one package or version in the pull request. Update
your pull request to address the issue and try again.

URL- The URLs Validation Test could not locate the URL and responded with a HTTP
Validation- error status code (403 or 404), or the URL reputation test failed. You can identify
Error which URL is in question by looking at the pull request check details. To address
this issue, update the URLs in question to resolve the HTTP error status code. If
the issue is not due to an HTTP error status code, you can submit the URL for
review to avoid the reputation failure.
Label Details

Validation- During dynamic testing, Microsoft Defender reported a problem. To reproduce

Defender- this problem, install your application, then run a Microsoft Defender full scan. If
Error you can reproduce the problem, fix the binary or submit it for analysis for false
positive assistance. If you are unable to reproduce the problem, add a comment
to get the Windows Package Manager engineers to investigate.

Validation- The test has determined the domain if the InstallerURL does not match the
Domain domain expected. The Windows Package Manager policies requires that the
InstallerUrl comes directly from the ISV's release location. If you believe this is a
false detection, add a comment to the pull request to get the Windows Package
Manager engineers to investigate.

Validation- Validation of the Windows Package Manager failed during manual approval. Look
Error at the accompanying comment for next steps.

Validation- During installation testing, the test was unable to locate the primary application.
Executable- Make sure the application installs correctly on all platforms. If your application
Error does not install an application, but should still be included in the repository, add
a comment to the pull request to get the Windows Package Manager engineers
to investigate.

Validation- During installation testing, the application fails to install because the
Hash- InstallerSha256 no longer matches the InstallerURL hash. This can occur if the
Verification- application is behind a vanity URL and the installer was updated without updating
Failed the InstallerSha256. To address this issue, update the InstallerSha256 associated
with the InstallerURL and submit again.

Validation- The URL used for the installer does not use the HTTPS protocol. Update the
HTTP-Error InstallerURL to use HTTPS and resubmit the Pull Request.

Validation- The URL is not coming directly from the ISVs server. Testing has determined a
Indirect-URL redirector has been used. This is not allowed because the Windows Package
Manager policies require that the InstallerUrl comes directly from the ISV's
release location. Remove the redirection and resubmit.

Validation- During manual validation of this package, there was a general error. Look at the
Installation- accompanying comment for next steps.
Error

Validation- This package could not be validated due to a merge conflict. Please address the
Merge- merge conflict and resubmit your pull request.
Conflict

Validation- The MSIX package has a dependency on package that could not be resolved.
MSIX- Update the package to include the missing components or add the dependency
Dependency to the manifest file and resubmit the pull request.
 Label Details

Validation- The test has determined the domain if the InstallerURL does not match the
Unapproved- domain expected. The Windows Package Manager policies requires that the
URL InstallerUrl comes directly from the ISV's release location.

Validation- During installation, the test timed out. This most likely is due to the application
Unattended- not installing silently. It could also be due to some other error being encountered
Failed and stopping the test. Verify that you can install your manifest without user input.
If you need assistance, add a comment to the pull request and the Windows
Package Manager engineers will investigate.

Validation- During uninstall testing, the application did not clean up completely following
Uninstall- uninstall. Look at the accompanying comment for more details.
Error

Validation- The package has a dependency on the C++ runtime that could not be resolved.
VCRuntime- Update the package to include the missing components or add the dependency
Dependency to the manifest file and resubmit the pull request.

Content policy labels

The following table lists content policy labels. If one of these labels is added, something
in the manifest metadata triggered additional manual content review to ensure that the
metadata is following the Windows Package Manager policies.

Label Details

Policy-Test-2.1 See General Content Requirements.

Policy-Test-2.2 See Content Including Names, Logos, Original and Third Party

Policy-Test-2.3 See Risk of Harm.

Policy-Test-2.4 See Defamatory, Libelous, Slanderous and Threatening.

Policy-Test-2.5 See Offensive Content.

Policy-Test-2.6 See Alcohol, Tobacco, Weapons and Drugs.

Policy-Test-2.7 See Adult Content.

Policy-Test-2.8 See Illegal Activity.

Policy-Test-2.9 See Excessive Profanity and Inappropriate Content.

Policy-Test-2.10 See Country/Region Specific Requirements.

Policy-Test-2.11 See Age Ratings.

 Label Details

Policy-Test-2.12 See User Generated Content.

Internal labels

The following table lists internal error labels. When internal errors are encountered, your
pull request will be assigned to the Windows Package Manager engineers to investigate.

Label Details

Internal-Error-Domain An error occurred during the domain validation of the URL.

Internal-Error-Dynamic-Scan An error occurred during the validation of the installed binaries.

Internal-Error-Keyword- An error occurred during the validation of the manifest.

Policy

Internal-Error-Manifest An error occurred during the validation of the manifest.

Internal-Error- An error occurred because the test could not determine the
NoArchitectures architecture if the application.

Internal-Error- An error occurred because the current architecture is not

NoSupportedArchitectures supported.

Internal-Error-PR An error occurred during the processing of the pull request.

Internal-Error-Static-Scan An error occurred during static analysis of the installers.

Internal-Error-URL An error occurred during reputation validation of the installers.

Internal-Error A generic failure or unknown error was encountered during the

test pass.

Binary validation error

If validation of your Pull Request fails the Installers Scan test and receives a Binary-
Validation-Error label, it means that your application failed to install on all
environments.

Installers Scan test

To provide an excellent application installation user experience, the Windows Package
Manager must ensure that all applications install on PCs without errors, regardless of
environment. One key test is to ensure that all applications install without warnings on
various popular antivirus configurations. Windows provides the built-in Microsoft
Defender antivirus program, but many enterprise customers and users use other
antivirus software.

Each submission to the Windows Package Manager Repository is run through several
antivirus programs. These programs all have different virus detection algorithms for
identifying potentially unwanted applications (PUA) and malware.

Address binary validation errors

If an application fails validation, Microsoft first attempts to verify with the antivirus
vendor whether the flagged software is a false positive. In many cases, after notification
and validation, the antivirus vendor updates their algorithm, and the application passes.

In some cases, the antivirus vendor can't determine whether the detected code anomaly
is a false positive. In this case, the application can't be added to the Windows Package
Manager repository. The pull request is rejected with a Binary-Validation-Error label.

If you get a Binary-Validation-Error label on your pull request, update your software to
remove the code detected as PUA.

Sometimes, genuine tools used for debugging and low-level activities appear as PUA to
antivirus software. This is because the necessary debugging code has a similar signature
to unwanted software. Even though this coding practice is legitimate, the Windows
Package Manager repository unfortunately can't allow these applications.

Submission Troubleshooting
If your Windows Package Manager submission fails, you can use the labels described
above to investigate the reason for the failure.

To investigate pull request failures, take the following steps:

1. A pull request failure appears at the bottom of the web page with the string Some
checks were not successful. Select the Details link next to a failed validation to go
to the Azure Pipelines page.
2. On the Azure Pipelines page, select the 0 errors / 0 warnings link.

3. On the next page, select the failed job.

4. The next page shows the output for the failed job. The output should help you
identify the change you need to make to fix the manifest.

In the following example, the failure was during the Installation Validation task.
Windows Package Manager repository
policies
Article • 05/05/2023

Document version: 1.0

Document date: May 22, 2021

Effective date: May 22, 2021

Thank you for your interest in providing a Product to the Windows Package Manager
repository.

Product refers to content in whatever form including, but not limited to, apps,
games, titles, and any additional content sold or offered from within a Product.
Submission refers to a pull request of manifest files and includes but is not
limited to the Product and metadata about the Product.

A few principles to get you started:

Offer unique and distinct value within your Submission. Provide a compelling
reason to download the Product from the Windows Package Manager
repository .
Don’t mislead our customers about what your Submission can do, who is offering
it, etc.
Don’t attempt to cheat customers, the system or the ecosystem. There is no place
in the repository for any kind of fraud, be it ratings and review manipulation, credit
card fraud or other fraudulent activity.

Adhering to these policies should help you make choices that enhance your
Submission's appeal and audience.

Your Submissions are crucial to the experience of hundreds of millions of customers. We

can't wait to see what you create and want to help deliver your Submissions to the
world.

If you have feedback on the policies or Windows Package Manager, let us know by
commenting in our GitHub issues forum

Table of Contents
Product Policies:
 1.1 Distinct Function & Value; Accurate Representation
1.2 Security
1.3 Product is Testable
1.4 Usability
1.5 Personal Information
1.6 Capabilities
1.7 Localization
1.8 Financial Transactions
1.9 Notifications
1.10 Advertising Conduct and Content

Content Policies:

2.1 General Content Requirements

2.2 Content Including Names, Logos, Original and Third Party
2.3 Risk of Harm
2.4 Defamatory, Libelous, Slanderous and Threatening
2.5 Offensive Content
2.6 Alcohol, Tobacco, Weapons and Drugs
2.7 Adult Content
2.8 Illegal Activity
2.9 Excessive Profanity and Inappropriate Content
2.10 Country/Region Specific Requirements
2.11 Age Ratings
2.12 User Generated Content

Product Policies

1.1 Distinct Function & Value; Accurate Representation

The Product and its associated metadata, including but not limited to the app title,
description, screenshots, trailers, content rating and Product category, must accurately
and clearly reflect the source, functionality, and features of the Product.

1.1.1
All aspects of the Product should accurately describe the functions, features and any
important limitations of the Product.

1.1.2
Tags may not exceed 16 unique tags and should be relevant to the Product.

1.1.3
The Product must have distinct and informative metadata and must provide a valuable
and quality user experience.

1.1.4
The InstallerUrl must be the ISV's release location for the Product. Products from
download websites will not be allowed.

1.2 Security
The Product must not jeopardize or compromise user security, or the security or
functionality of the device, system or related systems.

1.2.1
The Product must not attempt to change or extend its described functionality through
any form of dynamic inclusion of code that is in violation of Windows Package Manager
Policies. The Product should not, for example, download a remote script and
subsequently execute that script in a manner that is not consistent with the described
functionality.

1.2.2
The Product must not contain or enable malware as defined by the Microsoft criteria for
Unwanted and Malicious Software.

1.2.3
The Product may contain fully integrated middleware (such as third-party cross-platform
engines and third-party analytics services).

The Product may depend on non-integrated software (such as another Product, module,
or service) to deliver its primary functionality.

1.3 Product is Testable

The Product must be testable. If it is not possible to test your submitted Product for any
reason your Product may fail this requirement.

1.4 Usability
The Product should meet usability standards, including, but not limited to, those listed
in the subsections below.

1.4.1
The Product should support the devices and platforms on which they are downloaded,
including compatibility with the software, hardware and screen resolution requirements
specified by the Product. If the Product is downloaded on a device with which it is not
compatible, it should detect that at launch and display a message to the customer
detailing the requirements.

1.4.2
The Product should continue to run and remain responsive to user input. Products
should shut down gracefully and not close unexpectedly. The Product should handle
exceptions raised by any of the managed or native system APIs and remain responsive
to user input after the exception is handled.

1.4.3
The Product should start up promptly and must stay responsive to user input.

1.5 Personal Information

The following requirements apply to Products that access Personal Information. Personal
Information includes all information or data that identifies or could be used to identify a
person, or that is associated with such information or data.

1.5.1
If the Product accesses, collects or transmits Personal Information, or if otherwise
required by law, it should maintain a privacy policy. The submission, should include the
PrivacyUrl which links to the privacy policy of the Product.

1.5.2
If the Product publishes the Personal Information of customers of the Product to an
outside service or third party, the Product should only do so after obtaining opt-in
consent from those customers. Opt-in consent means the customer gives their express
permission in the Product user interface for the requested activity, after the Product has:

Described to the customer how the information will be accessed, used or shared,
indicating the types of parties to whom it is disclosed, and
Provided the customer a mechanism in the Product user interface through which
they can later rescind this permission and opt-out.

1.5.3
If the Product publishes a person’s Personal Information to an outside service or third
party through the Product or its metadata, but the person whose information is being
shared is not a customer of the Product, the Product must obtain express written
consent to publish that Personal Information, and must permit the person whose
information is shared to withdraw that consent at any time. If the Product provides a
customer with access to another person’s Personal Information, this requirement would
also apply.

1.5.4
If the Product collects, stores or transmits Personal Information, it must do so securely,
by using modern cryptography methods.

1.5.5
The Product must not collect, store or transmit highly sensitive personal information,
such as health or financial data, unless the information is related to the Product’s
functionality. The Product must also obtain express user consent before collecting,
storing or transmitting such information. The Product’s privacy policy must clearly tell
the user when and why it is collecting Personal Information and how it will be used.

1.5.6
If the Product supports Microsoft identity authentication it must do so only by using
Microsoft-approved methods.

1.5.7
Products that receive device location must provide settings that allow the user to enable
and disable the Product's access to and use of location from the Location Service API.

1.6 Capabilities
If the Product declares the use of capabilities, then the capabilities the Product declares
must legitimately relate to the functions of the Product. The Product must not
circumvent operating system checks for capability usage.

1.7 Localization
You should localize your Product for all languages that it supports. The text of your
product’s description should be localized in each language that you declare. If your
product is localized such that some features are not available in a localized version, you
should clearly state or display the limits of localization in the product description. The
experience provided by a product must be reasonably similar in all languages that it
supports.

1.8 Financial Transactions

If your product includes in-product purchase, subscriptions, virtual currency, billing
functionality or captures financial information, the following requirements apply:

1.8.1
In-product offerings sold in your product cannot be converted to any legally valid
currency (for example, USD, Euro, etc.) or any physical goods or services.

1.8.2
The Product must use a secure purchase API for purchases of physical goods or services,
and a secure purchase API for payments made in connection with real world gambling
or charitable contributions. If the Product is used to facilitate or collect charitable
contributions or to conduct a promotional sweepstakes or contest, it must do so in
compliance with applicable law. The Product must also state clearly that Microsoft is not
the fundraiser or sponsor of the promotion.

The Product must use a secure purchase API to receive voluntary donations from users.

The following requirements apply to your use of a secure purchase API:

 At the time of the transaction or when the Product collects any payment or
financial information from the customer, the Product must identify the commerce
transaction provider, authenticate the user, and obtain user confirmation for the
transaction.
The product can offer the user the ability to save this authentication, but the user
must have the ability to either require an authentication on every transaction or to
turn off in-product transactions.
If the product collects credit card information or uses a third-party payment
processor that collects credit card information, the payment processing must meet
the current PCI Data Security Standard (PCI DSS).

1.8.3
The product and its associated metadata must provide information about the types of
in-product purchases offered and the range of prices. The Product not mislead
customers and must be clear about the nature of the in-product promotions and
offerings including the scope and terms of any trial experiences. If the Product restricts
access to user-created content during or after a trial, it must notify users in advance. In
addition, the Product must make it clear to users that they are initiating a purchase
option in the Product.

If your game offers “loot boxes” or other mechanisms that provide randomized virtual
items, then you must disclose the odds of receiving each item to customers prior to
purchase. These disclosures may appear: in-product, such as in an in-app store, on the
Microsoft Store Product Description Page (PDP), and/or on a developer or publisher
website, with a link from the Store Product Description Page (PDP) and/or in-app.

1.8.4
All pricing, including sales or discounting, for your digital products or services shall
comply with all applicable laws, regulations and regulatory guidelines, including without
limitation, the Federal Trade Commission Guides Against Deceptive Pricing .

1.9 Notifications
If the Product supports notifications, then the Product must respect system settings for
notifications and remain functional when they are disabled. This includes the
presentation of ads and notifications to the customer, which must also be consistent
with the customer’s preferences, whether the notifications are provided by the Microsoft
Push Notification Service (MPNS), Windows Push Notification Service (WNS) or any
other service. If the customer disables notifications, either on an Product-specific or
system-wide basis, the Product must remain functional.

1.10 Advertising Conduct and Content

For all advertising related activities, the following requirements apply:

1.10.1
The primary purpose of the Product should not be to get users to click ads.
The Product may not do anything that interferes with or diminishes the visibility,
value, or quality of any ads it displays.
The Product must respect advertising ID settings that the user has selected.
All advertising must be truthful, non-misleading and comply with all applicable
laws, regulations, and regulatory guidelines.

Content Policies
The following policies apply to content and metadata (including publisher name,
Product name, Product icon, Product description, Product screenshots, Product trailers
and trailer thumbnails, and any other Product metadata) offered for distribution in the
Windows Package Manager repository. Content means the Product name, publisher
name, Product icon, Product description, the images, sounds, videos and text contained
in the Product, the tiles, notifications, error messages or ads exposed through the
Product, and anything that’s delivered from a server or that the Product connects to.
Because Product and the Windows Package Manager repository are used around the
world, these requirements will be interpreted and applied in the context of regional and
cultural norms.

2.1 General Content Requirements

Metadata and other content you submit to accompany your submission may contain
only content that would merit a rating of PEGI 12, ESRB EVERYONE 10+, or lower.

2.2 Content Including Names, Logos, Original and Third

Party
All content in the Product and associated metadata must be either originally created by
the application provider, appropriately licensed from the third-party rights holder, used
as permitted by the rights holder, or used as otherwise permitted by law.
2.3 Risk of Harm

2.3.1
The Product must not contain any content that facilitates or glamorizes the following
real world activities: (a) extreme or gratuitous violence; (b) human rights violations; (c)
the creation of illegal weapons; or (d) the use of weapons against a person, animal, or
real or personal property.

2.3.2
The Product must not: (a) pose a safety risk to, nor result in discomfort, injury or any
other harm to end users or to any other person or animal; or (b) pose a risk of or result
in damage to real or personal property. You are solely responsible for all Product safety
testing, certificate acquisition, and implementation of any appropriate feature
safeguards. You will not disable any platform safety or comfort features, and you must
include all legally required and industry-standard warnings, notices, and disclaimers in
the Product.

2.4 Defamatory, Libelous, Slanderous and Threatening

The Product must not contain any content that is defamatory, libelous, slanderous, or
threatening.

2.5 Offensive Content

The Product and associated metadata must not contain potentially sensitive or offensive
content. Content may be considered sensitive or offensive in certain countries/regions
because of local laws or cultural norms. In addition, the Product and associated
metadata must not contain content that advocates discrimination, hatred, or violence
based on considerations of race, ethnicity, national origin, language, gender, age,
disability, religion, sexual orientation, status as a veteran, or membership in any other
social group.

2.6 Alcohol, Tobacco, Weapons and Drugs

The Product must not contain any content that facilitates or glamorizes excessive or
irresponsible use of alcohol or tobacco Products, drugs, or weapons.
2.7 Adult Content
The Product must not contain or display content that a reasonable person would
consider pornographic or sexually explicit.

2.8 Illegal Activity

The Product must not contain content or functionality that encourages, facilitates or
glamorizes illegal activity in the real world.

2.9 Excessive Profanity and Inappropriate Content

The Product must not contain excessive or gratuitous profanity.
The Product must not contain or display content that a reasonable person would
consider to be obscene.

2.10 Country/Region Specific Requirements

Content that is offensive in any country/region to which the Product is targeted is not
allowed. Content may be considered offensive in certain countries/regions because of
local laws or cultural norms. Examples of potentially offensive content in certain
countries/regions include the following:

China

Prohibited sexual content

Disputed territory or region references
Providing or enabling access to content or services that are illegal under applicable
local law

2.11 Age Ratings

The Product should have a age rating that would merit a rating of PEGI 12, ESRB
EVERYONE 10+, or lower.

2.11.1
If the Product provides content (such as user-generated, retail or other web-based
content) that might be appropriate for a higher age rating than its assigned rating, you
must enable users to opt in to receiving such content by using a content filter or by
signing in with a pre-existing account.
2.12 User Generated Content
User Generated Content (UGC) is content that users contribute to an app or Product and
which can be viewed or accessed by other users in an online state. If the Product
contains UGC, the Product should:

Publish and make available to users a Product terms of service and/or content
guidelines for User Generated Content either in Product or on the Product website.
Provide a means for users to report inappropriate content within the Product to
the developer for review and removal/disablement if in violation of content
guidelines and/or implement a method for proactive detection of inappropriate or
harmful UGC.
Remove or disable UGC when requested by Microsoft.

See also
Windows Package Manager Code of Conduct
Windows Package Manager Contributing requirements
Microsoft PowerToys: Utilities to
customize Windows
Article • 04/12/2024

Microsoft PowerToys is a set of utilities for power users to tune and streamline their
Windows experience for greater productivity.

Install PowerToys

Processor architecture support

x64: Supported
ARM64: Supported

Current PowerToy utilities

The currently available utilities include:

Always On Top

Always On Top enables you to pin windows above other windows with a quick key
shortcut ( ⊞ Win + Ctrl + T ).

PowerToys Awake
PowerToys Awake is designed to keep a computer awake without having to manage its
power & sleep settings. This behavior can be helpful when running time-consuming
tasks, ensuring that the computer does not go to sleep or turns off its displays.

Color Picker

Color Picker is a system-wide color picking utility activated with ⊞ Win + Shift + C . Pick
colors from anywhere on the screen, the picker automatically copies the color to your
clipboard in a set format. Color Picker contains an editor that shows a history of
previously picked colors, allows you to fine-tune the selected color and to copy different
string representations. This code is based on Martin Chrzan's Color Picker.

Command Not Found

Command Not Found is a PowerShell 7 module that detects an error thrown by a
command and suggests a relevant WinGet package to install, if available.

Crop And Lock

Crop And Lock is a utility that creates a new window that's a crop or a thumbnail of
another window.

Environment Variables
Environment Variables offers an easy and convenient way to manage environment
variables. You can create profiles for managing a set of variables together.

FancyZones

FancyZones is a window manager that makes it easy to create complex window layouts
and quickly position windows into those layouts.

File Explorer add-ons

File Explorer add-ons enable Preview pane and thumbnail rendering in File Explorer to
display a variety of file types. To open the Preview pane, go to View in File Explorer and
select Preview Pane.

File Locksmith

File Locksmith is a Windows shell extension to check which files are in use and by which
processes. Right-click on one or more selected files in File Explorer and select Unlock
with File Locksmith.

Hosts File Editor

Hosts File Editor is a convenient way to edit the 'Hosts' file that contains domain names
and matching IP addresses, acting as a map to identify and locate hosts on IP networks.

Image Resizer

Image Resizer is a Windows Shell extension for quickly resizing images. With a right click
from File Explorer, instantly resize one or many images. This code is based on Brice
Lambson's Image Resizer.

Keyboard Manager
Keyboard Manager allows you to customize the keyboard to be more productive by
remapping keys and creating your own keyboard shortcuts.

Mouse utilities

Mouse utilities add functionality to enhance your mouse and cursor. With Find My
Mouse, quickly locate your mouse's position with a spotlight that focuses on your
cursor. This feature is based on source code developed by Raymond Chen. Mouse
Highlighter displays visual indicators when basic mouse buttons are clicked. Mouse
Jump allows a quick jump on large displays. Mouse Pointer Crosshairs draws crosshairs
centered on the mouse pointer.

Mouse Without Borders

Use Mouse Without Borders to interact with multiple computers from the same
keyboard and mouse, sharing clipboard contents and files between the machines
seamlessly.

Paste As Plain Text

Paste As Plain Text allows you to paste text from your clipboard, excluding text-
formatting, with a quick key shortcut ( ⊞ Win + Ctrl + Alt + V ).

Peek
Peek allows you to preview file content without the need to open multiple applications
or interrupt your workflow. Select the file and use the shortcut ( Ctrl + Space )

PowerRename

Use PowerRename to perform bulk renaming; searching and replacing file names. It
includes advanced features, such as using regular expressions, targeting specific file
types, previewing expected results, and the ability to undo changes. This code is based
on Chris Davis's SmartRename.

PowerToys Run
PowerToys Run can help you search and open your app instantly. To open, use the
shortcut Alt + Space and start typing. It is open source and modular for additional
plugins.

Quick Accent

Quick Accent is an alternative way to type accented characters, useful for when a
keyboard doesn't support that specific character with a quick key combo.

Registry Preview
Registry Preview is a utility to visualize and edit Windows Registry files.

Screen Ruler

Use Screen Ruler to quickly measure pixels on your screen based with image edge
detection. To activate, use the shortcut ⊞ Win + Shift + M . This was inspired by Pete
Blois's Rooler.

Shortcut Guide
Windows key shortcut guide appears when you press ⊞ Win + Shift + / (or as we like
to think, ⊞ Win + ? ) and shows the available shortcuts for the current state of the
desktop. You can also use press and hold ⊞ Win .

Text Extractor

Text Extractor is a convenient way to copy text from anywhere on your screen. To
activate, use the shortcut ⊞ Win + Shift + T . This code is based on Joe Finney's Text
Grab.

Video Conference Mute

Video Conference Mute is a quick way to globally "mute" both your microphone and
camera using ⊞ Win + Shift + Q while on a conference call, regardless of the application
that currently has focus.

Languages
Currently, PowerToys is available in the following languages: Arabic (Saudi Arabia),
Chinese (simplified), Chinese (traditional), Czech, Dutch, English, French, German,
Hebrew, Hungarian, Italian, Japanese, Korean, Persian, Polish, Portuguese, Portuguese
(Brazil), Russian, Spanish, Turkish, Ukrainian.

PowerToys video walk-through

In this video, Clint Rutkas (PM for PowerToys) walks through how to install and use the
various utilities available, in addition to sharing some tips, info on how to contribute,
and more.

[!VIDEO https://learn.microsoft.com/shows/Tabs-vs-Spaces/PowerToys-Utilities-to-
customize-Windows-10/player?format=ny]

Known issues
Search known issues or file a new issue in the Issues tab of the PowerToys repository
on GitHub. If you don't find the issue you are experiencing, you can Report a Bug on
the PowerToys product repo.

Contribute to PowerToys (Open Source)

PowerToys welcomes your contributions! The PowerToys development team is excited to
partner with the power user community to build tools that help users get the most out
of Windows. There are a variety of ways to contribute:

Write a tech spec

Submit a design concept or recommendation
Contribute to documentation
Identify and fix bugs in the source code
Code new features and PowerToy utilities

Before starting work on a feature that you would like to contribute, read the
Contributor's Guide . The PowerToys team will be happy to work with you to figure
out the best approach, provide guidance and mentorship throughout feature
development, and help avoid any wasted or duplicate effort.

PowerToys release notes

PowerToys release notes are listed on the install page of the GitHub repo. For
reference, you can also find the Release checklist on the PowerToys wiki.

PowerToys history
Inspired by the Windows 95 era PowerToys project , this reboot provides power users
with ways to squeeze more efficiency out of the Windows shell and customize it for
individual workflows. An overview of the original PowerToys can be found here: Using
Windows 95 PowerToys .

PowerToys roadmap
PowerToys is a rapid-incubation, open source team aimed at providing power users
ways to squeeze more efficiency out of the Windows shell and customize it for
individual workflows. Work priorities will consistently be examined, reassessed, and
adjusted with the aim of improving our users productivity.

New specs for possible PowerToys

Backlog priority list

６ Collaborate with us on Windows developer

feedback
GitHub Windows developer is an open
source project. Select a link to
The source for this content can provide feedback:
be found on GitHub, where you
can also create and review  Open a documentation issue
issues and pull requests. For
more information, see our  Provide product feedback
contributor guide.
Installing PowerToys
Article • 04/12/2024

We recommend installing PowerToys via GitHub or Microsoft Store, but alternative

install methods are also listed if you prefer using a package manager.

Requirements
Supported Operating Systems:
Windows 11 (all versions)
Windows 10 v2004 (19041) or newer
System architecture
x64 and Arm64 architectures are currently supported.
Our installer will install the following runtimes:
Microsoft Edge WebView2 Runtime bootstrapper (this will always install the
latest version available)

To see if your machine meets these requirements, check your Windows version and
build number by opening a Run dialog (Win+R), then type winver and select OK or
Enter . Alternatively, enter the ver command in Windows Command Prompt. You may
be able to update to the latest Windows version in Windows Update.

Installing with Windows executable file from

GitHub
Install PowerToys

To install PowerToys using a Windows executable file:

1. Visit the Microsoft PowerToys GitHub releases page .

2. Select the Assets drop-down menu to display the files for the release.
3. Select the PowerToysSetup-0.##.#-x64.exe or PowerToysSetup-0.##.#-arm64.exe file
to download the PowerToys executable installer.
4. Once downloaded, open the executable file and follow the installation prompts.

Installing with Microsoft Store

Install from the Microsoft Store's PowerToys page .
Installing with Windows Package Manager
To install PowerToys using the Windows Package Manager, it is as simple as running the
following command from the command line / PowerShell:

PowerShell

winget install Microsoft.PowerToys --source winget

PowerToys supports configuring through winget configure using Desired State

Configuration.

Installer arguments
The installer executable accepts the Microsoft Standard Installer command-line options.

Here are the common commands you may want:

ﾉ Expand table

Command Abbreviation Function

/quiet /q Silent install

/silent /s Silent install

/passive progress bar only install

/layout create a local image of the bootstrapper

/log /l log to a specific file

Extracting the MSI from the bundle

Make sure to have WiX Toolset v3 installed. The command doesn't work with WiX
Toolset v4.

This PowerShell example assumes the default install location for WiX Toolset and the
PowerToys installer downloaded to the desktop.

PowerShell

cd $Env:WIX\"bin"

# dark.exe -x OUTPUT_FOLDER INSTALLER_PATH

 .\dark.exe -x ${Env:\USERPROFILE}"\Desktop\extractedPath"
${Env:\USERPROFILE}"\Desktop\PowerToysSetup-0.53.0-x64.exe"

Fixes for uninstalling 0.51 and earlier builds issues

If you have an issue where the MSI is not accessible, you can download the installer that
corresponds with the installed version via the PowerToys release page and then run
the following command. You'll need to change EXECUTABLE_INSTALLER_NAME to the
actual file name.

In PowerShell, run .\EXECUTABLE_INSTALLER_NAME.exe --extract_msi and this will extract

the MSI to your desktop.

Clean-up scripts
In case there are problems with uninstalling a version, there are cleanup scripts
available:

<github.com/microsoft/PowerToys/tree/main/tools/CleanUp_tool>
<github.com/microsoft/PowerToys/tree/main/tools/CleanUp_tool_powershell_script>

Community-driven install tools

These community-driven alternative install methods are not officially supported and the
PowerToys team does not update or manage these packages.

Installing with Chocolatey

To install PowerToys using Chocolatey , run the following command from your
command line / PowerShell:

PowerShell

choco install powertoys

To upgrade PowerToys, run:

PowerShell

choco upgrade powertoys

If you have issues when installing/upgrading, create an issue at the maintainers GitHub
repository or follow the Chocolatey triage process .

Installing with Scoop

To install PowerToys using Scoop , run the following command from the command line
/ PowerShell:

PowerShell

scoop bucket add extras

scoop install powertoys

To update PowerToys, run the following command from the command line / PowerShell:

PowerShell

scoop update powertoys

If you have issues when installing/updating, file an issue in the Scoop repo on GitHub .

After installation
After successfully installing PowerToys, an overview window will display with
introductory guidance on each of the available utilities.

Updates
PowerToys uses an auto-updater that checks for new versions when the app is running.
If enabled, a toast notification will appear when an update is available. Updates can also
be checked for manually from the PowerToys Settings.
６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
General settings for PowerToys
Article • 04/12/2024

The general section of Microsoft PowerToys contains the following settings:

Version
Here you can check for new updates and if one is available, you can download and
install it. You can set if updates should be downloaded automatically.

Administrator mode
Read more about the administrator mode in the PowerToys running with administrator
permissions section of the documentation.

Appearance & behavior

App theme
Here you can set the theme of the PowerToys settings app and the PowerToys flyout:
Dark, Light, or Windows default.

Run at startup
If activated, PowerToys will start automatically when you log in to Windows.

Backup & restore

Set a location where you want to save your PowerToys settings. You can also restore
your settings from a backup.

Experimentation
Will activate experimentation with new features on Windows Insider builds, if available.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
PowerToys running with administrator
permissions
Article • 08/09/2023

When running any application as an administrator (also referred to as elevated

permissions), PowerToys may not work correctly when the elevated applications are in
focus or trying to interact with a PowerToys feature like FancyZones. This can be
addressed by also running PowerToys as administrator.

Options
There are two options for PowerToys to support applications running as administrator
(with elevated permissions):

1. Recommended: PowerToys will display a notification when an elevated process is

detected. Open PowerToys Settings. On the General tab, select Restart as
administrator.
2. Enable Always run as administrator in the PowerToys Settings.

Support for admin mode with PowerToys

PowerToys needs elevated administrator permission when writing protected system
settings or when interacting with other applications that are running in administrator
mode. If those applications are in focus, PowerToys may not function unless it is
elevated as well.

These are the two scenarios PowerToys will not work in:

Intercepting certain types of keyboard strokes

Resizing / moving windows

Affected PowerToys utilities

Admin mode permissions may be required in the following scenarios:

Always On Top
Pin windows that are elevated
FancyZones
Snapping an elevated window (e.g. Task Manager) into a Fancy Zone
Moving the elevated window to a different zone
 File Locksmith
End elevated processes
Hosts file editor
Keyboard remapper
Key to key remapping
Global level shortcuts remapping
App-targeted shortcuts remapping
Mouse without Borders
Use Service
PowerToys Run
Use shortcut
Registry Preview
Write keys to the registry
Shortcut guide
Display shortcut
Video Conference Mute

Run as administrator: elevated processes

explained
Windows applications run in User mode by default. To run an application in
Administrative mode or as an elevated process means that app will run with additional
access to the operating system. Most apps do not need to run with elevated permission.
A common scenario, however, for requiring administrator permission would be to run
certain PowerShell commands or edit the registry.

The simplest way to run an app or program in administrative mode is to right-click the
program and select Run as administrator. If the current user is not an administrator,
Windows will ask for the administrator username and password.

If you see this User Account Control prompt, the application is requesting administrator
level elevated permission:
In the case of an elevated command line, typically the text "Administrator" will be
included in the title bar.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Desired State Configuration
Article • 04/09/2024

Since version 0.80, the PowerToys installer has been released on GitHub with
Microsoft.PowerToys.Configure DSC resource that allows you to configure PowerToys using

a Winget configuration file.

Installation

Prerequisites
PSDesiredStateConfiguration 2.0.7 or later: Refer to the PowerShell DSC documentation
for installation instructions.
PowerShell 7.2 or higher.
WinGet version v1.6.2631 or later .

Download
Microsoft.PowerToys.Configure is installed with PowerToys. Depending on the installer type,
it's installed as follows:

For the per-user install scope, the module is located in

%USERPROFILE%\Documents\PowerShell\Modules\Microsoft.PowerToys.Configure .

For the machine-wide install scope, it's found in

%ProgramFiles%\WindowsPowerShell\Modules\Microsoft.PowerToys.Configure .

Usage
You can invoke the resource directly using the following Powershell syntax:

ps

Invoke-DscResource -Name PowerToysConfigure -Method Set -ModuleName

Microsoft.PowerToys.Configure -Property @{ Awake = @{ Enabled = $false; Mode =
"TIMED"; IntervalMinutes = "10" } }

However, creating a configuration.dsc.yaml file that contains the required settings in a

simpler format is more convenient. Here's an example:

YAML
 properties:
resources:
- resource: Microsoft.WinGet.DSC/WinGetPackage
id: installPowerToys
directives:
description: Install PowerToys
allowPrerelease: true
settings:
id: Microsoft.PowerToys
source: winget

- resource: Microsoft.PowerToys.Configure/PowerToysConfigure
dependsOn:
- installPowerToys
directives:
description: Configure PowerToys
settings:
ShortcutGuide:
Enabled: false
OverlayOpacity: 50
FancyZones:
Enabled: true
FancyzonesEditorHotkey: "Shift+Ctrl+Alt+F"
FileLocksmith:
Enabled: false
configurationVersion: 0.2.0

Use the following command to apply the configuration from the file:

ps

winget configure .\configuration.dsc.yaml

This command installs the latest version of PowerToys and uses the PowerToysConfigure
resource to apply settings for multiple PowerToys modules. More examples can be found in
the PowerToys repo .

Available Configuration Settings by Module

AlwaysOnTop

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

Hotkey KeyboardKeys Customize the shortcut to pin or unpin an ✅

Name Type Description Available

app window.

FrameEnabled Boolean Show a border around the pinned ✅

window.

FrameThickness Int Border thickness in pixels. ✅

FrameColor String Specify a color in a #FFFFFFFF format. ✅

FrameOpacity Int Border opacity in percentage. ✅

FrameAccentColor Boolean Use a custom FrameColor value. ✅

SoundEnabled Boolean Play a sound when pinning a window. ✅

DoNotActivateOnGameMode Boolean Disable activation shortcut when Game ✅

Mode is on.

ExcludedApps String '\r'-separated list of executable names to ✅

exclude from pinning on top.

RoundCornersEnabled Boolean Enable round corners. ✅

Awake

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

KeepDisplayOn Boolean This setting is only available when keeping the PC ✅

awake.

Mode AwakeMode Possible values: PASSIVE, INDEFINITE, TIMED, ✅

EXPIRABLE.

IntervalHours UInt32 When using TIMED mode, specifies the number of ✅

hours.

IntervalMinutes UInt32 When using TIMED mode, specifies the number of ✅

minutes.

ExpirationDateTime DateTimeOffset When using EXPIRABLE mode, specifies the date ✅

and time in a format parsable with
DateTimeOffset.TryParse .

ColorPicker
 ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActivationShortcut HotkeySettings Customize the shortcut to ✅

activate this module.

CopiedColorRepresentation String The default color representation ✅

to be used. Example :"HEX".

ActivationAction ColorPickerActivationAction Possible values: OpenEditor, ✅

OpenColorPickerAndThenEditor,
OpenOnlyColorPicker.

VisibleColorFormats — — ❌

ShowColorName Boolean This will show the name of the ✅

color when picking a color.

７ Note

Configuring custom color formats through DSC is not yet supported.

CropAndLock

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ReparentHotkey KeyboardKeys Shortcut to crop an application's window into a ✅

cropped window.

ThumbnailHotkey KeyboardKeys Shortcut to crop and create a thumbnail of another ✅

window.

EnvironmentVariables

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

Name Type Description Available

LaunchAdministrator Boolean Needs to be launched as administrator in order to make ✅

changes to the system environment variables.

FancyZones

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this ✅

utility.

FancyzonesShiftDrag Boolean Hold Shift key to activate ✅

zones while dragging a
window.

FancyzonesMouseSwitch Boolean Use a non-primary ✅

mouse button to toggle
zone activation.

FancyzonesMouseMiddleClickSpanningMultipleZones Boolean Use middle-click mouse ✅

button to toggle multiple
zones spanning.

FancyzonesOverrideSnapHotkeys Boolean This overrides the ✅

Windows Snap shortcut
(Win + arrow) to move
windows between zones.

FancyzonesMoveWindowsAcrossMonitors Boolean Move windows between ✅

zones across all monitors.

FancyzonesMoveWindowsBasedOnPosition Boolean Move windows based on ✅

relative position or zone
index.

FancyzonesOverlappingZonesAlgorithm Int When multiple zones ✅

overlap algorithm index.

FancyzonesDisplayOrWorkAreaChangeMoveWindows Boolean Keep windows in their ✅

zones when the screen
resolution or work area
changes.

FancyzonesZoneSetChangeMoveWindows Boolean During zone layout ✅

changes, windows
assigned to a zone will
match new size/positions.
Name Type Description Available

FancyzonesAppLastZoneMoveWindows Boolean Move newly created ✅

windows to their last
known zone.

FancyzonesOpenWindowOnActiveMonitor Boolean Move newly created ✅

windows to the curreynt
active monitor
(Experimental).

FancyzonesRestoreSize Boolean Restore the original size ✅

of windows when
unsnapping.

FancyzonesQuickLayoutSwitch Boolean Enable quick layout ✅

switch.

FancyzonesFlashZonesOnQuickSwitch Boolean Flash zones when ✅

switching layout.

UseCursorposEditorStartupscreen Boolean Open editor on the ✅

display where the mouse
point is.

FancyzonesShowOnAllMonitors Boolean Show zones on all ✅

monitors while dragging
a window.

FancyzonesSpanZonesAcrossMonitors Boolean Allow zones to span ✅

across monitors.

FancyzonesMakeDraggedWindowTransparent Boolean Make dragged window ✅

transparent.

FancyzonesAllowChildWindowSnap Boolean Allow child windows ✅

snapping.

FancyzonesDisableRoundCornersOnSnap Boolean Disable round corners ✅

when window is snapped.

FancyzonesZoneHighlightColor String If not using ✅

FancyzonesSystemTheme,
highlight color to use in
#FFFFFFFF format.

FancyzonesHighlightOpacity Int Zone opacity in ✅

percentage.

FancyzonesEditorHotkey KeyboardKeys Customize the shortcut ✅

to activate this module.

FancyzonesWindowSwitching Boolean Switch between windows ✅

in the current zone.
Name Type Description Available

FancyzonesNextTabHotkey KeyboardKeys Next window shortcut. ✅

FancyzonesPrevTabHotkey KeyboardKeys Previous window ✅

shortcut.

FancyzonesExcludedApps String '\r'-separated list of ✅

executable names to
exclude from snapping.

FancyzonesBorderColor String If not using ✅

FancyzonesSystemTheme,
border color to use in
#FFFFFFFF format.

FancyzonesInActiveColor String If not using ✅

FancyzonesSystemTheme,
inactive color to use in
#FFFFFFFF format.

FancyzonesNumberColor String If not using ✅

FancyzonesSystemTheme,
number color to use in
#FFFFFFFF format.

FancyzonesSystemTheme Boolean Use system theme for ✅

zone appearance.

FancyzonesShowZoneNumber Boolean Show zone number. ✅

７ Note

Configuring layouts through DSC is not yet supported.

FileLocksmith

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ExtendedContextMenuOnly Boolean Show File Locksmith in extended context menu ✅

only or in default context menu as well.

FindMyMouse
 ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActivationMethod Int Activation method index. ✅

ActivationShortcut HotkeySettings Custom activation shortcut when using ✅

Custom for ActivationMethod.

DoNotActivateOnGameMode Boolean Disable activation shortcut when Game ✅

Mode is on.

BackgroundColor String Background color in #FFFFFFFF format. ✅

SpotlightColor String Spotlight color in #FFFFFFFF format. ✅

OverlayOpacity Int Overlay opacity in percentage. ✅

SpotlightRadius Int Spotlight radius in px. ✅

AnimationDurationMs Int Animation duration in milliseconds. ✅

SpotlightInitialZoom Int Spotlight zoom factor at animation start. ✅

ExcludedApps String '\r'-separated list of executable names to ✅

prevent module activation.

ShakingMinimumDistance Int When using shake mouse ✅

ActivationMethod, the minimum
distance for mouse shaking activation,
for adjusting sensitivity.

ShakingIntervalMs Int When using shake mouse ✅

ActivationMethod, the span of time
during which we track mouse movement
to detect shaking, for adjusting
sensitivity.

ShakingFactor Int When using shake mouse ✅

ActivationMethod, Shake factor in
percentage.

Hosts

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

Name Type Description Available

LaunchAdministrator Boolean Needs to be opened as ✅

administrator in order to make
changes to the system
environment variables.

ShowStartupWarning Boolean Show a warning at startup. ✅

LoopbackDuplicates Boolean Consider loopback addresses as ✅

duplicates.

AdditionalLinesPosition HostsAdditionalLinesPosition Possible values: Top, Bottom. ✅

Encoding HostsEncoding Possible values: Utf8, Utf8Bom. ✅

ImageResizer

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ImageresizerSelectedSizeIndex Int Default size preset index. ✅

ImageresizerShrinkOnly Boolean Make pictures smaller but not larger. ✅

ImageresizerReplace Boolean Overwrite files. ✅

ImageresizerIgnoreOrientation Boolean Ignore the orientation of pictures. ✅

ImageresizerJpegQualityLevel Int JPEG quality level in percentage. ✅

ImageresizerPngInterlaceOption Int PNG interlacing option index. ✅

ImageresizerTiffCompressOption Int Tiff compression index. ✅

ImageresizerFileName String This format is used as the filename for ✅

resized images.

ImageresizerSizes — — ❌

ImageresizerKeepDateModified Boolean Remove metadata that doesn't affect ✅

rendering.

ImageresizerFallbackEncoder String Fallback encoder to use. ✅

ImageresizerCustomSize — — ❌

７ Note
 Configuring custom sizes through DSC is not yet supported.

KeyboardManager

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActiveConfiguration — — ❌

KeyboardConfigurations — — ❌

７ Note

Configuring remappings through DSC is not yet supported.

MeasureTool
Measure Tool is the internal name for Screen Ruler.

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActivationShortcut HotkeySettings Customize the shortcut to bring up the ✅

command bar.

ContinuousCapture Boolean Capture screen continuously during ✅

measuring.

DrawFeetOnCross Boolean Adds feet to the end of cross lines. ✅

PerColorChannelEdgeDetection Boolean Enable a different edge detection ✅

algorithm.

PixelTolerance Int Pixel Tolerance for edge detection. ✅

MeasureCrossColor String Line color in #FFFFFFFF format. ✅

DefaultMeasureStyle Int Default measure style index. ✅

MouseHighlighter
 ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActivationShortcut HotkeySettings Customize the shortcut to turn on or off this ✅

mode.

LeftButtonClickColor String Primary button highlight color in #FFFFFFFF ✅

format.

RightButtonClickColor String Secondary button highlight color in ✅

#FFFFFFFF format.

AlwaysColor String Always highlight color in #FFFFFFFF format. ✅

HighlightRadius Int Highlight radius in pixels. ✅

HighlightFadeDelayMs Int Fade delay in milliseconds. ✅

HighlightFadeDurationMs Int Fade duration in milliseconds. ✅

AutoActivate Boolean Automatically activate on utility startup. ✅

MouseJump

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActivationShortcut HotkeySettings Customize the shortcut to turn on or off ✅

this mode.

ThumbnailSize MouseJumpThumbnailSize Thumbnail size. ✅

MousePointerCrosshairs

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActivationShortcut HotkeySettings Customize the shortcut to show/hide ✅

the crosshairs.

CrosshairsColor String Crosshairs color in #FFFFFFFF . ✅

Name Type Description Available

CrosshairsOpacity Int Crosshairs opacity in percentage. ✅

CrosshairsRadius Int Crosshairs center radius in pixels. ✅

CrosshairsThickness Int Crosshairs thickness in pixels. ✅

CrosshairsBorderColor String Crosshairs border color in #FFFFFFFF ✅

format.

CrosshairsBorderSize Int Crosshairs border size in pixels. ✅

CrosshairsAutoHide Boolean Automatically hide crosshairs when ✅

the mouse pointer is hidden.

CrosshairsIsFixedLengthEnabled Boolean Fix crosshairs length. ✅

CrosshairsFixedLength Int Crosshairs fixed length in pixels. ✅

AutoActivate Boolean Automatically activate on utility ✅

startup.

MouseWithoutBorders

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this ✅

utility.

ShowOriginalUI Boolean Show the original Mouse ✅

Without Borders UI.

WrapMouse Boolean Move control back to the ✅

first machine when mouse
moves past the last one.

ShareClipboard Boolean If share clipboard stops ✅

working, Ctrl+Alt+Del
then Esc may solve the
problem.

TransferFile Boolean If a file (<100MB) is ✅

copied, it will be
transferred to the remote
machine clipboard.

HideMouseAtScreenEdge Boolean Hide mouse at the screen ✅

edge.
Name Type Description Available

DrawMouseCursor Boolean Mouse cursor may not be ✅

visible in Windows 10 and
later versions of Windows
when there is no physical
mouse attached.

ValidateRemoteMachineIP Boolean Reverse DNS lookup to ✅

validate machine IP
Address.

SameSubnetOnly Boolean Only connect to machines ✅

in the same intranet
NNN.NNN.. (only works
when both machines have
IPv4 enabled).

BlockScreenSaverOnOtherMachines Boolean Block screen saver on ✅

other machines.

MoveMouseRelatively Boolean Use this option when ✅

remote machine's monitor
settings are different, or
remote machine has
multiple monitors.

BlockMouseAtScreenCorners Boolean Block mouse at screen ✅

corners to avoid accident
machine-switch at screen
corners.

ShowClipboardAndNetworkStatusMessages Boolean Show clipboard and ✅

network status messages.

EasyMouse Int Easy Mouse mode index. ✅

HotKeySwitchMachine Int Shortcut to switch ✅

between machines index.

ToggleEasyMouseShortcut HotkeySettings Shortcut to toggle Easy ✅

Mouse.

LockMachineShortcut HotkeySettings Shortcut to lock all ✅

machines.

ReconnectShortcut HotkeySettings Shortcut to try ✅

reconnecting.

Switch2AllPCShortcut HotkeySettings Shortcut to switch to ✅

multiple machine mode.

Name2IP String IP address mapping. ✅

PastePlain

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActivationShortcut HotkeySettings Customize the shortcut to activate this module. ✅

Peek

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActivationShortcut HotkeySettings Customize the shortcut to activate this module. ✅

AlwaysRunNotElevated Boolean Always run not elevated, even when PowerToys ✅

is elevated.

CloseAfterLosingFocus Boolean Automatically close the Peek window after it ✅

loses focus.

PowerAccent
PowerAccent is the internal name for Quick Accent.

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this ✅

utility.

ActivationKey PowerAccentActivationKey Possible values: ✅

LeftRightArrow, Space, Both.

DoNotActivateOnGameMode Boolean Disable activation shortcut ✅

when Game Mode is on.

ToolbarPosition String Toolbar position index. ✅

InputTime Int Input time delay in ✅

milliseconds.

SelectedLang String A character set to use. ✅

 Name Type Description Available

ExcludedApps String '\r'-separated list of ✅

executable names to to
prevent module activation if
they're in a foreground.

ShowUnicodeDescription Boolean Show the Unicode code and ✅

name of the currently
selected character.

SortByUsageFrequency Boolean Sort characters by usage ✅

frequency.

StartSelectionFromTheLeft Boolean Start selection from the left. ✅

PowerLauncher
PowerLaucher is the internal name for PowerToys Run.

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

OpenPowerLauncher HotkeySettings Customize the shortcut to activate ✅

the module.

IgnoreHotkeysInFullscreen Boolean Ignore shortcuts in fullscreen mode. ✅

ClearInputOnLaunch Boolean Clear the previous query on open. ✅

TabSelectsContextButtons Boolean Tab through context buttons. ✅

Theme Theme Possible values: System, Light, Dark, ✅

HighContrastOne, HighContrastTwo,
HighContrastBlack,
HighContrastWhite.

TitleFontSize Int32 Text size in points. ✅

Position StartupPosition Possible values: Cursor, ✅

PrimaryMonitor, Focus.

UseCentralizedKeyboardHook Boolean Use centralized keyboard hook. ✅

SearchQueryResultsWithDelay Boolean Input Smoothing. ✅

SearchInputDelay Int32 Immediate plugins delay in ✅

milliseconds.
 Name Type Description Available

SearchInputDelayFast Int32 Background execution plugins delay ✅

in milliseconds.

SearchClickedItemWeight Int32 Selected item weight. ✅

SearchQueryTuningEnabled Boolean Results order tuning. ✅

SearchWaitForSlowResults Boolean Wait for slower plugin results before ✅

selecting top item in results.

MaximumNumberOfResults Int Number of results shown before ✅

having to scroll.

UsePinyin Boolean Use Pinyin. ✅

GenerateThumbnailsFromFiles Boolean Thumbnail generation for files is ✅

turned on.

Plugins explained in the Thumbnail generation for files is ✅

next subsection turned on.

PowerToys Run plugins

PowerToys Run plugins can be configured in the Plugins property. A sample can be found
in the PowerToys repository.

These are the available properties to configure each plugin:

ﾉ Expand table

Name Type Description

Name String Name of the plugin we want to configure

Disabled Boolean The plugin should be disabled

IsGlobal Boolean The results for this plugin are shown in the global results

ActionKeyword String Configure the action keyword of the plugin

WeightBoost Int The weight modifier to help in ordering the results for this plugin

７ Note

Configuring additional properties of plugins through DSC is not yet supported.

PowerOcr
PowerOcr is the internal name for Text Extractor.

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

ActivationShortcut HotkeySettings Customize the shortcut to activate this module. ✅

PreferredLanguage String Should match the full name of one of the ✅

languages installed in the system. Example:
"English (United States)".

PowerPreview

ﾉ Expand table

Name Type Description Available

EnableSvgPreview Boolean Scalable Vector Graphics Preview Handler ✅

Enabled state.

SvgBackgroundColorMode Int Color mode index. ✅

SvgBackgroundSolidColor String When using Solid color ✅

SvgBackgroundColorMode, specifies the
color in #FFFFFFFF format.

SvgBackgroundCheckeredShade Int When using Checkered pattern ✅

SvgBackgroundColorMode, specifies the
shade index.

EnableSvgThumbnail Boolean Scalable Vector Graphics Thumbnail ✅

Generator Enabled state.

EnableMdPreview Boolean Markdown Preview Handler Enabled state. ✅

EnableMonacoPreview Boolean Source code files Preview Handler Enabled ✅

state.

EnableMonacoPreviewWordWrap Boolean Wrap text. ✅

MonacoPreviewTryFormat Boolean Try to format the source for preview. ✅

MonacoPreviewMaxFileSize Int Maximum file size to preview in KB. ✅

EnablePdfPreview Boolean Portable Document Format Preview Handler ✅

Enabled state.

EnablePdfThumbnail Boolean Portable Document Format Thumbnail ✅

Generator Enabled state.
Name Type Description Available

EnableGcodePreview Boolean Geometric Code Preview Handler Enabled ✅

state.

EnableGcodeThumbnail Boolean Geometric Code Thumbnail Generator ✅

Enabled state.

EnableStlThumbnail Boolean Stereolithography Thumbnail Generator ✅

Enabled state.

StlThumbnailColor String Thumbnail color in #FFFFFFFF format . ✅

EnableQoiPreview Boolean Quite OK Image Preview Handler Enabled ✅

state.

EnableQoiThumbnail Boolean Quite OK Image Thumbnail Generator ✅

Enabled state.

PowerRename

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

MRUEnabled Boolean Enable auto-complete for the search & replace ✅

fields.

MaxMRUSize Int Maximum number of recently used items to ✅

remember.

ExtendedContextMenuOnly Boolean Show PowerRename in extended context menu ✅

only or in default context menu as well.

UseBoostLib Boolean Use Boost Library. ✅

RegistryPreview

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

DefaultRegApp Boolean Make Registry Preview default app for opening .reg files. ✅

ShortcutGuide
 ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

OpenShortcutGuide HotkeySettings Customize the shortcut to ✅

activate this module.

OverlayOpacity Int Background opacity in ✅

percentage.

UseLegacyPressWinKeyBehavior Boolean If ShortcutGuide should be ✅

activated by pressing the
Windows key.

PressTimeForGlobalWindowsShortcuts Int Press duration before showing ✅

global Windows shortcuts in
milliseconds.

PressTimeForTaskbarIconShortcuts Int Press duration before showing ✅

taskbar icon shortcuts in
milliseconds.

Theme String Theme index. ✅

DisabledApps String Turns off Shortcut Guide when ✅

these applications have focus.

VideoConference

ﾉ Expand table

Name Type Description Available

Enabled Boolean The enabled state for this utility. ✅

MuteCameraAndMicrophoneHotkey KeyboardKeys Shortcut for muting the camera ✅

and microphone.

MuteMicrophoneHotkey KeyboardKeys Shortcut for muting the ✅

microphone.

PushToTalkMicrophoneHotkey KeyboardKeys Shortcut for push to talk. ✅

PushToReverseEnabled Boolean If enabled, allows both push to talk ✅

and push to mute, depending on
microphone state.

MuteCameraHotkey KeyboardKeys Shortcut for muting the camera. ✅

SelectedCamera String Device name. ✅

Name Type Description Available

SelectedMicrophone String Device name or [All]. ✅

ToolbarPosition String Toolbar position option: "Top ✅

center", "Bottom center", "Top
right corner", "Top left corner",
"Bottom right corner", "Bottom left
corner".

ToolbarMonitor String Toolbar monitor option: "Main ✅

monitor", "All monitors".

CameraOverlayImagePath String Path to the image used for the ✅

camera overlay.

ToolbarHide String When to hide the toolbar: "Never", ✅

"When both camera and
microphone are unmuted", "When
both camera and microphone are
muted", "After timeout".

StartupAction String Startup action: "Nothing", ✅

"Unmute", "Mute".

GeneralSettings

ﾉ Expand table

Name Type Description Available

Startup Boolean PowerToys is automatically enabled at ✅

startup.

EnableWarningsElevatedApps Boolean Show a warning for functionality issues ✅

when running alongside elevated
applications.

Theme String What theme to use for the Settings ✅

application: "system", "dark", "light".

ShowNewUpdatesToastNotification Boolean Show a toast notification when a new ✅

PowerToys update is available.

AutoDownloadUpdates Boolean If new updates of PowerToys should be ✅

automatically downloaded in the
background.

ShowWhatsNewAfterUpdates Boolean After updating PowerToys, open the ✅

"What's new" screen.
 Name Type Description Available

EnableExperimentation Boolean Opt-in into experimental features. ✅

Contributing
Refer to the relevant devdocs section in the developer documentation to start working on
the DSC module.

６ Collaborate with us on
Windows developer feedback
GitHub
Windows developer is an open source
The source for this content can project. Select a link to provide
be found on GitHub, where you feedback:
can also create and review issues
and pull requests. For more  Open a documentation issue
information, see our contributor
guide.  Provide product feedback
Group Policies
Article • 01/30/2024

Since version 0.64, PowerToys is released on GitHub with Administrative Templates that
allows you to configure PowerToys using Group Policies.

How to install

Download
You can find the latest administrative templates (ADMX files) in the assets section of our
newest PowerToys release on GitHub . The file is named GroupPolicyObjectsFiles-
<Version>.zip .

Add the administrative template to an individual

computer
1. Copy the PowerToys.admx file to your Policy Definition template folder. (Example:
C:\Windows\PolicyDefinitions)
2. Copy the PowerToys.adml file to the matching language folder in your Policy
Definition folder. (Example: C:\Windows\PolicyDefinitions\en-US)

Add the administrative template to Active Directory

1. On a domain controller or workstation with RSAT, go to the PolicyDefinition folder
(also known as the Central Store) on any domain controller for your domain. For
older versions of Windows Server, you might need to create the PolicyDefinition
folder. For more information, see How to create and manage the Central Store for
Group Policy Administrative Templates in Windows .
2. Copy the PowerToys.admx file to the PolicyDefinition folder. (Example:
%systemroot%\sysvol\domain\policies\PolicyDefinitions)
3. Copy the PowerToys.adml file to the matching language folder in the
PolicyDefinition folder. Create the folder if it doesn't already exist. (Example:
%systemroot%\sysvol\domain\policies\PolicyDefinitions\EN-US)
4. If your domain has more than one domain controller, the new ADMX files will be
replicated to them at the next domain replication interval.

Import the administrative template in Intune

You can find all instructions on how to import the administrative templates in Intune on
this page.

Scope
You will find the policies under "Administrative Templates/Microsoft PowerToys" in both
the Computer Configuration and User Configuration folders. If both settings are
configured, the setting in Computer Configuration takes precedence over the setting in
User Configuration.

Policies

Configure global utility enabled state

Supported on PowerToys 0.75.0 or later.

This policy configures the enabled state for all PowerToys utilities.

If you enable this setting, all utilities will be always enabled and the user won't be
able to disable it.
If you disable this setting, all utilities will be always disabled and the user won't be
able to enable it.
If you don't configure this setting, users are able to enable or disable the utilities.

The individual enabled state policies for the utilities will override this policy.

Group Policy (ADMX) information

GP unique name: ConfigureGlobalUtilityEnabledState
GP name: Configure global utility enabled state
GP path: Administrative Templates/Microsoft PowerToys
GP scope: Computer and user
ADMX file name: PowerToys.admx

Registry information

Path: Software\Policies\PowerToys
Name: ConfigureGlobalUtilityEnabledState
Type: DWORD
Example value: 0x00000000
Intune information
OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys/ConfigureGlobalU
tilityEnabledState

Example value: <disabled/>

Configure enabled state for individual utilities

Supported on PowerToys 0.64.0 or later, depending on the utility.

For each utility shipped with PowerToys, there's a "Configure enabled state" policy,
which forces an enabled state for the utility.

If you enable this setting, the utility will be always enabled and the user won't be
able to disable them.
If you disable this setting, the utility will be always disabled and the user won't be
able to enable them.
If you don't configure this setting, users are able to enable or disable the utility.

These policies have a higher priority than, and will override, the policy "Configure global
utility enabled state".

７ Note

PDF file preview: There have been reports of incompatibility between the PDF
Preview Handler and Outlook.

Table of utility Policies

ﾉ Expand table

Utility ADMX GP name ADMX GP unique name /

Registry value name /
Intune PolicyID

Always On Top Always On Top: ConfigureEnabledUtilityAlwaysOnTop

Configure enabled
state

Awake Awake: Configure ConfigureEnabledUtilityAwake

enabled state
Utility ADMX GP name ADMX GP unique name /
Registry value name /
Intune PolicyID

Color Picker Color Picker: Configure ConfigureEnabledUtilityColorPicker

enabled state

Command Not Command Not Found: ConfigureEnabledUtilityCmdNotFound

Found Configure enabled
state

Crop And Lock Crop And Lock: ConfigureEnabledUtilityCropAndLock

Configure enabled
state

Environment Environment Variables: ConfigureEnabledUtilityEnvironmentVariables

Variables Configure enabled
state

FancyZones FancyZones: Configure ConfigureEnabledUtilityFancyZones

enabled state

File Locksmith File Locksmith: ConfigureEnabledUtilityFileLocksmith

Configure enabled
state

Gcode file Gcode file preview: ConfigureEnabledUtilityFileExplorerGcodePreview

preview Configure enabled
state

Markdown file Markdown file ConfigureEnabledUtilityFileExplorerMarkdownPreview

preview preview: Configure
enabled state

PDF file preview PDF file preview: ConfigureEnabledUtilityFileExplorerPDFPreview

Configure enabled
state

QOI file preview QOI file preview: ConfigureEnabledUtilityFileExplorerQOIPreview

Configure enabled
state

Source code file Source code file ConfigureEnabledUtilityFileExplorerMonacoPreview

preview preview: Configure
enabled state

SVG file preview SVG file preview: ConfigureEnabledUtilityFileExplorerSVGPreview

Configure enabled
state
Utility ADMX GP name ADMX GP unique name /
Registry value name /
Intune PolicyID

Gcode file Gcode file thumbnail: ConfigureEnabledUtilityFileExplorerGcodeThumbnails

thumbnail Configure enabled
state

PDF file PDF file thumbnail: ConfigureEnabledUtilityFileExplorerPDFThumbnails

thumbnail Configure enabled
state

QOI file QOI file thumbnail: ConfigureEnabledUtilityFileExplorerQOIThumbnails

thumbnail Configure enabled
state

STL file STL file thumbnail: ConfigureEnabledUtilityFileExplorerSTLThumbnails

thumbnail Configure enabled
state

SVG file SVG file thumbnail: ConfigureEnabledUtilityFileExplorerSVGThumbnails

thumbnail Configure enabled
state

Hosts file editor Hosts file editor: ConfigureEnabledUtilityHostsFileEditor

Configure enabled
state

Image Resizer Image Resizer: ConfigureEnabledUtilityImageResizer

Configure enabled
state

Keyboard Keyboard Manager: ConfigureEnabledUtilityKeyboardManager

Manager Configure enabled
state

Find My Mouse Find My Mouse: ConfigureEnabledUtilityFindMyMouse

Configure enabled
state

Mouse Mouse Highlighter: ConfigureEnabledUtilityMouseHighlighter

Highlighter Configure enabled
state

Mouse Jump Mouse Jump: ConfigureEnabledUtilityMouseJump

Configure enabled
state

Mouse Pointer Mouse Pointer ConfigureEnabledUtilityMousePointerCrosshairs

Crosshairs Crosshairs: Configure
enabled state
Utility ADMX GP name ADMX GP unique name /
Registry value name /
Intune PolicyID

Mouse Without Mouse Without ConfigureEnabledUtilityMouseWithoutBorders

Borders Borders: Configure
enabled state

Paste as Plain Paste as Plain Text: ConfigureEnabledUtilityPastePlain

Text Configure enabled
state

Peek Peek: Configure ConfigureEnabledUtilityPeek

enabled state

Power Rename Power Rename: ConfigureEnabledUtilityPowerRename

Configure enabled
state

PowerToys Run PowerToys Run: ConfigureEnabledUtilityPowerLauncher

Configure enabled
state

Quick Accent Quick Accent: ConfigureEnabledUtilityQuickAccent

Configure enabled
state

Registry Registry Preview: ConfigureEnabledUtilityRegistryPreview

Preview Configure enabled
state

Screen Ruler Screen Ruler: ConfigureEnabledUtilityScreenRuler

Configure enabled
state

Shortcut Guide Shortcut Guide: ConfigureEnabledUtilityShortcutGuide

Configure enabled
state

Text Extractor Text Extractor: ConfigureEnabledUtilityTextExtractor

Configure enabled
state

Video Video Conference ConfigureEnabledUtilityVideoConferenceMute

Conference Mute: Configure
Mute enabled state

Group Policy (ADMX) information

GP unique name: See the table above.
 GP name: See the table above.
GP path: Administrative Templates/Microsoft PowerToys
GP scope: Computer and user
ADMX file name: PowerToys.admx

Registry information

Path: Software\Policies\PowerToys
Name: See the table above.
Type: DWORD
Example value: 0x00000000

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys/<PolicyID>

７ Note

Please see the table above for the PolicyID value.

Example value: <disabled/>

Allow experimentation
Supported on PowerToys 0.68.0 or later.

This policy configures whether PowerToys experimentation is allowed. With

experimentation allowed the user sees the new features being experimented if it gets
selected as part of the test group. Experimentation will only happen on Windows Insider
builds.

If this setting is enabled or not configured, the user can control experimentation in
the PowerToys settings menu.
If this setting is disabled, experimentation is not allowed.

Group Policy (ADMX) information

GP unique name: AllowExperimentation

GP name: Allow experimentation
GP path: Administrative Templates/Microsoft PowerToys
 GP scope: Computer and user
ADMX file name: PowerToys.admx

Registry information

Path: Software\Policies\PowerToys
Name: AllowExperimentation
Type: DWORD
Example value: 0x00000000

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys/AllowExperimenta
tion

Example value: <disabled/>

Installer and Updates

Disable per-user installation

Supported on PowerToys 0.68.0 or later.

This policy configures whether PowerToys per-user installation is allowed or not.

If enabled, per-user installation is not allowed.

If disabled or not configured, per-user installation is allowed.

７ Note

You can set this policy only as Computer policy.

Group Policy (ADMX) information

GP unique name: DisablePerUserInstallation

GP name: Disable per-user installation
GP path: Administrative Templates/Microsoft PowerToys/Installer and Updates
GP scope: Computer only
ADMX file name: PowerToys.admx
Registry information

Path: HKLM\Software\Policies\PowerToys
Name: DisablePerUserInstallation
Type: DWORD
Example value: 0x00000001

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~InstallerUpdates
/DisablePerUserInstallation

Example value: <enabled/>

Disable automatic downloads

Supported on PowerToys 0.68.0 or later.

This policy configures whether the automatic download and installation of available
updates is disabled or not. Updates are never downloaded on metered connections.

If enabled, automatic download and installation is disabled.

If disabled or not configured, the user can control this in the settings.

Group Policy (ADMX) information

GP unique name: DisableAutomaticUpdateDownload

GP name: Disable automatic downloads
GP path: Administrative Templates/Microsoft PowerToys/Installer and Updates
GP scope: Computer and user
ADMX file name: PowerToys.admx

Registry information

Path: Software\Policies\PowerToys
Name: DisableAutomaticUpdateDownload
Type: DWORD
Example value: 0x00000001

Intune information
 OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~InstallerUpdates

/DisableAutomaticUpdateDownload

Example value: <enabled/>

Suspend Action Center notification for new updates

Supported on PowerToys 0.68.0 or later.

This policy configures whether the action center notification for new updates is
suspended for 2 minor releases. (Example: if the installed version is v0.60.0, then the
next notification is shown for the v0.63.* release.)

If enabled, the notification is suspended.

If disabled or not configured, the notification is shown.

７ Note

The notification about new major versions is always displayed.

Group Policy (ADMX) information

GP unique name: SuspendNewUpdateToast

GP name: Suspend Action Center notification for new updates
GP path: Administrative Templates/Microsoft PowerToys/Installer and Updates
GP scope: Computer and user
ADMX file name: PowerToys.admx

Registry information

Path: Software\Policies\PowerToys
Name: SuspendNewUpdateToast
Type: DWORD
Example value: 0x00000001

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~InstallerUpdates
/SuspendNewUpdateToast
 Example value: <enabled/>

Disable Action Center notification for new updates

Supported on PowerToys 0.78.0 or later.

This policy configures whether the action center notification for new updates is shown
or not.

If enabled, the notification is disabled.

If disabled or not configured, the user can control if the notification is shown or
not.

Group Policy (ADMX) information

GP unique name: DisableNewUpdateToast

GP name: Disable Action Center notification for new updates
GP path: Administrative Templates/Microsoft PowerToys/Installer and Updates
GP scope: Computer and user
ADMX file name: PowerToys.admx

Registry information

Path: Software\Policies\PowerToys
Name: DisableNewUpdateToast
Type: DWORD
Example value: 0x00000001

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~InstallerUpdates
/DisableNewUpdateToast

Example value: <enabled/>

Do not show the release notes after updates

Supported on PowerToys 0.78.0 or later.

This policy allows you to configure if the window with the release notes is shown after
updates.
 If enabled, the window with the release notes is not shown automatically.
If disabled or not configured, the user can control this in the settings of PowerToys.

Group Policy (ADMX) information

GP unique name: DoNotShowWhatsNewAfterUpdates

GP name: Disable Action Center notification for new updates
GP path: Administrative Templates/Microsoft PowerToys/Installer and Updates
GP scope: Computer and user
ADMX file name: PowerToys.admx

Registry information

Path: Software\Policies\PowerToys
Name: DoNotShowWhatsNewAfterUpdates
Type: DWORD
Example value: 0x00000001

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~InstallerUpdates

/DoNotShowWhatsNewAfterUpdates

Example value: <enabled/>

PowerToys Run

Configure enabled state for all plugins

Supported on PowerToys 0.75.0 or later.

This policy configures the enabled state for all PowerToys Run plugins. All plugins will
have the same state.

If you enable this setting, the plugins will be always enabled and the user won't be
able to disable it.
If you disable this setting, the plugins will be always disabled and the user won't be
able to enable it.
If you don't configure this setting, users are able to enable or disable the plugins.
You can override this policy for individual plugins using the policy "Configure enabled
state for individual plugins".

７ Note

Changes require a restart of PowerToys Run.

Group Policy (ADMX) information

GP unique name: PowerToysRunAllPluginsEnabledState

GP name: Configure enabled state for all plugins
GP path: Administrative Templates/Microsoft PowerToys/PowerToys Run
GP scope: Computer and user
ADMX file name: PowerToys.admx

Registry information

Path: Software\Policies\PowerToys
Name: PowerToysRunAllPluginsEnabledState
Type: DWORD
Example value: 0x00000000

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~PowerToysRun/Pow

erToysRunAllPluginsEnabledState

Example value: <disabled/>

Configure enabled state for individual plugins

Supported on PowerToys 0.75.0 or later.

With this policy you can configure an individual enabled state for each PowerToys Run
plugin that you add to the list.

If you enable this setting, you can define the list of plugins and their enabled states:

The value name (first column) is the plugin ID. You will find it in the plugin.json
file which is located in the plugin folder.
 The value (second column) is a numeric value: 0 for disabled, 1 for enabled and 2
for user takes control.
Example to disable the Program plugin: 791FC278BA414111B8D1886DFE447410 | 0

If you disable or don't configure this policy, either the user or the policy "Configure
enabled state for all plugins" takes control over the enabled state of the plugins.

You can set the enabled state for all plugins not controlled by this policy using the
policy "Configure enabled state for all plugins".

７ Note

Changes require a restart of PowerToys Run.

Group Policy (ADMX) information

GP unique name: PowerToysRunIndividualPluginEnabledState

GP name: Configure enabled state for individual plugins
GP path: Administrative Templates/Microsoft PowerToys/PowerToys Run
GP scope: Computer and user
ADMX file name: PowerToys.admx

Registry information

Path: Software\Policies\PowerToys\PowerLauncherIndividualPluginEnabledList

Name: The plugin ID from the plugin.json file.

Type: STRING

Example values:

Software\Policies\PowerToys\0778F0C264114FEC8A3DF59447CF0A74 = 2 (=>
User can enable/disable the OneNote plugin.)
Software\Policies\PowerToys\791FC278BA414111B8D1886DFE447410 = 0 (=>
Program plugin force disabled.)
Software\Policies\PowerToys\CEA0FDFC6D3B4085823D60DC76F28855 = 1 (=>
Calculator plugin force enabled.)

Intune information
 OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~PowerToysRun/Pow

erToysRunIndividualPluginEnabledState

Example value:

<enabled/>
<data id="PowerToysRunIndividualPluginEnabledList"
value="0778F0C264114FEC8A3DF59447CF0A74&#xF000;2&#xF000;791FC278BA41411
1B8D1886DFE447410&#xF000;0&#xF000;CEA0FDFC6D3B4085823D60DC76F28855&#xF0
00;1"/>

７ Note

Syntax for the value property from the data element: <PluginID>&#xF000;
<Number>&#xF000;<PluginID>&#xF000;<Number>

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Always On Top utility
Article • 12/20/2023

A system-wide Windows utility to pin windows above other windows.

Pin a window
When you activate Always On Top (default: ⊞ Win + Ctrl + T ), the utility pins the active
window above all other windows. The pinned window stays on top, even when you
select other windows.

Settings
Always On Top has the following settings:

ﾉ Expand table

Setting Description

Activation The customizable keyboard command to turn on or off the always-on-top

shortcut property for that window.

Do not activate Prevents the feature from being activated when actively playing a game on
when Game the system.
Mode is on

Show a border When On, this option shows a colored border around the pinned window.
around the
pinned window

Color mode Choose either Windows default or Custom color for the highlight border.
Setting Description

Color The custom color of the highlight border. Color is only available when Color
mode is set to Custom color.

Opacity (%) The opacity of the highlight border.

Thickness (px) The thickness of the highlight border in pixels.

Enable round When selected, the highlight border around the pinned window will have
corners rounded corners.

Play a sound When selected, this option plays a sound when you activate or deactivate
when pinning a Always On Top.
window

Excluded apps Prevents you from pinning an application using Always On Top. Add an
application's name to stop it from being pinned. The list will also exclude
partial matches. For example, Notepad will prevent both Notepad.exe and
Notepad++.exe from being pinned. To only prevent a specific application, add
Notepad.exe to the excluded list.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
PowerToys Awake utility
Article • 08/09/2023

PowerToys Awake is a tool for Windows designed to keep a computer awake without
having to manage its power & sleep settings . This can be helpful when running time-
consuming tasks, ensuring that the computer does not go to sleep or turn off its
screens.

Getting started
You can use PowerToys Awake directly from PowerToys Settings or as a standalone
executable. When it's running from PowerToys, it can be managed from PowerToys
Settings or the system tray.

７ Note

PowerToys Awake does not modify any of the Windows power plan settings, and
does not depend on a custom power plan configuration. Instead, it spawns
background threads that tell Windows that they require a specific state of the
machine.

Settings
In the PowerToys Settings, start PowerToys Awake by toggling Enable Awake on. Once
enabled, the application will manage the awakeness state of the computer.
You can choose the following Awake states:

ﾉ Expand table

Setting Description

Keep using the selected The computer awakeness state is unaffected. The application is waiting
power plan for user input.

Keep awake indefinitely The computer stays awake indefinitely, until you explicitly put the
machine to sleep or close/disable the application.

Keep awake for a time Keep machine awake for a defined limited time. After the defined time,
interval Awake returns to the previous state.

Keep awake until Keep machine awake until a defined time.

expiration.

７ Note

Changing the hours or minutes while the computer is kept awake temporarily will
reset the timer.

Keep screen on
While PowerToys Awake can keep the computer awake indefinitely or temporarily, in its
default state the displays connected to the machine will turn off. If you need the displays
to be available, use the Keep screen on switch, which will keep displays active.

This feature only works if Awake is running in one of the three Keep awake states. It
does not survive a computer restart.

System tray
To manage the execution of the tool from the system tray, right-click on the PowerToys
Awake icon.

Command Line Interface (CLI)

PowerToys Awake can also be executed as a standalone application, directly from the
PowerToys folder. The following command line arguments can be used when running
PowerToys.Awake.exe from the terminal or via a .lnk shortcut file:

ﾉ Expand table

Argument Description

--use-pt- Use the PowerToys configuration file to manage the settings. This assumes that
config there is a settings.json file for Awake, generated by PowerToys, that contains all
required runtime information. This includes the Behavior Mode (indefinite or
timed), whether screens should be kept on, and what the values for hours and
minutes are for a temporary keep-awake.
When this argument is used, all other arguments are ignored. Awake will look for
changes in the settings.json file to update its state.

--display- Keep displays on or off while the machine is kept awake. Expected values are true
on or false .
 Argument Description

--time- Duration, in seconds, during which Awake keeps the computer awake. Can be used
limit in combination with --display-on .

--expire- Expiration date and/or time when Awake will turn off and resume the standard
at power state. Can be used in combination with --display-on .

--pid Attaches the execution of Awake to a Process ID (PID). When the process with a
given PID terminates, Awake terminates as well.

７ Note

The settings.json configuration file is located at

%HomePath%\AppData\Local\Microsoft\PowerToys\Awake\ . "Keep awake temporarily"

options can be adjusted by modifying the "customTrayTimes" value, an array

consisting of name and duration (in seconds) to stay awake. For example:
"customTrayTimes":{"8 hours":28800} .

In absence of command-line arguments, PowerToys Awake will keep the computer

awake indefinitely.

When setting the value for the --time-limit parameter, both of these formats will be
accepted:

PowerToys.Awake.exe --time-limit 36000

PowerToys.Awake.exe --time-limit=36000

When setting the value for the --expire-at parameter, these formats will be accepted
based on DateTime.Parse

PowerToys.Awake.exe --expire-at=17:00:00 will expire at 5PM of the current day

PowerToys.Awake.exe --expire-at="4/13/2023 17:00:00" will expire at 5PM on April

13 2023

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Color Picker utility
Article • 04/12/2024

A system-wide color picking utility for Windows to pick colors from any screen and copy
it in a configurable format to the clipboard.

Getting started

Enabling Color Picker

Enable Color Picker in PowerToys Settings.

Activating Color Picker

Choose what happens when you activate Color Picker (default: Win + Shift + C ) by
changing Activation Behavior:

Open editor opens an editor that lets you choose a color from the colors history,
fine-tune a selected color, or pick a new color
 Pick a color and open editor activates Color Picker, then opens an editor and
copies the selected color to the clipboard after you've picked a color
Only pick a color activates Color Picker and copies the selected color to the
clipboard

Picking colors
After activating Color Picker, select a color on your screen to pick that color. If you want
to see the area under your cursor in more detail, scroll up to zoom in.

Color Picker copies the selected color to the clipboard in the Default color format
you've chosen in Color Picker's settings (default: HEX).

 Tip

To select the color of the non-hover state of a element:

1. Move the mouse pointer close, but not over the element.
2. Zoom in by scrolling the mouse wheel up. Image will be frozen.
3. In the enlarged area, you can pick the color of the element.

Using the Color Picker editor

The Color Picker editor stores a history of up to 20 picked colors and lets you copy them
to the clipboard. Choose which color formats are visible in the editor in Color formats in
PowerToys Settings.

The colored bar at the top of the Color Picker editor lets you:

fine tune your chosen color

pick a similar color

To fine tune your chosen color, select the central color in the color bar. The fine-tuning
control lets you change the color's HSV, RGB, and HEX values. Select adds the new color
to the colors history.

To choose a similar color, select one of the segments on the top and bottom edges of
the color bar. Selecting one of these similar colors adds it to the history.

To remove a color from the history, right-click a color and select Remove.

To export the colors history, right-click a color and select Export. You can group the
values by colors or formats.
Settings
Color Picker has the following settings:

ﾉ Expand table

Setting Description

Activation The shortcut that activates Color Picker.

shortcut

Activation Sets what happens when you activate Color Picker. Read more about this setting
behavior in Activating Color Picker.

Default color The color format that Color Picker copies to the clipboard.
format

Show color Shows a high-level representation of the color. For example, 'Light Green',
name 'Green', or 'Dark Green'.

Color formats Enable and add different color formats, and change the order of color formats in
the Color Picker editor. Read more about color formats in Managing color
formats.
Managing color formats
You can add, edit, delete, disable, and change the order of color formats in Color
formats.

To change the order that color formats appear in the Color Picker editor, select the more
button (•••) next to a color format and select Move up or Move down.
To disable a color format, turn off the toggle next to that color format. Color Picker
doesn't show disabled color formats in the editor.

To delete a color format, select the more button (•••) next to a color format and select
Delete.

To add a new color format, select Add custom color format. Enter the color format's
Name and Format. The syntax for color formats is described in the dialog.

To edit a color format, select it from the list. Edit the color format's Name and Format in
the Edit custom color format dialog. The syntax for color formats is described in the
dialog.

Define color formats with these parameters:

ﾉ Expand table

Parameter Meaning

%Re red

%Gr green

%Bl blue

%Al alpha

%Cy cyan

%Ma magenta

%Ye yellow

%Bk Black key

%Hu hue

%Si saturation (HSI)

%Sl saturation (HSL)

%Sb saturation (HSB)

%Br brightness

%In intensity

%Hn hue (natural)

%Ll lightness (natural)

 Parameter Meaning

%Lc lightness (CIE)

%Va value

%Wh whiteness

%Bn blackness

%Ca chromaticity A

%Cb chromaticity B

%Xv X value

%Yv Y value

%Zv Z value

%Dv decimal value

%Na color name

Format the red, green, blue and alpha values to the following formats:

ﾉ Expand table

Formatter Meaning

b byte value (default)

h hex lowercase one digit

H hex uppercase one digit

x hex lowercase two digits

X hex uppercase two digits

f float with leading zero

F float without leading zero

For example %ReX means the red value in hex uppercase two digits format.

Color formats can contain any words or characters that you prefer. For example, the
default color format, which shows up on color format creation is: _'new Color (R = %Re,
G = %Gr, B = %Bl)'_ .
Limitations
Color Picker can't display on top of the Start menu or Action Center, but you can
still pick a color.
If you started the currently focused application with an administrator elevation
(Run as administrator), the Color Picker activation shortcut won't work, unless you
also started PowerToys with administrator elevation.
Wide Color Gamut (WCG) and High Dynamic Range (HDR) color formats are
currently not supported.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Command Not Found utility
Article • 04/12/2024

A PowerShell 7 module that detects command-line errors and suggests a relevant

WinGet package to install, if available.

） Important

There are some incompatibilities between Command Not Found and some
PowerShell configurations. Read more about them in issue 30818 on GitHub.

Requirements
PowerShell 7
PowerShell Microsoft.WinGet.Client module

Install the module

To install the Command Not Found module, go to the Command Not Found page in
PowerToys settings and select Install. Once the installation has completed, PowerShell 7
experimental features needed for the module to function will be enabled:

PSFeedbackProvider
PSCommandNotFoundSuggestion

After that, the PowerShell profile file will be appended with following block of
PowerShell commands:
 psh

#34de4b3d-13a8-4540-b76d-b9e8d3851756 PowerToys CommandNotFound module

Import-Module "<powertoys install dir>/WinGetCommandNotFound.psd1"
#34de4b3d-13a8-4540-b76d-b9e8d3851756

Note: The profile file will be created if needed. Restart PowerShell session to use the
module.

Uninstall the module

To uninstall the Command Not Found module, go to the Command Not Found page in
PowerToys settings and select Uninstall. Once the uninstallation has completed, the
block of commands previously added will be removed from the PowerShell profile file.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Crop And Lock
Article • 04/12/2024

PowerToys Crop And Lock allows you to crop a current application into a smaller
window or just create a thumbnail. Focus the target window and press the shortcut to
start cropping.

Getting started

How to use
To start using Crop And Lock, enable it in PowerToys Settings.

Once enabled, focus a Window and press the "Thumbnail" shortcut (default: ⊞ Win +
Ctrl + Shift + T ) or the "Reparent" shortcut (default: ⊞ Win + Ctrl + Shift + R ) to
select an area of the window to crop.

 Tip

Use Esc to cancel the crop selection.

After you've selected the area of the window, a new window will appear and behave
according to the selected crop mode.

Select the Close button of the cropped window to close it and restore the original
window.

Crop modes
Thumbnail
Creates a window that shows the selected area of the original window. Any changes to
the original window's selected area will be reflected on the thumbnail, but the original
application can't be controlled through the thumbnail. This mode has the best
compatibility.

Reparent
Creates a window that replaces the original window, showing only the selected area. The
application will now be controlled through the cropped window. Closing the cropped
window will restore the original window. Not every window will react well to being
contained in another application so this mode has many compatibility issues. It's
advisable to use the "Thumbnail" mode instead if you find that a windows isn't reacting
well to being cropped with the "Reparent" mode.

Known issues
Cropping maximized or full-screen windows in "Reparent" mode might not work.
It's recommended to resize the window to fill the screen corners instead.
Some UWP apps won't react well to being cropped in "Reparent" mode. Windows
Calculator is a notable example of this.
Applications that use sub-windows or tabs can react poorly to being cropped in
"Reparent" mode. Notepad and OneNote are notable examples of applications
that react poorly.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Environment Variables
Article • 04/12/2024

Environment Variables offers an easy and convenient way to manage environment

variables. It allows you to create profiles for managing a set of variables together. Profile
variables have precedence over User and System variables. Applying the profile adds
variables to User environment variables in the background. When a profile is applied, if
there is an existing User variable with the same name, a backup variable is created in
User variables which will be reverted to the original value on profile un-apply. Applied
variables list shows the current state of the environment, respecting the order of
evaluation of environment variables (Profile > User > System). Evaluated Path variable
value is shown at the top of the list.

Edit/Remove variable
To edit or remove a variable (profile, User or System), select the more button (•••) on the
desired variable:
Add profile
To add a new profile:

Select New profile

Enter profile name
Set Enabled toggle to On to apply the profile right after creation
Select Add variable to add variables to profile (either new variable or existing
User/System variables)
Select Save

To edit or remove a profile, select the more button (•••) on the desired profile.

Apply profile
To apply a profile, set the profile toggle to On. Only one profile can be applied at a time.
The Applied variables list will show applied profile variables at the top (below Path
variable):

Settings
From the settings, the following options can be configured:

ﾉ Expand table

Setting Description

Open as Allow management of System variables. If off, only profile and User variables
administrator can be modified. Environment Variables is opened as administrator by default.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
FancyZones utility
Article • 08/11/2023

FancyZones is a window manager utility for arranging and snapping windows into
efficient layouts to improve your workflow and restore layouts quickly. You can define a
set of zone locations to use as targets for windows on your desktop. When you drag a
window into a zone, or use the associated keyboard shortcut, the window is resized and
repositioned to fill that zone.

Snapping to a single zone with mouse

Drag the window. By default, you'll also need to select and hold Shift . You'll see the
zones appear. As you move your mouse, hovering over a zone will highlight that zone.

You can also trigger zone selection mode by using a non-primary mouse button if Use
non-primary mouse button to toggle zone activation is selected.

If both Hold Shift key to activate zones while dragging and Use non-primary mouse
button to toggle zone activation are cleared, zones will appear immediately after you
start dragging the window.

Snapping to a single zone with keyboard

Select Override Windows Snap in the FancyZones settings. Use Win +[arrow keys] to
snap a window to a zone. Use Move windows based on to choose whether to move
windows based the zone index or a window's relative position.

Snapping to multiple zones

A window can be snapped to more than one zone in the following ways.

Snapping to two zones by hovering the edges

If two zones are adjacent, you can snap a window to the sum of their area (rounded to
the minimum rectangle that contains both). When the mouse cursor is near the
common edge of two zones, both zones are activated simultaneously, allowing you to
drop the window into both zones.

Snapping to multiple zones with the mouse and keyboard

Drag the window until one zone is activated, then hold Ctrl while dragging the window
to select multiple zones.

Snapping to multiple zones with only the keyboard

Turn on the Override Windows Snap toggle and select Move windows based on:
Relative position. Use Win + Ctrl + Alt +[arrow keys] to expand the window to multiple
zones.

Window switching
When two or more windows are snapped in the same zone, cycle between the snapped
windows in that zone by using the shortcut Win + PgUp/PgDn .

Shortcut keys

ﾉ Expand table

Shortcut Action

⊞ Win + Shift + ` Opens the editor (this shortcut can be changed in the Settings window)

⊞ Win + Left/Right Move focused window between zones (only if Override Windows Snap
hotkeys is selected and Zone index is chosen; in that case only the
⊞ Win + Left and ⊞ Win + Right are overridden, while the ⊞ Win
+ Up and ⊞ Win + Down keep working as usual)

⊞ Win + Move focused window between zones (only if Override Windows Snap
Left/Right/Up/Down hotkeys is selected and Relative position is chosen; in that case all the
⊞ Win + Left , ⊞ Win + Right , ⊞ Win + Up and ⊞ Win + Down are
overridden)

⊞ Win + PgUp/PgDn Cycle between windows snapped to the same zone

⊞ Win + Ctrl + Alt + Quickly apply custom layout (you need to assign number to the custom
[number] layout in the editor first)

FancyZones doesn't override the Windows ⊞ Win + Shift +[arrow keys] to quickly move
a window to an adjacent monitor.

Snapping apps with elevated permission

To snap applications that are elevated (such as Windows Terminal or Task Manager), run
PowerToys in administrator mode. Read Running as administrator for more information.

Getting started with the editor

FancyZones includes an editor for layouts that can be accessed in PowerToys Settings.

Open the layout editor

Open the layout editor by selecting Open layout editor or with Win + Shift + ` ("back-
tick" or "accent grave"). You can change the FancyZones layout editor shortcut in
PowerToys Settings.
Layout Editor: Choose your layout
When you first open the layout editor, you'll see a list of layouts that can be adjusted by
how many windows are on the monitor. Selecting a layout shows a preview of that
layout on the screen. The selected layout is applied automatically. Double-clicking a
layout will apply it and close the editor. Select a monitor, and it becomes the target of
the selected layout.
Space around zones

Show space around zones sets the size of margin around each FancyZone window.
Enter a custom width of the margin in Space around zones. With the layout editor open,
change Show space around zones after changing the values to see the new value
applied.

Distance to highlight adjacent zones sets a custom value for the amount of space
between zones until they snap together, or before both are highlighted enabling them
to merge together.

Default layout for horizontal monitor orientation and Default layout for vertical
monitor orientation set which layout to use as the default when the display
configuration is changed in the system (for example, if you add a new display).
Creating a custom layout
Select Create new layout at the bottom.

There are two styles of custom zone layouts: Grid and Canvas.

The Grid model starts with a three column grid and allows zones to be created by
splitting and merging zones, moving the gutter between zones as desired. This is a
relative layout and will resize with different screen sizes. You can edit the layout using
mouse or keyboard.

Mouse

To divide a zone: click your mouse. To rotate the divider: hold down Shift .
To move a divider: click on the thumb and drag or select the thumb by focusing
the layout.
To merge/delete zones: select a zone, hold the left mouse button and drag the
mouse until multiple zones are selected. Release the button and a popup menu
will show up. Select Merge and they will become one zone. This is how a zone
should be deleted, by merging it into another zone.

Keyboard

First, focus the layout by pressing Ctrl + Tab . All zones and dividers can be
focused by pressing Tab .
 To divide a zone: focus the zone you want to divide and press S or Shift + S to
divide it.
To move a divider: focus the divider and press arrow keys to move it.
To merge/delete zones: focus the divider between zones and press Delete . All
zones adjacent to deleted divider will be merged into one zone.

The Canvas model starts with one zone and supports adding zones that can be moved
and resized, similar to windows. Zones in the canvas model may be overlapping.

Canvas layout also has keyboard support for zone editing. Use the arrow keys (Left,
Right, Up, Down) to move a zone by 10 pixels, or Ctrl +arrow to move a zone by 1
pixel. Use Shift +arrow to resize a zone by 10 pixels (5 per edge), or Ctrl + Shift

+arrow to resize a zone by 2 pixels (1 per edge). To switch between the editor and
dialog, press Ctrl + Tab .
Quickly changing between custom layouts

７ Note

Select Enable quick layout switch to use this feature.

A custom layout can be configured to have a user-defined hotkey to quickly apply it to

the active screen. The hotkey can be set by opening the custom layout's edit dialog.
Once set, the custom layout can be applied by pressing the Win + Ctrl + Alt +[number]
binding. The layout can also be applied by pressing the hotkey when dragging a
window.

In the demo below, we start with a default template applied to the screen and two
custom layouts that we assign hotkeys for. We then use the Win + Ctrl + Alt +[number]
binding to apply the first custom layout and snap a window to it. Finally, we apply the
second custom layout while dragging a window and snap the window to it.
  Tip

The settings for custom zone layouts are saved in the file
%LocalAppData%\Microsoft\PowerToys\FancyZones\custom-layouts.json . This file can

be manually changed to tweak zones, and exported to share layouts across devices.
Other json files in the same directory can be modified to alter settings for monitors,
layout hotkeys, etc. Be warned that editing these files is not recommended as it
may cause other issues with FancyZones functionality.

Settings
ﾉ Expand table

Setting Description

Activation shortcut To change the default hotkey, click on the control and enter the
desired key combination.

Open editor on the display Select where the Editor will show.

Hold Shift key to activate Toggles between auto-snap mode with the Shift key
zones while dragging (disabling snapping during a drag) and manual snap mode
where pressing the Shift key during a drag enables snapping.
Setting Description

Use a non-primary mouse Clicking a non-primary mouse button toggles the zones
button to toggle zone activation
activation

Use middle mouse button to Use the middle mouse button to select multiple zones
toggle multiple zones
spanning

Show zones on all monitors By default, FancyZones shows only the zones available on the
while dragging a window focused monitor. (This feature may have a performance impact
when selected)

Allow zones to span across Treat all connected monitors as one large screen. To work
monitors (all monitors must correctly, it requires all monitors to have the same DPI scaling
have the same DPI scaling) factor. (There might be unexpected effects when using monitors
in different orientations)

When multiple zones overlap Choose how to deal with overlapping zones.

Zone appearance Choose system or custom colors for the layouts

Show zone number Should the number of the zone be visible when layout is shown

Opacity (%) The percentage of opacity of active and inactive zones. (default:
50%)

Highlight color The color of a zone when it is the active drop target during the
dragging of a window.

Inactive color The color of zones when they are not an active drop during the
dragging of a window.

Border color The color of the border of active and inactive zones.

Number color The color of the number of the zone

Keep windows in their zones FancyZones will resize and reposition windows into the zones
when the screen resolution they were previously in, after a screen resolution change.
changes

During zone layout changes, FancyZones will resize and position windows into the new zone
windows assigned to a zone layout by maintaining the previous zone number location of
will match new size/position each window.

Move newly created windows Automatically move a newly opened window into the last zone
to the last known zone location that application was in.

Move newly created windows When this option is selected, and Move newly created windows
to the current active monitor to the last known zone is cleared or the application doesn't
Setting Description

have a last known zone, it moves the application on the current

active monitor.

Restore the original size of Unsnapping a window will restore its size as before it was
windows when unsnapping snapped.

Make dragged window When the zones are activated, the window being dragged is
transparent made transparent to improve the layout visibility.

Allow popup windows Popup windows couldn't be snapped by default. However, this
snapping could be the reason why some windows don't trigger
FancyZones when dragging. This setting affects all popup
windows including notifications.

Allow child windows snapping Child windows couldn't be snapped by default. However, this
could be the reason why some windows don't trigger
FancyZones when dragging.

Disable round corners when Only for Windows 11.

window is snapped

Switch between windows in Allows cycling activation between windows in the same zone.
the current zone

Next window To change the default hotkey, click on the control and then
enter the desired key combination.

Previous window To change the default hotkey, click on the control and then
enter the desired key combination.

Override Windows Snap When this option is checked and FancyZones is running, it
hotkeys (Win + arrow) to move overrides the Windows Snap keys: ⊞ Win + Left , ⊞ Win +
between zones Right , ⊞ Win + Up and ⊞ Win + Down .

Move windows based on Zone index allows to use ⊞ Win + Left and ⊞ Win + Right
to snap a window based on its index. ⊞ Win + Up , ⊞ Win +
Down are not overridden.
Relative position overwrites all ⊞ Win +[arrow keys] and
chooses zone to snap relative to the zone layout

Move windows between zones Cleared: snapping with ⊞ Win +[arrow keys] cycles the window
across all monitors through the zones on the current monitor.
Selected: it cycles the window through all the zones on all
monitors.

Enable quick layout switch Enables hotkeys to quickly changes layouts - see individual
layout settings.

Flash zones when switching The zones will flash when a layout is selected via the shortcut.
Setting Description

layout

Exclude applications from Add an application's name, or part of the name, one per line
snapping to zones (e.g. adding Notepad will match both Notepad.exe and
Notepad++.exe ; to match only Notepad.exe add the .exe
extension)
６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
File Explorer add-ons utility
Article • 04/12/2024

２ Warning

Enabling the preview handlers will override other preview handlers already installed
- there have been reports of incompatibility between Outlook and the PDF Preview
Handler.

Preview Pane previewers

Preview Pane is an existing feature in Windows File Explorer which allows you to see a
preview of the file's contents in the view's reading pane. PowerToys adds multiple
extensions: Markdown, SVG, PDF, G-code and QOI. In addition to those, PowerToys also
adds support for source code files for more than 150 file extensions.

Preview Pane supports:

SVG images (.svg)

Markdown files (.md)
Source code files (.cs, .cpp, .rs, …)
PDF files (.pdf)
G-code files (.gcode)
QOI images (.qoi)

Settings for Source code files previewer

Expand the Source code files (Monaco) section to change the following settings.

ﾉ Expand table

Setting Description

Wrap text Enable or disable word wrapping.

Try to format the source for Enable or disable formatting of the source code for json and
preview xml files.
The original file stays unchanged.

Maximum file size to preview Maximum file size in kilobytes to preview.

Enabling Preview Pane support
To enable preview support, set the extension to On.

If the preview pane does not appear to work after setting the extension to On, there is
an advanced setting in Windows that may be blocking the preview handler. Go to
Options in Windows File Explorer and under the View tab, you will see a list of
Advanced settings. Ensure that Show preview handlers in preview pane is selected in
order for the preview pane to display.
Enabling the Explorer pane in Windows 11
Open Windows File Explorer, go to View in the Explorer ribbon and select Preview pane.

Enabling the Explorer pane in Windows 10

Open Windows File Explorer, go to View in the Explorer ribbon and select Preview Pane.

７ Note

It is not possible to change the background color of the preview pane, so if you are
working with transparent images with white shapes, you may not be able to see
them in the preview.
Thumbnail Previews
To enable thumbnail preview support, set the extension to On.

Thumbnail preview supports:

SVG images (.svg)

PDF files (.pdf)
G-code files (.gcode)
STL files (.stl)
QOI images (.qoi)

７ Note

A reboot may be required after enabling the thumbnail previewer for the settings
to take effect. Thumbnails might not appear on paths managed by cloud storage
solutions like OneDrive, since these solutions may get their thumbnails from the
cloud instead of generating them locally.

Settings for Stereolithography (.stl) files

Expand the Stereolithography section to change the background color.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
File Locksmith utility
Article • 04/12/2024

File Locksmith is a Windows shell extension for checking which files are in use and by
which processes.

How to activate and use File Locksmith

To activate File Locksmith, open PowerToys and turn on the Enable File Locksmith
toggle. Select one or more files or directories in Windows File Explorer. If a directory is
selected, all of its files and subdirectories will be scanned as well. Right-click on the
selected file(s), select Show more options to expand the list of menu options, then
select Unlock with File Locksmith to open File Locksmith and see which processes are
using the file(s).

When File Locksmith is opened, it will scan all of the running processes that it can
access, checking which files the processes are using. Processes that are being run by a
different user cannot be accessed and may be missing from the list of results. To scan all
processes, select Restart as administrator.
After scanning, a list of processes will be displayed. Select End task to terminate the
process, or select the expander to show more information. File Locksmith will
automatically remove terminated processes from the list, whether or not this action was
done via File Locksmith. To manually refresh the list of processes, select Reload.

See also
PowerToys overview
Installing PowerToys

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Hosts File Editor utility
Article • 04/12/2024

Windows includes a local "Hosts" file that contains domain names and matching IP
addresses, acting as a map to identify and locate hosts on IP networks. Every time you
visit a website, your computer will check the hosts file first to see which IP address it
connects to. If the information is not there, your internet service provider will look into
the Domain Name Server (DNS) for the resources to load the site. The Hosts File Editor
provides a convenient way to edit the hosts file. This can be useful for scenarios like
migrating a website to a new hosting provider or domain name, which may take a 24-48
hour period of downtime. Creating a custom IP address to associate with your domain
using the hosts file can enable you to see how it will look on the new server.

Adding a new entry

Ensure that the Hosts File Editor is set to On in the PowerToys Settings.

To add a new entry using the Hosts File Editor:

Select New entry

Enter the IP address
Enter the Host name
Enter any comments that may be helpful in identifying the purpose of the entry
Turn on the Active toggle and select Add
Filtering host file entries
To filter host file entries, select the filter icon and enter data in either the Address, Hosts,
or Comment field to narrow the scope of results.
Back up Hosts file
Hosts File Editor creates a backup of the hosts file before editing session. The backup
files are located near the hosts file in %SystemRoot%\System32\drivers\etc named
hosts_PowerToysBackup_YYYYMMDDHHMMSS .

Settings
From the Settings menu, the following options can be configured:

ﾉ Expand table

Setting Description

Open as administrator Open as administrator to be able edit the hosts file. If disabled, the
editor is run in read-only mode. Hosts File Editor is started as
administrator by default.
 Setting Description

Show a warning at Warns that editing hosts can change DNS names resolution. Enabled
startup by default.

Additional lines position Default value is Top. If Bottom is selected, the file header is moved
below hosts settings to the bottom.

Consider loopback Loopback addresses (like 127.0.0.1 and ::1) are considered as
addresses as duplicates duplicates.

Troubleshooting
A "Failed to save hosts file" message appears if a change is made without administrator
permissions:

Select Open as administrator in settings to fix the error.

６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Image Resizer utility
Article • 01/09/2024

Image Resizer is a Windows shell extension for bulk image-resizing. After installing
PowerToys, right-click on one or more selected image files in File Explorer, and select
Resize with ImageResizer from the menu.

Image Resizer allows you to resize images by dragging and dropping your selected files
with the right mouse button. This way, resized pictures can quickly be saved in a folder.

７ Note

If Ignore the orientation of pictures is selected, the width and height of the
specified size may be swapped to match the orientation (portrait/landscape) of the
current image. In other words: If selected, the smallest number (in width/height) in
 the settings will be applied to the smallest dimension of the picture. Regardless if
this is declared as width or height. The idea is that different photos with different
orientations will still be the same size.

Settings
On the Image Resizer page, configure the following settings.

Sizes
Add new preset sizes. Each size can be configured as Fill, Fit or Stretch. The dimension to
be used for resizing can be centimeters, inches, percent and pixels.

Fill versus Fit versus Stretch

Fill: Fills the entire specified size with the image. Scales the image proportionally.
Crops the image as needed.
Fit: Fits the entire image into the specified size. Scales the image proportionally.
Does not crop the image.
Stretch: Fills the entire specified size with the image. Stretches the image
disproportionally as needed. Does not crop the image.

 Tip

You can leave the width or height empty. The dimension will be calculated to a
value proportional to the original image aspect ratio.

Fallback encoding
The fallback encoder is used when the file cannot be saved in its original format. For
example, the Windows Meta File (.wmf) image format has a decoder to read the image,
but no encoder to write a new image. In this case, the image cannot be saved in its
original format. Specify the format the fallback encoder will use: PNG, JPEG, TIFF, BMP,
GIF, or WMPhoto settings. This is not a file type conversion tool, but only works as a
fallback for unsupported file formats.

File
The file name of the resized image can use the following parameters:

ﾉ Expand table

Parameter Result

%1 Original filename

%2 Size name (as configured in the PowerToys Image Resizer settings)

%3 Selected width

%4 Selected height
 Parameter Result

%5 Actual height

%6 Actual width

Example: setting the filename format to %1 (%2) on the file example.png and selecting
the Small file size setting, would result in the file name example (Small).png . Setting
the format to %1_%4 on the file example.jpg and selecting the size setting Medium 1366 ×
768px would result in the file name example_768.jpg .

You can specify a directory in the filename format to group resized images into sub-
directories. Example: a value of %2\%1 would save the resized image(s) to
Small\example.jpg

Characters that are illegal in file names will be replaced by an underscore _ .

You can choose to retain the original last modified date on the resized image or reset it
at time of the resizing action.

See also
Microsoft PowerToys overview
Installing PowerToys
General settings for PowerToys

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Keyboard Manager utility
Article • 03/20/2024

The PowerToys Keyboard Manager enables you to redefine keys on your keyboard.

For example, you can exchange the letter A for the letter B on your keyboard. When
you press the A key, a B will be inserted.

You can exchange shortcut key combinations. For example: The shortcut key Ctrl + C

will copy text in many applications. With PowerToys Keyboard Manager utility, you can
swap that shortcut for ⊞ Win + C . Now, ⊞ Win + C will copy text. If you do not specify a
targeted application in PowerToys Keyboard Manager, the shortcut exchange will be
applied globally across Windows.

Also, you can exchange key or shortcut to arbitrary unicode text sequence. For example,
you can exchange the letter H for the text Hello! . When you press the H key, Hello!
will be inserted. Similarly, you can use shortcut Ctrl + G to send some text (e.g. Hello
from shortcut! ).
PowerToys Keyboard Manager must be enabled (with PowerToys running in the
background) for remapped keys and shortcuts to be applied. If PowerToys is not
running, key remapping will no longer be applied.

） Important

There are some shortcut keys that are reserved by the operating system or cannot
be replaced. Keys that cannot be remapped include:

⊞ Win + L and Ctrl + Alt + Del cannot be remapped as they are reserved by
the Windows OS.
The Fn (function) key cannot be remapped (in most cases). The F1 ~ F12

(and F13 ~ F24 ) keys can be mapped.

Pause will only send a single key-down event. So mapping it against the
backspace key, for instance, and pressing and holding will only delete a single
character.
⊞ Win + G often opens the Xbox Game Bar, even when reassigned. Game Bar
can be disabled in Windows Settings.

Settings
To create mappings with Keyboard Manager, open the PowerToys Settings. In PowerToys
Settings, on the Keyboard Manager tab, you will see options to:

Open the Remap Keys settings window by selecting Remap a key

Open the Remap Shortcuts settings window by selecting Remap a shortcut

Remapping keys
To remap a key, open the Remap Keyboard settings window with Remap a Key. When
first opened, no predefined mappings will be displayed. Select Add key remapping to
add a new remap. Note that various keyboard keys actually send a shortcut.

Once a new remap row appears, select the input key whose output you want to change
in the “Select” column. Select the new key, shortcut or text value to assign in the “To
send” column.

For example, to press A and have B appear:

 ﾉ Expand table

Select: To send:

A B

To swap key positions between the A and B keys, add another remapping with:

ﾉ Expand table

Select: To send:

B A

Remapping a key to a shortcut

To remap a key to a shortcut (combination of keys), enter the shortcut key combination
in the "To send" column.

For example, to press the Ctrl key and have it result in ⊞ Win + ← (left arrow):

ﾉ Expand table

Select: To send:

Ctrl ⊞ Win + ←
 ） Important

Key remapping will be maintained even if the remapped key is used inside another
shortcut. The order of key press matters in this scenario as the action is executed
during key-down, not key-up. For example, pressing Ctrl + C would result as ⊞
Win + left arrow + C . Pressing the Ctrl key will first execute ⊞ Win + left

arrow . Pressing the C key first will execute C + ⊞ Win + left arrow .

Remapping a key to text

To remap a key to arbitrary unicode text, in the "To send" column first select "Text" in the
combo box and then fill the text box with wanted text.

For example, to press the H key and have it result in Hello! :

ﾉ Expand table

Select: To send:

H Hello!

Remapping shortcuts
To remap a shortcut key combination, like Ctrl + C , select Remap a shortcut to open
the Remap Shortcuts settings window.

When first opened, no predefined mappings will be displayed. Select Add shortcut
remapping to add a new remap.

When a new remap row appears, select the input keys whose output you want to
change in the “Select” column. Select the new shortcut value to assign in the “To send”
column.

For example, the shortcut Ctrl + C copies selected text. To remap that shortcut to use
the Alt key, rather than the Ctrl key:

ﾉ Expand table

Select: To send:

Alt + C Ctrl + C
There are a few rules to follow when remapping shortcuts. These rules only apply to the
"Shortcut" column.

Shortcuts must begin with a modifier key: Ctrl , Shift , Alt , or ⊞ Win

Shortcuts must end with an action key (all non-modifier keys): A, B, C, 1, 2, 3, etc.
Shortcuts cannot exceed four keys in length, or five if the shortcut is a 'chord'.

Shortcuts with chords

Shortcuts can be created with one or more modifiers and two non-modifier keys. These
are called "chords". In order to create a chord, select Edit to open the dialog to record
the shortcut using the keyboard. Once opened, toggle on the Allow chords switch. This
allows you to enter two non-modifier keys. For example, you can create shortcuts using
a chord based on 'V' for Volume Up and Volume Down like this:

ﾉ Expand table

Select: To send:

Shift + Ctrl + V , U Volume Up

Shift + Ctrl + V , D Volume Down

Chords are handy if you have a number of shortcuts that are similar, and it makes sense
to have them all start with the same non-modifier key.

Remap a shortcut to a single key

It is possible to remap a shortcut (key combination) to a single key press by selecting
Remap a shortcut in PowerToys Settings.

For example, to replace the shortcut ⊞ Win + ← (left arrow) with a single key press Alt:
 ﾉ Expand table

Select: To send:

⊞ Win + ← Alt

） Important

Shortcut remapping will be maintained even if the remapped key is used inside
another shortcut. The order of key press matters in this scenario as the action is
executed during key-down, not key-up. For example: pressing ⊞ Win + ← + Shift

would result in Alt + Shift .

Remap a shortcut to text

For example, to replace the shortcut Ctrl + G with Hello! text, choose Text in the
combo box and enter "Hello!":

ﾉ Expand table

Select: To send:

Ctrl + G Hello!

Remap a shortcut to start an app

Keyboard Manager enables you to start applications with the activation of any shortcut.
Choose Start App for the action in the "To:" column. There are a few options to
configure when using this type of shortcut.

ﾉ Expand table

Option Meaning

App This is the path to an executable. Environment variables will be expanded.

Args Arguments that will be sent to the app.

Start in The working directory for the app to start in.

Elevation Specify the elevation level to start the app. The options include Normal, Elevated, and
Different User.
 Option Meaning

If What action should be taken when this shortcut is activated while the app is already
running running? The options are: Show Window, Start another instance, Do nothing, Close,
End task.

Visibility The app will be visible. This is useful if the app is a console or something you don't
want to see.

Remap a shortcut to open a URI

This type of shortcut action will open a URI. The only input is the actual Path/URI. Almost
anything you can issue on the command line should work. See Launch an app with a URI
for more examples.

App-specific shortcuts
Keyboard Manager enables you to remap shortcuts for only specific apps (rather than
globally across Windows).

For example, in the Outlook email app the shortcut Ctrl + E is set by default to search
for an email. If you prefer instead to set Ctrl + F to search your email (rather than
forward an email as set by default), you can remap the shortcut with "Outlook" set as
your "Target app".

Keyboard Manager uses process-names (not application names) to target apps. For
example, Microsoft Edge is set as "msedge" (process name), not "Microsoft Edge"
(application name). To find an application's process name, open PowerShell and enter
the command get-process or open Command Prompt and enter the command
tasklist . This will result in a list of process names for all applications you currently have

open. Below is a list of a few popular application process names.

ﾉ Expand table

Application Process name

Microsoft Edge msedge.exe

OneNote onenote.exe

Outlook outlook.exe

Teams ms-teams.exe

Adobe Photoshop Photoshop.exe

 Application Process name

File Explorer explorer.exe

Spotify Music spotify.exe

Google Chrome chrome.exe

Excel excel.exe

Word winword.exe

Powerpoint powerpnt.exe

How to select a key

To select a key or shortcut to remap:

Select Select.
Use the drop-down menu.

Once you select Select, a dialog window will open in which you can enter the key or
shortcut, using your keyboard. Once you’re satisfied with the output, hold Enter to
continue. To leave the dialog, hold Esc .

Using the drop-down menu, you can search with the key name and additional drop-
down values will appear as you progress. However, you can not use the type-key feature
while the drop-down menu is open.

Orphaning Keys
Orphaning a key means that you mapped it to another key and no longer have anything
mapped to it. For example, if the key is remapped from A to B , then a key no longer
exists on your keyboard that results in A . To remind you of this, a warning will display
for any orphaned keys. To fix this, create another remapped key that is mapped to result
in A .
Frequently asked questions

I remapped the wrong keys, how can I stop it quickly?

For key remapping to work, PowerToys must be running in the background and
Keyboard Manager must be enabled. To stop remapped keys, close PowerToys or
disable Keyboard Manager in the PowerToys settings.

Can I use Keyboard Manager at my log-in screen?

No, Keyboard Manager is only available when PowerToys is running and doesn't work on
any password screen, including while Run As Admin.

Do I have to restart my computer or PowerToys for the

remapping to take effect?
No, remapping should occur immediately upon pressing OK.

Where are the Mac/Linux profiles?

Currently Mac and Linux profiles are not included.

Will this work on video games?

We suggest that you avoid using Keyboard Manager when playing games as it may
affect the game's performance. It will also depend on how the game accesses your keys.
Certain keyboard APIs do not work with Keyboard Manager.

Will remapping work if I change my input language?

Yes it will. Right now if you remap A to B on English (US) keyboard and then change
the language setting to French, typing A on the French keyboard ( Q on the English US
physical keyboard) would result in B , this is consistent with how Windows handles
multilingual input.

Can I have different key mappings across multiple

keyboards?
Currently no. We are not aware of an API where we can see the input and which device it
came from. The typical use case here is a laptop with an external keyboard connected.

I see keys listed in the drop down menus that don't work.
Why is that?
Keyboard Manager lists mappings for all known physical keyboard keys. Some of these
mappings may not be available on your keyboard as there may not be a physical key
that it corresponds to. For instance: the Start App 1 option shown below is only
available on keyboards that physically have a Start App 1 key. Trying to map to and
from this key on a keyboard that does not support the Start App 1 key will result in
undefined behavior.

Troubleshooting
If you have tried to remap a key or shortcut and are having trouble, it could be one of
the following issues:

Run As Admin: Remapping will not work on an app or window if that window is
running in administrator (elevated) mode and PowerToys is not running as
administrator. Try running PowerToys as an administrator.
Not intercepting keys: Keyboard Manager intercepts keyboard hooks to remap
your keys. Some apps that also do this can interfere with Keyboard Manager. To fix
this, go to the settings, disable and enable Keyboard Manager.

Known Issues
Keyboard Manager should not be used when playing video games. Keyboard
Manager interception of key presses currently will impact the FPS.
Remapping keys like Win, Ctrl, Alt or Shift may break gestures and some special
keys
AltGr and Ctrl+Alt gives issues, since AltGr behaves as (L)Ctrl + (R)Alt and
remapping one of these keys can break the function.
Note that some keyboard keys actually send a shortcut. Common examples are the
Office key (Win+Ctrl+Alt+Shift) and the Copilot key (Win + C or Left-Shift +
Windows key + F23).

See the list of all open keyboard manager issues .

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Mouse utilities
Article • 09/27/2023

Mouse utilities is a collection of features that enhance mouse and cursor functionality
on Windows.

Find my mouse
Activate a spotlight that focuses on the cursor's position by pressing the Ctrl key twice,
using a custom shortcut or by shaking the mouse. Click the mouse or press any
keyboard key to dismiss it. If you move the mouse while the spotlight is active, the
spotlight will dismiss on its own shortly after the mouse stops moving.

Settings
From the settings page, the following options can be configured:

ﾉ Expand table

Setting Description

Activation method Choose between Press Left Ctrl twice, Press Right Ctrl twice, Shake
mouse or Custom shortcut.
 Setting Description

Minimum distance to Adjust sensitivity.

shake

Activation shortcut The custom shortcut used to activate the spotlight.

Do not activate when Prevents the spotlight from being used when actively playing a game on
Game Mode is on the system.

Overlay opacity The opacity of the spotlight backdrop. (default: 50%)

Background color The color of the spotlight backdrop. (default: #000000)

Spotlight color The color of the circle that centers on the cursor. (default: #FFFFFF)

Spotlight radius The radius of the circle that centers on the cursor. (default: 100px)

Spotlight initial zoom The spotlight animation's zoom factor. Higher values result in more
pronounced zoom animation as the spotlight closes in on the cursor
position.

Animation duration Time for the spotlight animation. (default: 500ms)

Excluded apps Add an application's name, or part of the name, one per line (e.g. adding
Notepad will match both Notepad.exe and Notepad++.exe ; to match only
Notepad.exe add the .exe extension).

Mouse Highlighter
Display visual indicators when the left or right mouse buttons are clicked. By default,
mouse highlighting can be turned on and off with the Win + Shift + H shortcut.

Settings
From the settings page, the following options can be configured:

ﾉ Expand table

Setting Description

Activation shortcut The customizable keyboard command to turn mouse highlighting on

or off.

Left button highlight The highlighter color for the left mouse button.
color

Right button highlight The highlighter color for the right mouse button.
color

Always on highlight The highlighter color for the mouse pointer.

color

Overlay opacity The opacity of the highlighter.

Radius The radius of the highlighter - Measured in pixels.

Fade delay How long it takes before a highlight starts to disappear - Measured in
milliseconds.

Fade duration Duration of the disappear animation - Measured in milliseconds.

Mouse jump

Mouse jump allows moving the mouse pointer long distances on a single screen or
across multiple screens.

ﾉ Expand table

Setting Description

Activation shortcut The customizable keyboard command to activate the mouse jump.

Mouse pointer Crosshairs

Mouse Pointer Crosshairs draws crosshairs centered on the mouse pointer.

ﾉ Expand table

Setting Description

Activation shortcut The customizable keyboard command to turn

mouse crosshairs on or off.

Color The color for the crosshairs.

Opacity (default: 75%)

Center radius (default: 20px)

Crosshairs thickness (default: 5px)

Border color The color for the crosshair borders.

Setting Description

Border size Size of the border, in pixels.

Automatically hide crosshairs when the

mouse pointer is hidden

Fix crosshairs length

Crosshairs fixed length (px)

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Mouse Without Borders
Article • 01/30/2024

Mouse Without Borders enables you to control up to 4 computers from the same
machine.

Features:

Control a set of machines using the same keyboard/mouse.

Share clipboard between the machines.
Transfer files between the machines.

How to use Mouse Without Borders

With the latest version of PowerToys installed, you will see Mouse Without Borders listed
in the PowerToys Settings, where you will need to do some initial configuration.

Initial configuration
1. Open Mouse Without borders in PowerToys Settings to configure your
connections.

2. On the first computer, select New Key to generate a security key for connecting.

3. On the second computer, enter the security key that was generated on the first
computer and the name of the first computer. Then select Connect.

4. Once the computers are connected, you will be able to move between them by
moving your mouse cursor beyond the edge of the screen.
It's possible to switch the order of the devices by dragging the device icon to a new
position in the layout.
Install Mouse Without Borders as a service
To allow Mouse Without Borders to control elevated applications or the lock screen
from another computer, it's possible to run Mouse Without Borders as a service under
the System account.

To enable the service mode, run PowerToys in administrator mode and turn on the Use
Service toggle.

２ Warning

Running Mouse Without Borders as a service account brings added control and
ease of use to the controlled machines, but this also brings some additional
security risks in case someone wants to use Mouse Without Borders as an attack
vector. Be mindful of your risk tolerance.

Mouse Without Borders settings

 ﾉ Expand table

Setting Description

New key Generate a new key for the machine and resets current connections.

Security key Represents the security key used between the connected machines.
Can only be changed by generating a new key.

Connect Connect to other machines knowing the other machine's name and
security key.

Local machine's host Show the current machine's host name.

name

Device layout Allows arranging the machine's position relative to each other by
dragging the machines in the layout.

Refresh connections Select this button to refresh the connections this machine has to the
other machines.

Devices in a single row Arrange the devices in a single row or in a 2x2 matrix.

Use Service Install Mouse Without Borders as a service to allow controlling the
lock screen and elevated applications.

Uninstall Service Uninstall the service from the computer.

Wrap mouse Wraps the mouse around to the first machine, after passing the edge
of the last machine and vice-versa.

Share clipboard

Transfer file Files can be copied via the clipboard. Limit is 100 MB.

Hide mouse at the Position the mouse cursor of one machine at the top edge of the
screen's edge screen when switching to another machine.

Draw mouse cursor Attempt to draw the mouse cursor on machines that have no physical
peripheral attached.

Validate remote machine Use reverse DNS lookup to validate remote machines IP addresses.
IP

Same subnet only Only connect to machines in the same intranet.

Block screen saver on Prevent the screen saver from starting on other machines.
other machines

Move mouse relatively May help in solving issues when the machine's resolutions are
different or there are multiple screen scenarios.
 Setting Description

Block mouse at screen Avoid accidentally switching machines when the mouse pointer is at
corners screen corners.

Show clipboard and Show clipboard activities and network status in system tray
network status messages notifications.

Easy Mouse Use the mouse pointer to switch between machines at screen edges.
Can also be configured to need to select Shift or Control to switch
between machines.

Shortcut to toggle Easy Set a Ctrl + Alt +<letter> shortcut to toggle Easy Mouse.
Mouse

Shortcut to lock all Set a Ctrl + Alt +<letter> shortcut to press twice to lock all
machines machines. Only works in the machines that have the same setting.

Shortcut to try Set a Ctrl + Alt +<letter> shortcut to try reconnecting.

reconnecting

Shortcut to switch to Set a Ctrl + Alt +<letter> shortcut to start sending the same input
multiple machine mode to all machines at the same time.

Shortcut to switch Set a Ctrl + Alt +<number> shortcut to switch to a specific

between machines machine. Ctrl + Alt + 3 switches to the third machine and so on.
F1 , F2 , F3 and F4 can also be used.

Add a firewall rule for Install a firewall rule for Mouse Without Borders.
Mouse Without Borders

Show the original Mouse Show the original UI from Mouse Without Borders through the
Without Borders UI original tray icon. Mouse Without Borders needs to be restarted for it
to take effect.

Status Colors
The following colors are used to indicate the connection status to the user when trying
to connect to another computer:

ﾉ Expand table

Connection Status Color Hex Code

N/A Dark Grey #00717171

Resolving Yellow #FFFFFF00

 Connection Status Color Hex Code

Connecting Orange #FFFFA500

Handshaking Blue #FF0000FF

Error Red #FFFF0000

ForceClosed Purple #FF800080

InvalidKey Brown #FFA52A2A

Timeout Pink #FFFFC0CB

SendError Maroon #FF800000

Connected Green #FF008000

Troubleshooting
If you can't setup the initial connection:

Make sure all machines are connected on the same network.

Check if the security key and computer host name are correctly inserted.
Check if the Firewall is blocking connections. Select Add a firewall rule for Mouse
Without Borders to make adjustments.

If the connection is lost:

Make sure the machines are still connected.

Select Refresh connections in Settings (or use the Refresh shortcut).

Known Issues
Copy/Paste between machines only works with a single file and the size limit is
100MB.
Drag/Drop between machines works with single file only and it does not work with
network files.
 Copy/Paste, Drag/Drop does not work with folder and multiple files, the
workaround is to zip them first.
If the host machine has a full-screen focused Remote Desktop/virtual machine
window (or some kind of simulator window), the keyboard might not follow the
mouse to another machine. The workaround is to enable the option Hide mouse
at screen edge in the Settings or switch the focus to another window first.
The mouse pointer might be invisible if there is no physical mouse attached to the
machine. Plug in an unused mouse or turn on Mouse Keys in Control Panel.
Some settings may not sync correctly and may need to be manually changed to be
the same on all machines.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Paste as Plain Text
Article • 04/12/2024

PowerToys Paste as Plain Text enables you to paste text stored in your clipboard,
excluding any text-formatting, using a quick key shortcut. Any formatting included with
the clipboard text will be replaced with an unformatted version of the text.

Getting started

Enabling
To start using Paste as Plain Text, enable it in the PowerToys Settings.

Activating
Execute the paste as plain text action with the activation shortcut (default: Ctrl + Win +
Alt + V ).

Settings
From the Settings menu, the following options can be configured:

ﾉ Expand table

Setting Description

Activation shortcut The customizable keyboard command to execute this action.

７ Note

It's possible to set Ctrl + V as the activation shortcut. This is not recommended, as
overriding this shortcut may have unintended consequences.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Peek utility
Article • 04/12/2024

A system-wide utility for Windows to preview file content without the need to open
multiple applications or interrupt your workflow. It offers a seamless and quick file
preview experience for various file types, including images, Office documents, web
pages, Markdown files, text files, and developer files.

Preview a file
Select a file in File Explorer and open the Peek preview using the activation /
deactivation shortcut (default: Ctrl + Space ).

Using Left and Right or Up and Down , you can scroll between all files in the current
folder. Select multiple files in File Explorer for previewing to scroll only between selected
ones.

Pin preview window position and size

The Peek window adjusts its size based on the dimensions of the images being
previewed. However, if you prefer to keep the window's size and position, you can use
the pinning feature. By selecting the pinning button, the window will preserve the
current size and position. Selecting the pinning button again will unpin the window.
When unpinned, the Peek window will return to the default position and size when
previewing the next file.

Open file with the default program

Select Open with or Enter to open the current file with the default program.

Settings
From the settings page, the following options can be configured:

ﾉ Expand table

Setting Description

Activation shortcut The customizable keyboard command to open Peek

for the selected file(s).

Always run not elevated, even when Tries to run Peek without elevated permissions, to fix
PowerToys is elevated access to network shares.

Automatically close the Peek window

after it loses focus

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
PowerRename utility
Article • 08/31/2023

PowerRename is a bulk renaming tool that enables you to:

Modify the file names of a large number of files, without giving all of the files the
same name.
Perform a search and replace on a targeted section of file names.
Perform a regular expression rename on multiple files.
Check expected rename results in a preview window before finalizing a bulk
rename.
Undo a rename operation after it is completed.

Demo
In this demo, all instances of the file name "foo" are replaced with "foobar". Since all of
the files are uniquely named, this would have taken a long time to complete manually
one-by-one. PowerRename enables a single bulk rename. Notice that the Explorer's
"Undo Rename" (Ctrl+Z) command makes it possible to undo the last change.

PowerRename window
After selecting files in Windows File Explorer, right-click and select Rename with
PowerRename (which will appear only if enabled in PowerToys). The selected items will
be displayed, along with search and replace values, a list of options, and a preview pane
displaying results of the search and replace values entered.

Search for
Enter text or a regular expression to find the files in your selection that contain the
criteria matching your entry. You will see the matching items in the Preview pane.

Replace with
Enter text to replace the Search for value entered previously. You can see the original file
name and renamed file name in the Preview pane.

Use regular expressions

If selected, the Search value will be interpreted as a regular expression (regex). The
Replace value can also contain regex variables (see examples below). If cleared, the
Search value will be interpreted as plain text to be replaced with the text in the Replace
field.

For more information regarding the Use Boost library option in the settings menu for
extended regex functionalities, see the regular expressions section.
Match all occurrences
If selected, all matches of text in the Search field will be replaced with the Replace text.
Otherwise, only the first instance of the Search for text in the file name will be replaced.

For example, given the file name: powertoys-powerrename.txt :

Search for: power

Rename with: super

The value of the renamed file would result in:

Match all occurrences cleared: supertoys-powerrename.txt

Match all occurrences selected: supertoys-superrename.txt

Case sensitive
If selected, the text specified in the Search field will only match text in the items if the
text is the same case. Case matching will be insensitive by default.

Apply to: Filename only

Only the file name is modified by the operation. For example: txt.txt → NewName.txt .

Apply to: Extension only

Only the file extension is modified by the operation. For example: txt.txt →
txt.NewExtension .

Include files
Clearing causes files to not be included in the operation.

Include folders
Clearing causes folders to not be included in the operation.

Include subfolders
Clearing causes files within folders to not be included in the operation. By default, all
subfolder items are included.
Text formatting
Choose between four options to either convert items to be all lowercase, all uppercase,
title case (first character of sentence is capitalized), or capitalize every word.

Enumerate items
If selected, you can use the following patterns as part of the Replace with text:

ﾉ Expand table

Variable pattern Explanation

${} A simple counter that will start from zero for the first renamed file.

${increment=X} A counter with a customized incrementer value.

${padding=X} A counter with a specified number of leading zeroes for the number.

${start=X} A counter with a customized initial value.

You can also use multiple counters in the same replace string and combine
customizations.

For example, given a Search text a and a set of files:

a.jpg
ab.jpg
abc.jpg

A Replace with text Image_${padding=4;increment=2;start=10}_ would produce the

following:

Image_0010_.jpg
Image_0012_b.jpg
Image_0014_bc.jpg

Replace using file creation date and time

The creation date and time attributes of a file can be used in the Replace with text by
entering a variable pattern according to the table below. Selecting the tool-tip in the
Replace with field allows you to view and select from the supported patterns.
 ﾉ Expand table

Variable Explanation
pattern

$YYYY Year, represented by a full four or five digits, depending on the calendar used.

$YY Year, represented only by the last two digits. A leading zero is added for single-
digit years.

$Y Year, represented only by the last digit.

$MMMM Name of the month.

$MMM Abbreviated name of the month.

$MM Month, as digits with leading zeros for single-digit months.

$M Month, as digits without leading zeros for single-digit months.

$DDDD Name of the day of the week.

$DDD Abbreviated name of the day of the week.

$DD Day of the month, as digits with leading zeros for single-digit days.

$D Day of the month, as digits without leading zeros for single-digit days.

$hh Hours, with leading zeros for single-digit hours.

$h Hours, without leading zeros for single-digit hours.

$mm Minutes, with leading zeros for single-digit minutes.

$m Minutes, without leading zeros for single-digit minutes.

$ss Seconds, with leading zeros for single-digit seconds.

$s Seconds, without leading zeros for single-digit seconds.

$fff Milliseconds, represented by full three digits.

$ff Milliseconds, represented only by the first two digits.

$f Milliseconds, represented only by the first digit.

For example, given the file names:

powertoys.png , created on 11/02/2020 (november second)

powertoys-menu.png , created on 11/03/2020 (november third)

Enter the criteria to rename the items:

Search for: powertoys

Rename with: $MMM-$DD-$YY-powertoys

The value of the renamed file would result in:

Nov-02-20-powertoys.png

Nov-03-20-powertoys-menu.png

Regular expressions
For most use cases, a simple search and replace is sufficient. There may be occasions,
however, in which complicated renaming tasks require more control. Regular
Expressions can help.

Regular Expressions define a search pattern for text. They can be used to search, edit
and manipulate text. The pattern defined by the regular expression may match once,
several times, or not at all for a given string. PowerRename uses the ECMAScript
grammar, which is common amongst modern programming languages.

To enable regular expressions, select Use Regular Expressions. Note: You will likely want
to select Match all occurrences while using regular expressions.

To use the Boost library instead of the standard library, select the Use Boost library
option in the PowerToys settings. It enables extended features, like lookbehind , which
are not supported by the standard library.

Examples of regular expressions

Simple matching examples.

ﾉ Expand table

Search for Description

^ Match the beginning of the filename (zero size)

$ Match the end of the filename (zero size)

.* Match all the text in the name

^foo Match text that begins with "foo"

 Search for Description

bar$ Match text that ends with "bar"

^foo.*bar$ Match text that begins with "foo" and ends with "bar"

.+?(?=bar) Match everything up to "bar"

foo[\s\S]*bar Match everything between and including "foo" and "bar"

Matching and variable examples. Capturing groups are defined in parentheses () . To

refer to them, use $ followed by a number: $1 will refer to the first group, $2 to the
second etc. When using the variables, "Match all occurrences" must be selected.

ﾉ Expand table

Search for Replace Description

with

(.*).png foo_$1.png Prepends "foo_" to the existing file name for

PNG files

(.*).png $1_foo.png Appends "_foo" to the existing file name for

PNG files

(.*) $1.txt Appends ".txt" extension to existing file

(^\w+\.$)\|(^\w+$) $2.txt Appends ".txt" extension to existing file name

only if it does not have an extension

(\d\d)-(\d\d)-(\d\d\d\d) or $3-$2-$1 Move parts in the filename: "29-03-2020"

(\d{2})-(\d{2})-(\d{4}) becomes "2020-03-29"

^(.{n})(.*) or (.*)(.{n})$ $1foo$2 Insert "foo" n characters from the beginning or

the end, respectively

^.{n} or .{n}$ nothing Trim n characters from the beginning or the

end, respectively

Additional resources for learning regular expressions

There are great examples/cheatsheets available online to help you:

Regular Expression Tutorial

JavaScript Regular Expressions Tutorial with Examples

File list filters
Filters can be used in PowerRename to narrow the results of the rename. Use the
Preview pane to check expected results.

Original, the first column in the Preview pane switches between:

Selected: The file is selected to be renamed
Cleared: The file is not selected to be renamed (even though it fits the value
entered in the search criteria)

Renamed, the second column in the Preview pane can be toggled:

The default preview will show all selected files, with only files matching the
Search for criteria displaying the updated rename value.
Selecting the Renamed header will toggle the preview to only display files that
will be renamed. Other selected files from your original selection will not be
visible.

Settings
Additional options can be configured in the settings, as described below:

ﾉ Expand table
Setting Description

Show PowerRename in PowerRename appears as one of the default options or only

in the extended context menu

Hide icon in context menu Hides the PowerRename icon in the context menu

Enable auto-complete for the Automatically suggest terms to use in the search and
search and replace fields replace fields based on prior uses of PowerRename

Maximum number of items The largest number of search and replace suggestions to
display

Show recently used strings When opening PowerRename, populate the search and
replace fields with the last values used

Use Boost library Enable extended regex functionality. See Regular

Expressions for more details

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
PowerToys Run utility
Article • 04/09/2024

PowerToys Run is a quick launcher for power users that contains additional features
without sacrificing performance. It is open source and modular for additional plugins.

To use PowerToys Run, select Alt + Space and start typing! (Note that this shortcut can
be changed in the settings window.)

） Important

PowerToys must be running in the background and Run must be enabled for this
utility to work.

Features
PowerToys Run features include:

Search for applications, folders or files

Search for running processes (previously known as Window Walker )
Clickable buttons with keyboard shortcuts (such as Open as administrator or Open
containing folder)
Invoke Shell Plugin using > (for example, > Shell:startup will open the Windows
startup folder)
Do a simple calculation using calculator
Execute system commands
Get time and date information
Convert units
Calculate hashes
Generate GUIDs
 Open web pages or start a web search

Settings
The following general options are available on the PowerToys Run settings page.

ﾉ Expand table

Setting Description

Activation shortcut Define the keyboard shortcut to show/hide PowerToys Run

Use centralized keyboard hook Try this setting if there are issues with the shortcut
(PowerToys Run might not get focus when triggered from an
elevated window)

Ignore shortcuts in full-screen When in full-screen (F11), PowerToys Run won't be engaged
mode with the shortcut

Input smoothing Add a delay to wait for more input before executing a search

Immediate plugins How many milliseconds a plugin that makes the UI wait
should wait before showing results

Background execution plugins How many milliseconds a plugin that executes in the
background should wait before showing results

Maximum number of results Maximum number of results shown without scrolling

before scrolling

Clear the previous query on When opened, previous searches will not be highlighted
opening

Results order tuning Fine tunes the ordering of the displayed results

Selected item weight Use a higher number to get selected results to rise faster
(Default: 5, 0 to disable)

Wait for slower plugin results Selecting this can help preselect the top, more relevant
before selecting top item in result, but at the risk of jumpiness
results

Tab through context buttons When enabled, you can tab through the context buttons
before tabbing to the next result

Generate thumbnails for files Thumbnails will be generated for files in the results list (this
may affect speed and stability)

Preferred monitor position If multiple displays are in use, PowerToys Run can be opened
on:
 Setting Description

• Primary display
• Display with mouse cursor
• Display with focused window

App theme Change the theme used by PowerToys Run

Plugin manager
PowerToys Run uses a plugin system to provide different types of results. The settings
page includes a plugin manager that allows you to enable/disable the various available
plugins. By selecting and expanding the sections, you can customize the direct
activation commands used by each plugin. In addition, you can select whether a plugin
appears in global results and set additional plugin options where available.
Direct activation commands
The plugins can be activated with a direct activation command so that PowerToys Run
will only use the targeted plugin. The following table shows the direct activation
commands assigned by default.

 Tip
 You can change commands to fit your personal needs in the plugin manager.

） Important

Some characters and phrases may conflict with global queries of other plugins if
you use them as activation commands. For example, using ( breaks global
calculation queries starting with an opening parenthesis.

Currently known conflicting character sequences:

Characters used in paths like \ , \\ , / , ~ , % .

Characters used in mathematical operations like . , , , + , - , ( .
Names of mathematical operations.

ﾉ Expand table

Plug-in Direct Example

activation
command

Calculator = = 2+2

Windows ? ? road to find 'roadmap.txt'

search

History !! !! car to find any results that have been selected in the
past, from any enabled plugin, that matches 'car'.

Installed . . code to get Visual Studio Code. (See Program parameters

programs for options on adding parameters to a program's startup.)

OneNote o: o: powertoys to search your local OneNote notebooks for

pages containing "powertoys"

Registry keys : : hkcu to search for the 'HKEY_CURRENT_USER' registry

key.

Windows ! ! alg to search for the 'Application Layer Gateway' service

services to be started or stopped
!startup:auto to search all services that start automatically
!status:running to show all running services

Shell command > > ping localhost to do a ping query.

Time and date ) ) time and date shows the current time and date in
different formats.
Plug-in Direct Example
activation
command

) calendar week::04/01/2022 shows the calendar week for

the date '04/01/2022'.

Unit converter %% %% 10 ft in m to calculate the number of meters in 10 feet.

Value # # guid3 ns:URL www.microsoft.com to generate the GUIDv3

Generator for the URL namespace using the URL namespace.
# sha1 abc to calculate the SHA1 hash for the string 'abc'.
# base64 abc to encode the string 'abc' to base64.

URI-handler // // to open your default browser.

// learn.microsoft.com to have your default browser go to
Microsoft Learn.
mailto: and ms-settings: links are supported.

Visual Studio { { powertoys to search for previously opened workspaces,

Code remote machines and containers that contain 'powertoys' in
their paths.

Web search ?? ?? to open your default browser's search page.

?? What is the answer to life to search with your default
browser's search engine.

Windows $ $ Add/Remove Programs to open the Windows settings page

settings for managing installed apps.
$ Device: to list all settings with 'device' in their
area/category name.
$ control>system>admin shows all settings of the path
'Control Panel > System and Security > Administrative
Tools'.

Windows _ _ powershell to list all profiles that contains 'powershell' in

Terminal their name.
profiles

Window Walker < < outlook to find all open windows that contain 'outlook' in
their name or the name of their process.

Using PowerToys Run

General keyboard shortcuts

ﾉ Expand table
 Shortcut Action

Alt + Space Show or hide PowerToys Run

(default)

Esc Hide PowerToys Run

Ctrl + Shift + Open the selected application as administrator (only applicable to

Enter applications)

Ctrl + Shift + U Open the selected application as different user (only applicable to
applications)

Ctrl + Shift + E Open containing folder in File Explorer (only applicable to applications
and files)

Ctrl + C Copy path location (only applicable to folders and files)

Tab Navigate through the search results and context menu buttons

System commands
The Windows System Commands plugin provides a set of system level actions that can
be executed.

 Tip

If your system language is supported by PowerToys, the system commands will be

localized. If you prefer English commands, clear the Use localized system
commands instead of English ones checkbox in the plugin manager.

ﾉ Expand table

Command Action Note

Shutdown Shuts down the computer

Restart Restarts the computer

Sign Out Signs current user out

Lock Locks the computer

Sleep Puts the computer to sleep

Hibernate Hibernates the computer

 Command Action Note

Recycle Bin Result: Opens the recycle bin The query Empty Recycle Bin shows the
Context menu: Empties the Recycle result too.
Bin

UEFI Firmware Reboots the computer into UEFI Only available on systems with UEFI
Settings Firmware Settings firmware. Requires administrative
permissions.

IP address * Shows the ip addresses from the The search query has to start with the
network connections of your word IP or the word address .
computer.

MAC address * Shows the mac addresses from the The search query has to start with the
network adapters in your computer. word MAC or the word address .

*) This command may take some time to provide the results.

Program plugin
The Program plugin can open software applications (such as Win32 or packaged
programs). The plugin scans common install locations, like the Start menu and desktops
that you have access to, looking for executable files (.exe) or shortcut files (such as .lnk
or .url). On occasion, a program may not be found by the program plugin scan and you
may want to manually create a shortcut in the directory containing the program you
want to access.

Program parameters
The Program plugin allows for program arguments to be added when opening an
application. The program arguments must follow the expected format as defined by the
program's command line interface.

７ Note

To input valid search queries, the first element after the program name has to be
one of the following possibilities:

The characters sequence -- .

A parameter that starts with - .
A parameter that starts with -- .
A parameter that starts with / .
For example, when opening Visual Studio Code, specify the folder to be opened with:

Visual Studio Code -- C:\myFolder

Visual Studio Code also supports a set of command line parameters , which can be
used with their corresponding arguments in PowerToys Run to, for instance, view the
difference between files:

Visual Studio Code -d C:\foo.txt C:\bar.txt

If the program plugin's option Include in global result is not selected, include the
activation phrase, . by default, to invoke the plugin's behavior:

.Visual Studio Code -- C:\myFolder

Calculator plugin

） Important

Please be aware of the different decimal and thousand delimiters in different locals.
The Calculator plugin respects the number format settings of your system. If you
prefer the English (United States) number format, change the behavior for the
query input and the result output in the plugin manager. If your system's number
format uses the comma ( , ) as the decimal delimiter, you have to write a space
between the number(s) and comma(s) on operations with multiple parameters. The
input has to look like this: min( 1,2 , 3 , 5,7) or min( 1.2 , 3 , 5.7) .

 Tip

The Calculator plugin can handle some implied multiplications like 2(3+4) and
(1+2)(3+4) by inserting the multiplication operator where appropriate.

The Calculator plugin supports the following operations:

ﾉ Expand table

Operation Operator Description

Syntax

Addition a+b

Subtraction a-b
Operation Operator Description
Syntax

Multiplication a*b

Division a/b

Modulo/Remainder a%b

Exponentiation a^b

Ceiling function ceil( x.y ) Rounds a number up to the next larger integer.

Floor function floor( x.y ) Rounds a number down to the next smaller integer.

Rounding round( x.abcd ) Rounds to the nearest integer.

Exponential function exp( x ) Returns e raised to the specified power.

Maximum max( x, y, z )

Minimum min( x, y, z )

Absolute abs( -x ) Absolute value of a number.

Logarithm base 10 log( x )

Logarithm base e ln( x )

Square root sqrt( x )

Power of x pow( x, y ) Calculate a number (x) raised to the power of some

other number (y).

Factorial x!

Sign sign( -x ) A number that indicates the sign of value:

• -1 if number is less than zero.
• 0 if number is zero.
• 1 if number is greater than zero.

Random number rand() Returns a fractional number between 0 and 1.

Pi pi Returns the number pi.

Sine sin( x )

Cosine cos( x )

Tangent tan( x )

Arc Sine arcsin( x )

 Operation Operator Description
Syntax

Arc Cosine arccos( x )

Arc Tangent arctan( x )

Hyperbolic Sine sinh( x )

Hyperbolic Cosine cosh( x )

Hyperbolic Tangent tanh( x )

Hyperbolic Arc Sine arsinh( x )

Hyperbolic Arc Cosine arcosh( x )

Hyperbolic Arc artanh( x )

Tangent

History plugin
The History plugin allows quick access to previously selected results from other plugins.
You can access and remove them using the direct activation command. To remove them
from history, select the Remove this from history context menu item.

History plugin examples

If you paste in a URL like https://github.com/microsoft/PowerToys/pull/123333 ,
then you can later quickly access this with just !! 123333 or even !! 333 . This
works just as well for file paths, registry paths, and other things where later you
can only remember part of the path. Any place you navigate to using PowerToys
run can be quickly found in the history.
If you recently did some math like = 1245+6789 , and you need to recall it, it will be
in the history. You can find it with !! 678 or even !! 8034 .
If you can't remember what you searched for to find that app/folder/setting, you
can just view them all with just !! .

Time and date plugin

The Time and date plugin provides the current time and date or a custom one in
different formats. You can enter the format or a custom time/date or both when
searching.
 ） Important

The Time and Date plugin respects the date and time format settings of your
system. Please be aware of the different notations in different locals.

） Important

For global queries the first word of the query has to be a complete match.

Examples:

time or ) time to show the time.

) 3/27/2022 to show all available formats for a date value.

) calendar week::3/27/2022 to show the calendar week for a date value.

) unix epoch::3/27/2022 10:30:45 AM to convert the given time and date value

into a Unix epoch timestamp.

Unit converter plugin

） Important

The Unit Converter plugin respects the number format settings of your system.
Please be aware of the different decimal characters and thousands delimiters in
different locals. The names and abbreviations of the units aren't localized yet.

The Unit Converter plugin supports the following unit types:

Acceleration
Angle
Area
Duration
Energy
Information technology
Length
Mass
Power
Pressure
Speed
Temperature
 Volume

Value Generator plugin

The Value Generator plugin can generate GUIDs/UUIDs, calculate hashes, and
encode/decode strings to base64.

UUIDs
It supports the following GUID versions:

v1 - Time based
v3 - Namespace and name based, using MD5
v4 - Random value
v5 - Namespace and name based, using SHA1

７ Note

For versions 3 and 5 there are some predefined namespaces: DNS, URL, OID and
X500. You can use the following predefined namespaces:

ns:DNS

ns:URL

ns:OID

ns:X500

Examples:

ﾉ Expand table

Command Result

# guid Generate a random GUID.

# uuid
# uuidv4

# guidv1 Generate a version 1 GUID.

# uuidv1

# guidv3 ns:DNS Generate the GUID version 3 for www.microsoft.com using the
www.microsoft.com DNS namespace.
# uuidv3 ns:DNS The namespace parameter can be any valid GUID, and the name
www.microsoft.com parameter can be any string.
  Tip

The guid and uuid keywords are interchangeable and the v is optional. I.e. guid5
and guidv5 are the same.

Hashing
It supports the following hashing algorithms:

MD5
SHA1
SHA256
SHA384
SHA512

Usage:

# md5 abc

Base64

Usage for encoding a string:

# base64 abc

Usage for decoding a string:

# base64d SGVsbG8gV29ybGQ=

URL
Usage for encoding an URL:

# url https://bing.com/?q=My Test query

７ Note

The whole URL including the / and the protocol identifier gets encoded. If you
only like to encode the query part of the URL you should only enter this part.

Usage for decoding an URL:

 # urld https://bing.com/?q=My+Test+query

Escaped data string

Usage for escaping a data string:

# esc:data C:\Program Files\PowerToys\PowerToys.exe

Usage for unescaping a data string:

# uesc:data C%3A%5CProgram%20Files%5CPowerToys%5CPowerToys.exe

Escaped hex character

Usage for escaping a single character:

# esc:hex z

Usage for decoding an URL:

# uesc:hex %7A

７ Note

Only the first hexadecimal character of your input is converted. The rest of the
input is ignored.

Folder plugin
With the folder plugin you can navigate through your directories.

Search filter
In the Folder plugin you can filter the results by using some special characters.

ﾉ Expand table

Character sequence Result Example

> Search inside the folder C:\Users\tom\Documents\>

* Search files by mask C:\Users\tom\Documents\*.doc

 Character sequence Result Example

>* Search files inside the folder by mask C:\Users\tom\Documents\>*.doc

Windows Settings plugin

The Windows Settings plugin allows you to search in Windows settings. You can search
by their name or by their location.

To search by location you can use the following syntax:

$ device: to list all settings with 'device' in the area name.

$ control>system>admin to show all settings of the path Control Panel > System

and Security > Administrative Tools.

Service plugin
The Service plugin lets you search, start, stop and restart Windows services directly from
the PowerToys Run search screen.

To search for Windows services, enable the plugin, open PowerToys Run and enter the
name of the service. Additionally, you can use the following syntax:

!startup:automatic to list all services with start type 'automatic'.

!status:running to list all currently running services.

Window Walker plugin

With the Window Walker plugin you can switch to other windows, close them or kill the
window process.

Kill a window process

With the Window Walker plugin you can kill the process of a window if it stops
responding.

７ Note

There are some limitations for the "kill process" feature:

Killing the Explorer process is only allowed if each folder window is running in
its own process.
 You can only kill elevated processes if you have admin permissions (UAC).
Windows of UWP apps don't know their process until they are searched in
non-minimized state.

２ Warning

If you kill the process of an UWP app window, you kill all instances of the app. All
windows are assigned to the same process.

File Explorer setting

If the File Explorer settings in Windows are not set to open each window in a separate
process, you will see the following message when searching for open Explorer windows:

You can turn off the message in the PowerToys Run plugin manager options for Window
Walker, or select the message to change the File Explorer settings. On the Folder
options window, select Launch folder windows in a separate process.
Windows Search plugin
With the Windows Search plugin you can search for files and folders that are indexed by
the Windows Search Index service.

Windows Search settings

If the indexing settings for Windows Search are not set to cover all drives, you will see
the following warning when using the Windows Search plugin:
You can turn off the warning in the PowerToys Run plugin manager options for Windows
Search, or select the warning to expand which drives are being indexed. After selecting
the warning, the Windows settings page Searching Windows will open.

On the Searching Windows page, you can:

Select Enhanced mode to enable indexing across all of the drives on your
Windows machine.
Specify folder paths to exclude.
Select Advanced Search Indexer Settings to set advanced index settings, add or
remove search locations, index encrypted files, etc.
Known issues
For a list of all known issues and suggestions, see the PowerToys product repository
issues on GitHub .

Attribution
Wox
Beta Tadele's Window Walker

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Quick Accent utility
Article • 03/04/2024

Quick Accent is an alternative way to type accented characters, useful when a keyboard
doesn't support that specific accent with a quick key combo. This tool is based on
Damien Leroy's PowerAccent .

In order to use the Quick Accent utility, open PowerToys Settings, select the Quick
Accent page, and turn on the Enable toggle.

How to activate
Activate by holding the key for the character you want to add an accent to, then (while
held down) press the activation key (Space key or Left / Right arrow keys). If you
continue to hold, an overlay to choose the accented character will appear.

For example: If you want "à", press and hold A and press Space .

With the dialog enabled, keep pressing your activation key.

Character sets
You can limit the available characters by selecting a character set from the settings
menu. Available character sets are:

Catalan
Currency
Croatian
Czech
Danish
Gaeilge
 Gàidhlig
Dutch
Greek
Estonian
Finnish
French
German
Hebrew
Hungarian
Icelandic
Italian
Kurdish
Lithuanian
Macedonian
Maori
Norwegian
Pinyin
Polish
Portuguese
Romanian
Slovak
Slovenian
Spanish
Serbian
Swedish
Turkish
Welsh

Settings
From the Settings menu, the following options can be configured:

ﾉ Expand table

Setting Description

Activation key Choose Left/Right Arrow, Space or Left, Right or Space.

Character set Show only characters that are in the chosen set.

Toolbar location Position of the toolbar.

Setting Description

Show the Unicode code and Shows the Unicode code (in hexadecimal) and name of the
name of the currently currently selected character under the selector.
selected character

Sort characters by usage

frequency

Start selection from the left Starts the selection from the leftmost character for all activation
keys (including Left/Right arrow).

Input delay The delay in milliseconds before the dialog appears.

Excluded apps Add an application's name, or part of the name, one per line (e.g.
adding Notepad will match both Notepad.exe and Notepad++.exe ;
to match only Notepad.exe add the .exe extension).

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Registry Preview
Article • 04/12/2024

PowerToys Registry Preview simplifies the process of visualizing and editing complex
Windows Registry files. It can also write changes to the Windows Registry.

Getting started

Enable
To start using Registry Preview, enable it in the PowerToys Settings.

How to activate
Select one or more .reg files in Windows File Explorer. Right-click on the selected file(s)
and select Preview to open Registry Preview. On Windows 11: select Show more
options to expand the list of menu options. Registry Preview can also be opened from
PowerToys Settings.

Note: Currently, there is a 10MB file limit for opening Windows Registry files with
Registry Preview. It will show a message if a file contains invalid content.

How to use
After opening a Windows Registry file, the content is shown. This content can be
updated at any time.
On the other side there is a visual tree representation of the registry keys listed in the
file. This visual tree will be updated on each file content change inside the app.

Select a registry key in the visual tree to see the values of that registry key below it.

Select Edit to open the file in Notepad.

Select Reload to reload file content in case the file is changed outside of the Registry
Preview.

Select Write to registry to save the data listed in the Preview to the Windows Registry.
The Windows Registry Editor will ask for confirmation before writing data.

Select Open key to open the Windows Registry Editor with the location of the key you
have highlighted in the treeview as the initial starting point.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Screen ruler utility
Article • 04/12/2024

Screen ruler allows you to quickly measure pixels on your screen, based on image edge
detection. This was inspired by Pete Blois's Rooler .

How to activate
Use ⊞ Win + Shift + M to activate and select which tool you want to measure with. To
close, use Esc or select ╳ in the toolbar.

How to use
Bounds (dashed square symbol): This is a bounding box. Click and drag with your
mouse. If you hold Shift , the box(es) will stay in place until you cancel the
interaction.
Spacing (╋): Measure horizontal and vertical spacing at the same time. Select the
symbol and move your mouse to your target location.
Horizontal (━): Measure only horizontal spacing. Select the symbol and move your
mouse pointer to your target location.
Vertical (┃): Measure only vertical spacing. Select the symbol and move your
mouse pointer to your target location.
Cancel interaction: Esc , ╳ or mouse click. Upon clicking the primary mouse
button, the measurement is copied to the clipboard.

The controls on the toolbar can also be selected via Ctrl + 1 / 2 / 3 / 4 .

 Tip
 Scroll up with the mouse wheel to increase the threshold for pixel difference by 15
units per wheel tick. Effectively the measuring line can become longer. Scroll down
to reverse.

Settings
From the Settings menu, the following options can be configured:

ﾉ Expand table

Setting Description

Activation shortcut The customizable keyboard command to turn the toolbar on or off.

Capture screen When off, the utility takes a single snapshot of your screen. When this
continuously during is turned on, the utility will attempt real-time detection. Continuous
measuring mode will consume more resources when in use.

Per color channel edge Test if all color channels are within a tolerance distance from each
detection other. Otherwise, check that the sum of all color channels differences is
smaller than the tolerance.

Pixel tolerance for edge A value between 0-255. A higher value will provide a higher variation
detection so it will be more forgiving with things like gradients and shadows.

Draw feet on the cross Adds small, serif-like "feet" for additional visual recognition.

Line color The color for the line that does the measuring.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Windows key shortcut guide
Article • 04/09/2024

This guide displays common keyboard shortcuts that use the Windows key.

Getting started
Open the shortcut guide with the shortcut key combination: ⊞ Win + Shift + / (or as
we like to think, ⊞ Win + ? ) or hold down the ⊞ Win for the time as set in the Settings.
An overlay will appear showing keyboard shortcuts that use the Windows key, including:

common Windows shortcuts

shortcuts for changing the position of the active window
taskbar shortcuts

Keyboard shortcuts using the Windows key ⊞ Win can be used while the guide is
displayed. The result of those shortcuts (active window moved, arrow shortcut behavior
changes etc.) will be displayed in the guide.

Pressing the shortcut key combination again will dismiss the overlay.

Tapping the Windows key will display the Windows Start menu.

） Important

The PowerToys app must be running and Shortcut Guide must be enabled in the
PowerToys settings for this feature to be used.
Settings
These configurations can be edited from the PowerToys Settings:

ﾉ Expand table

Setting Description

Activation Choose your own shortcut or use the ⊞ Win key

method

Activation The custom shortcut used to open the shortcut guide

shortcut

Press duration Time (in milliseconds) to hold down the ⊞ Win key in order to open global
Windows shortcuts or taskbar icon shortcuts

App theme Light, Dark or Windows theme

Opacity of Opacity of the Shortcut Guide overlay

background

Excluded apps Ignores Shortcut Guide when these apps are in focus. Add an application's
name, or part of the name, one per line (e.g. adding Notepad will match both
Notepad.exe and Notepad++.exe ; to match only Notepad.exe add the .exe
extension).
６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Text Extractor utility
Article • 04/09/2024

Text Extractor enables you to copy text from anywhere on your screen, including inside
images or videos. This code is based on Joe Finney's Text Grab .

How to activate
With the activation shortcut (default: ⊞ Win + Shift + T ), you'll see an overlay on the
screen. Click and hold your primary mouse button and drag to activate your capture.
The text will be saved to your clipboard.

How to deactivate
Capture mode is closed immediately after text in the selected region is recognized and
copied to the clipboard. Close capture mode with Esc at any moment.

Adjust while trying to capture

By holding Shift , you change from adjusting the capture region's size to moving the
capture region. When you release Shift , you will be able to resize again.

） Important

1. The produced text may not be perfect, so you have to do a quick proof read
of the output.
2. This tool uses OCR (Optical Character Recognition) to read text on the screen.
3. The default language used will be based on your Windows system language
> Keyboard settings . OCR language packs are available for installation.

Settings
From the Settings menu, the following options can be configured:

ﾉ Expand table
 Setting Description

Activation shortcut The customizable keyboard command to turn on or off this module.

Preferred language The language used for OCR.

Supported languages
Text Extractor can only recognize languages that have the OCR language pack installed.

The list can be obtained via PowerShell by running the following commands:

PowerShell

# Please use Windows PowerShell, not PowerShell 7 as these aren't .NET Core
libraries

[Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType =

WindowsRuntime]

[Windows.Media.Ocr.OcrEngine]::AvailableRecognizerLanguages

How to query for OCR language packs

To return the list of all supported language packs, open PowerShell as an Administrator
(right-click, then select "Run as Administrator"), and enter the following command:

PowerShell

Get-WindowsCapability -Online | Where-Object { $_.Name -Like 'Language.OCR*'

}

An example output:

PowerShell

Name : Language.OCR~~~el-GR~0.0.1.0
State : NotPresent

Name : Language.OCR~~~en-GB~0.0.1.0
State : NotPresent

Name : Language.OCR~~~en-US~0.0.1.0
State : Installed

Name : Language.OCR~~~es-ES~0.0.1.0
 State : NotPresent

Name : Language.OCR~~~es-MX~0.0.1.0
State : NotPresent

The language and location is abbreviated, so "en-US" would be "English-United States"

and "en-GB" would be "English-Great Britain". If a language is not available in the
output, then it's not supported by OCR. State: NotPresent languages must be installed
first.

How to install an OCR language pack

The following commands install the OCR pack for "en-US":

PowerShell

$Capability = Get-WindowsCapability -Online | Where-Object { $_.Name -Like

'Language.OCR*en-US*' }

PowerShell

$Capability | Add-WindowsCapability -Online

How to remove an OCR language pack

The following commands remove the OCR pack for "en-US":

PowerShell

$Capability = Get-WindowsCapability -Online | Where-Object { $_.Name -Like

'Language.OCR*en-US*' }

PowerShell

$Capability | Remove-WindowsCapability -Online

Troubleshooting
This section will list possible errors and solutions.

"No Possible OCR languages are installed"

This message is shown when there are no available languages for recognition.

If an OCR pack is supported and installed, but still is not available and your system drive
X: is different than "C:", then copy X:/Windows/OCR folder to C:/Windows/OCR to fix the
issue.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Video Conference Mute
Article • 08/03/2023

７ Note

VCM is moving into legacy mode. Please find more about what this means in our
dedicated issue .

Quickly mute your microphone (audio) and turn off your camera (video) with a single
keystroke while on a conference call, regardless of what application has focus on your
computer.

Getting started
The default shortcuts to use Video Conference Mute are:

⊞ Win + Shift + Q to toggle both audio and video at the same time
⊞ Win + Shift + A to toggle microphone
⊞ Win + Shift + I to toggle microphone until key release
⊞ Win + Shift + O to toggle camera

When using the microphone and/or camera toggle shortcut keys, you'll see a small
toolbar letting you know whether your microphone and camera are set to on, off, or not
in use. Set the position of this toolbar in PowerToys settings.

To use this module, it must be selected as the source in the apps that are using camera
and/or microphone. Go to the settings and select PowerToys VCM.
Settings
The settings provide the following options:

ﾉ Expand table

Setting Description

Shortcuts Change the shortcut key used to mute your microphone, camera,
or both combined.

Selected microphone Select the microphone on your machine that this utility will use.

Push to reverse If enabled, allows both push to talk and push to mute, depending
on microphone state.

Selected camera Select the camera on your machine that this utility will use.

Camera overlay image Select an image to that will be used as a placeholder when your
camera is turned off. By default, a black screen will appear when
your camera is turned off with this utility.

Toolbar Set the position where the Microphone On, Camera On toolbar
displays when toggled (default: top right corner).

Show toolbar on Select whether you prefer the toolbar to be displayed on the main
monitor only (default) or on all monitors.
 Setting Description

Hide toolbar when both

camera and microphone are
unmuted

How this works under the hood

Applications interact with audio and video in different ways. If a camera stops working,
the application using it tends not to recover until the API does a full reset. To toggle the
global privacy camera on and off while using the camera in an application, typically it
will crash and not recover.
So, how does PowerToys handle this so you can keep streaming?

Audio: PowerToys uses the global microphone mute API in Windows. Apps should
recover when this is toggled on and off.
Video: PowerToys has a virtual driver for the camera. The video is routed through
the driver and then to the application. Selecting the Video Conference Mute
shortcut key stops video from streaming, but the application still thinks it is
receiving video. The video is just replaced with black or the image placeholder
you've saved in the settings.

Debug the camera driver

To debug the camera driver, open this file on your machine:
C:\Windows\ServiceProfiles\LocalService\AppData\Local\Temp\PowerToysVideoConference
.log

You can create an empty PowerToysVideoConferenceVerbose.flag in the same directory

to enable verbose logging mode in the driver.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Windows Subsystem for Linux
Documentation
Article • 06/27/2022

Windows Subsystem for Linux (WSL) lets developers run a GNU/Linux environment --
including most command-line tools, utilities, and applications -- directly on Windows,
unmodified, without the overhead of a traditional virtual machine or dual-boot setup.

Install WSL

Learn more
What is the Windows Subsystem for Linux (WSL)?
What's new with WSL 2?
Comparing WSL 1 and WSL 2
Frequently Asked Questions

Get started
Install WSL
Install Linux on Windows Server
Manual install steps
Best practices for setting up a WSL development environment

Try WSL preview features by joining the

Windows Insiders Program
To try the most recent features or updates to WSL, join the Windows Insiders
Program . Once you have joined Windows Insiders, you can choose the channel you
would like to receive preview builds from inside the Windows settings menu. You can
choose from:

Dev channel: Most recent updates, but low stability.

Beta channel: Ideal for early adopters, more reliable builds than the Dev channel.
Release Preview channel: Preview fixes and key features on the next version of
Windows just before its available to the general public.
Team blogs
Overview post with a collection of videos and blogs
Command-Line blog (Active)
Windows Subsystem for Linux Blog (Historical)

Provide feedback
GitHub issue tracker: WSL
GitHub issue tracker: WSL documentation

Related videos
WSL BASICS

1. What is the Windows Subsystem for Linux (WSL)? | One Dev Question (0:40)
2. I'm a Windows developer. Why should I use WSL? | One Dev Question (0:58)
3. I'm a Linux developer. Why should I use WSL? | One Dev Question (1:04)
4. What is Linux? | One Dev Question (1:31)
5. What is a Linux distro? | One Dev Question (1:04)
6. How is WSL different than a virtual machine or dual booting? | One Dev
Question
7. Why was the Windows Subsystem for Linux created? | One Dev Question (1:14)
8. How do I access files on my computer in WSL? | One Dev Question (1:41)
9. How is WSL integrated with Windows? | One Dev Question (1:34)
10. How do I configure a WSL distro to launch in the home directory in Terminal? |
One Dev Question (0:47)
11. Can I use WSL for scripting? | One Dev Question (1:04)
12. Why would I want to use Linux tools on Windows? | One Dev Question (1:20)
13. In WSL, can I use distros other than the ones in the Microsoft Store? | One Dev
Question (1:03)

WSL DEMOS

1. WSL2: Code faster on the Windows Subsystem for Linux! | Tabs vs Spaces (13:42)
2. WSL: Run Linux GUI Apps | Tabs vs Spaces (17:16)
3. WSL 2: Connect USB devices | Tabs vs Spaces (10:08)
4. GPU Accelerated Machine Learning with WSL 2 | Tabs vs Spaces (16:28)
5. Visual Studio Code: Remote Dev with SSH, VMs, and WSL | Tabs vs Spaces (29:33)
6. Windows Dev Tool Updates: WSL, Terminal, Package Manager, and more | Tabs
vs Spaces (20:46)
 7. Build Node.JS apps with WSL | Highlight (3:15)
8. New memory reclaim feature in WSL 2 | Demo (6:01)
9. Web development on Windows (in 2019) | Demo (10:39)

WSL DEEP DIVES

1. WSL on Windows 11 - Demos with Craig Loewen and Scott Hanselman |

Windows Wednesday (35:48)
2. WSL and Linux Distributions – Hayden Barnes and Kayla Cinnamon | Windows
Wednesday (37:00)
3. Customize your terminal with Oh My Posh and WSL Linux distros | Windows
Wednesday (33:14)
4. Web dev Sarah Tamsin and Craig Loewen chat about web development, content
creation, and WSL | Dev Perspectives (12:22)
5. How WSL accesses Linux files from Windows | Deep dive (24:59)
6. Windows subsystem for Linux architecture: a deep dive | Build 2019 (58:10)
What is Windows Terminal?
Article • 02/02/2024

Windows Terminal is a modern host application for the command-line shells you already
love, like Command Prompt, PowerShell, and bash (via Windows Subsystem for Linux
(WSL)). Its main features include multiple tabs, panes, Unicode and UTF-8 character
support, a GPU accelerated text rendering engine, and the ability to create your own
themes and customize text, colors, backgrounds, and shortcuts.

Install Windows Terminal

https://www.microsoft.com/en-us/videoplayer/embed/RWHAdS?postJsllMsg=true

７ Note

For more general info, check out Scott Hanselman's article: What's the difference
between a console, a terminal, and a shell? or Rich Turner's video What is a
command-line shell? .

Multiple profiles supporting a variety of

command line applications
Any application that has a command line interface can be run inside Windows Terminal.
This includes everything from PowerShell and Command Prompt to Azure Cloud Shell
and any WSL distribution such as Ubuntu or Oh-My-Zsh.

Tab tearout (Preview )

You can tear out tabs in Windows Terminal and create new windows.
You can also drag and drop tabs into existing windows.

Customized schemes and configurations

You can configure your Windows Terminal to have a variety of color schemes and
settings. To learn how to customize your prompt with cool themes, see Tutorial: Set up a
custom prompt for PowerShell or WSL with Oh My Posh To learn how to make your own
color scheme, visit the Color schemes page.
Custom actions
There are a variety of custom commands you can use in Windows Terminal to have it
feel more natural to you. If you don't like a particular keyboard shortcut, you can change
it to whatever you prefer.

For example, the default shortcut to copy text from the command line is Ctrl+Shift+C .
You can change this to Ctrl+1 or whatever you prefer. To open a new tab, the default
shortcut is Ctrl+Shift+T , but maybe you want to change this to Ctrl+2 . The default
shortcut to flip between the tabs you have open is Ctrl+Tab , this could be changed to
Ctrl+- and used to create a new tab instead.

You can learn about customizing shortcuts on the Actions page.

Unicode and UTF-8 character support

Windows Terminal can display Unicode and UTF-8 characters such as emoji and
characters from a variety of languages.

GPU accelerated text rendering

Windows Terminal uses the GPU to render its text, thus providing improved
performance over the default Windows command line experience.

Background image support

You can have background images and gifs inside your Windows Terminal window.
Information on how to add background images to your profile can be found on the
Profile - Appearance page.

Command line arguments

You can set Windows Terminal to launch in a specific configuration using command line
arguments. You can specify which profile to open in a new tab, which folder directory
should be selected, open the terminal with split window panes, and choose which tab
should be in focus.

For example, to open Windows Terminal from PowerShell with three panes, with the left
pane running a Command Prompt profile and the right pane split between your
PowerShell and your default profile running WSL, enter:
 PowerShell

wt -p "Command Prompt" `; split-pane -p "Windows PowerShell" `; split-pane -

H wsl.exe

Learn how to set up command-line arguments on the Command line arguments page.

６ Collaborate with us on Windows Terminal feedback

GitHub
Windows Terminal is an open source
The source for this content can project. Select a link to provide
be found on GitHub, where you feedback:
can also create and review
issues and pull requests. For  Open a documentation issue
more information, see our
contributor guide.  Provide product feedback
Sudo for Windows
Article • 02/08/2024

Sudo for Windows is a new way for users to run elevated commands (as an
administrator) directly from an unelevated console session on Windows.

Read the announcement , which includes a demo video and deep-dive into how Sudo
for Windows works.

Prerequisites
You must be running Windows 11 Insider Preview Build 26052 or higher to use the Sudo
for Windows command. (Check for Windows updates). Join Windows Insider Program .

７ Note

Sudo for Windows is not yet available for Windows 10, but may be in the future.

How to enable Sudo for Windows

To enable Sudo for Windows, open Settings > For Developers and set Enable sudo to
On.

２ Warning
 Sudo for Windows can be used as a potential escalation of privilege vector when
enabled in certain configurations. You should make sure to be aware of the security
considerations when enabling the sudo command on your machine.

How to configure Sudo for Windows

Sudo for Windows currently supports three different configuration options. The
configuration can be set from the Settings > For Developers menu or
programmatically, using the command line. The configuration options include:

In a new window ( forceNewWindow ): The forceNewWindow configuration option is

the default configuration option for Sudo for Windows. Use sudo in this
configuration to run the command in a new window. This is similar to the behavior
of the runas /user:admin command.

Input closed ( disableInput ): The disableInput configuration option will run the
elevated process in the current window, but with the input handle closed. This
means that the elevated process will not be able to receive input from the current
console window. This is useful for scenarios where you want to run a command as
an administrator, but do not want to allow the command to receive input from the
current console window. This configuration option provides some of the
convenience of the inline configuration option while mitigating some of the
associated security risks.

Inline ( normal ): The normal configuration option is most similar to how sudo
behaves on other operating systems. This configuration will run the elevated
process in the current window and the process will be able to receive input from
the current console session. This is useful for scenarios where you want to run a
command as an administrator and want to allow the command to receive input
from the current console window. This configuration option provides the most
convenience, but you should only choose this option if you are familiar with the
associated security risks.

You can select among these configurations from the Settings > For Developers menu
or change the configuration programmatically, in an elevated command line (admin
console), using:

sudo config --enable <configuration_option>

Update <configuration_option> to either forceNewWindow , disableInput , or normal .

How to use Sudo for Windows
To use Sudo for Windows, simply prepend sudo to the command you want to run as an
administrator. For example, to run netstat -ab as an administrator, you would run sudo
netstat -ab in your console window.

Because sudo elevates the targeted process to run with administrator-level permission,
a prompt will open asking you to verify that you want to continue.

Security Considerations
There are risks associated with running sudo in the Input closed ( inputClosed ) or Inline
( normal ) configurations. It is possible for malicious processes to attempt to drive the
elevated process using the connection established by the unelevated sudo.exe and the
elevated sudo.exe process.

The inputClosed configuration option mitigates risk by closing the input handle.
Disconnecting the input handle from the current console window means that
unelevated processes cannot send input to the elevated process.

The inline configuration option runs the elevated process in the current window and
the process is able to receive input from the current console session. An unelevated
process can send input to the elevated process within the same console windows or get
information from the output in the current windows in this configuration.

FAQ

How is Sudo for Windows different from the existing

runas command?

The sudo command offers a way to quickly elevate a command as administrator from
your current unelevated command line context and is familiar to some users coming
from other operating systems. The runas command offers a way to run programs as any
user, including administrator if you so choose. At this point in time, the sudo command
on Windows does not support running programs as other users. Other key differences
between sudo and runas include:

runas allows you to run programs as other users, including but not limited to as

administrator. This functionality is on the roadmap for the sudo command, but
does not yet exist.
 sudo allows you to quickly elevate a process (as administrator):

You can choose to do so in a new window, which resembles the runas

administrator flow.
You can choose to connect the elevated process to the current console window
with the disableInput and normal configuration options. This is not supported
with runas .

runas can prompt users for a password in the command-line.

sudo can only be elevated via the User Account Control (UAC) security feature

designed to protect the operating system from unauthorized changes using

verification prompt.

You should consider your particular use-case and plan to use the command that best
meets your needs. You should also consider the security implications of running sudo in
the inputClosed and normal modes. The default forceNewWindow configuration option is
recommended unless you are familiar and comfortable with the risks associated with the
other sudo configurations.

Sudo for Windows open source repository

Sudo for Windows is open source and welcomes your contributions and feedback. You
can find the source code for Sudo for Windows on GitHub .

Additional functionality
If you’re looking for additional functionality that Sudo for Windows does not provide,
check out Gerardo Grignoli’s gsudo which has a number of additional features and
configuration options or check out other solutions from the community.
６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Guide for changing your dev
environment from Mac to Windows
Article • 10/24/2022

The following tips and control equivalents should help you in your transition between a
Mac and Windows (or WSL/Linux) development environment.

For app development, the nearest equivalent to Xcode would be Visual Studio . There
is also a version of Visual Studio for Mac , if you ever feel the need to go back. For
cross-platform source code editing (and a huge number of plug-ins) Visual Studio
Code is the most popular choice.

Keyboard shortcuts

 Tip

You can use PowerToys Keyboard Manager to map Windows shortcuts to the
shortcuts you use on a Mac.

ﾉ Expand table

Operation Mac Windows

Copy Command+C Ctrl+C

Cut Command+X Ctrl+X

Paste Command+V Ctrl+V

Undo Command+Z Ctrl+Z

Save Command+S Ctrl+S

Open Command+O Ctrl+O

Lock computer Command+Control+Q WindowsKey+L

Show desktop Command+F3 WindowsKey+D

Open file browser Command+N WindowsKey+E

Minimize windows Command+M WindowsKey+M

Search Command+Space WindowsKey

Operation Mac Windows

Close active window Command+W Control+W

Switch current task Command+Tab Alt+Tab

Maximize a window to full screen Control+Command+F WindowsKey+Up

Save screen (Screenshot) Command+Shift+3 WindowsKey+Shift+S

Save window Command+Shift+4 WindowsKey+Shift+S

View item information or properties Command+I Alt+Enter

Select all items Command+A Ctrl+A

Select more than one item in a list Command, then click each Control, then click each
(noncontiguous) item item

Type special characters Option+ character key Alt+ character key

Trackpad shortcuts

７ Note

Some of these shortcuts require a "Precision Trackpad", such as the trackpad on

Surface devices and some other third-party laptops.

Trackpad options are configurable on both platforms.

ﾉ Expand table

Operation Mac Windows

Scroll Two finger vertical swipe Two finger vertical swipe

Zoom Two finger pinch in and Two finger pinch in and out
out

Swipe back and forward between Two finger sideways Two finger sideways swipe
views swipe

Switch virtual workspaces Four fingers sideways Four fingers sideways swipe
swipe

Display currently open apps Four fingers upward Three fingers upward swipe
swipe
 Operation Mac Windows

Switch between apps N/A Slow three finger sideways

swipe

Go to desktop Spread out four fingers Three finger swipe downwards

Open Cortana / Action center Two finger slide from Three finger tap
right

Open extra information Three finger tap N/A

Show launchpad / start an app Pinch with four fingers Tap with four fingers

Command-line shells and terminals

Windows supports several command-line shells and terminals which sometimes work a
little differently to the Mac's BASH shell and terminal emulator apps like Terminal and
iTerm.

Windows shells
Windows has two primary command-line shells:

1. PowerShell - PowerShell is a cross-platform task automation and configuration

management framework, consisting of a command-line shell and scripting
language built on .NET. Using PowerShell, administrators, developers, and power-
users can rapidly control and automate tasks that manage complex processes and
various aspects of the environment and operating system upon which it is run.
PowerShell is fully open-source , and because it is cross-platform, also available
for Mac and Linux.

Mac and Linux BASH shell users: PowerShell also supports many command-aliases
that you are already familiar with. For example:

List the contents of the current directory, using: ls

Move files with: mv
Move to a new directory with: cd <path>

Some commands and arguments are different in PowerShell vs. BASH. Learn more
by entering: get-help in PowerShell or checkout the compatibility aliases in the
docs.
 To run PowerShell as an Administrator, enter "PowerShell" in your Windows start
menu, then select "Run as Administrator."

2. Windows Command Line (Cmd): Windows still ships the traditional Command
Prompt (and Console – see below), providing compatibility with current and legacy
MS-DOS-compatible commands and batch files. Cmd is useful when running
existing/older batch files or command-line operations, but in general, users are
recommended to learn and use PowerShell since Cmd is now in maintenance, and
will not be receiving any improvements or new features in the future.

Linux shells
Windows Subsystem for Linux (WSL) can now be installed to support running a Linux
shell within Windows. This means that you can run bash, with whichever specific Linux
distribution you choose, integrated right inside Windows. Using WSL will provide the
kind of environment most familiar to Mac users. For example, you will ls to list the files
in a current directory, not dir as you would with the traditional Windows Cmd Shell. To
learn about installing and using WSL, see the Windows Subsystem for Linux Installation
Guide. Linux distributions that can be installed on Windows with WSL include:

1. Ubuntu 20.04 LTS

2. Kali Linux
3. Debian GNU/Linux
4. openSUSE Leap 15.1
5. SUSE Linux Enterprise Server 15 SP1

Just to name a few. Find more in the WSL install docs and install them directly from the
Microsoft Store .

Windows Terminals
In addition to many 3rd party offerings, Microsoft provides two "terminals" – GUI
applications that provide access to command-line shells and applications.

1. Windows Terminal: Windows Terminal is a new, modern, highly configurable

command-line terminal application that provides very high performance, low-
latency command-line user experience, multiple tabs, split window panes, custom
themes and styles, multiple "profiles" for different shells or command-line apps,
and considerable opportunities for you to configure and personalize many aspects
of your command-line user experience.
 You can use Windows Terminal to open tabs connected to PowerShell, WSL shells
(like Ubuntu or Debian), the traditional Windows Command Prompt, or any other
command-line app (e.g. SSH, Azure CLI, Git Bash).

2. Console: On Mac and Linux, users usually start their preferred terminal application
which then creates and connects to the user's default shell (e.g. BASH).

However, due to a quirk of history, Windows users traditionally start their shell, and
Windows automatically starts and connects a GUI Console app.

While one can still launch shells directly and use the legacy Windows Console, it's
highly recommended that users instead install and use Windows Terminal to
experience the best, fastest, most productive command-line experience.

Apps and utilities

ﾉ Expand table

App Mac Windows

Settings and Preferences System Preferences Settings

Task manager Activity Monitor Task Manager

Disk formatting Disk Utility Disk Management

Text editing TextEdit Notepad

Event viewing Console Event Viewer

Find files/apps Command+Space Windows key

Guide for changing your dev
environment from Mac to Windows
Article • 10/24/2022

The following tips and control equivalents should help you in your transition between a
Mac and Windows (or WSL/Linux) development environment.

For app development, the nearest equivalent to Xcode would be Visual Studio . There
is also a version of Visual Studio for Mac , if you ever feel the need to go back. For
cross-platform source code editing (and a huge number of plug-ins) Visual Studio
Code is the most popular choice.

Keyboard shortcuts

 Tip

You can use PowerToys Keyboard Manager to map Windows shortcuts to the
shortcuts you use on a Mac.

ﾉ Expand table

Operation Mac Windows

Copy Command+C Ctrl+C

Cut Command+X Ctrl+X

Paste Command+V Ctrl+V

Undo Command+Z Ctrl+Z

Save Command+S Ctrl+S

Open Command+O Ctrl+O

Lock computer Command+Control+Q WindowsKey+L

Show desktop Command+F3 WindowsKey+D

Open file browser Command+N WindowsKey+E

Minimize windows Command+M WindowsKey+M

Search Command+Space WindowsKey

Operation Mac Windows

Close active window Command+W Control+W

Switch current task Command+Tab Alt+Tab

Maximize a window to full screen Control+Command+F WindowsKey+Up

Save screen (Screenshot) Command+Shift+3 WindowsKey+Shift+S

Save window Command+Shift+4 WindowsKey+Shift+S

View item information or properties Command+I Alt+Enter

Select all items Command+A Ctrl+A

Select more than one item in a list Command, then click each Control, then click each
(noncontiguous) item item

Type special characters Option+ character key Alt+ character key

Trackpad shortcuts

７ Note

Some of these shortcuts require a "Precision Trackpad", such as the trackpad on

Surface devices and some other third-party laptops.

Trackpad options are configurable on both platforms.

ﾉ Expand table

Operation Mac Windows

Scroll Two finger vertical swipe Two finger vertical swipe

Zoom Two finger pinch in and Two finger pinch in and out
out

Swipe back and forward between Two finger sideways Two finger sideways swipe
views swipe

Switch virtual workspaces Four fingers sideways Four fingers sideways swipe
swipe

Display currently open apps Four fingers upward Three fingers upward swipe
swipe
 Operation Mac Windows

Switch between apps N/A Slow three finger sideways

swipe

Go to desktop Spread out four fingers Three finger swipe downwards

Open Cortana / Action center Two finger slide from Three finger tap
right

Open extra information Three finger tap N/A

Show launchpad / start an app Pinch with four fingers Tap with four fingers

Command-line shells and terminals

Windows supports several command-line shells and terminals which sometimes work a
little differently to the Mac's BASH shell and terminal emulator apps like Terminal and
iTerm.

Windows shells
Windows has two primary command-line shells:

1. PowerShell - PowerShell is a cross-platform task automation and configuration

management framework, consisting of a command-line shell and scripting
language built on .NET. Using PowerShell, administrators, developers, and power-
users can rapidly control and automate tasks that manage complex processes and
various aspects of the environment and operating system upon which it is run.
PowerShell is fully open-source , and because it is cross-platform, also available
for Mac and Linux.

Mac and Linux BASH shell users: PowerShell also supports many command-aliases
that you are already familiar with. For example:

List the contents of the current directory, using: ls

Move files with: mv
Move to a new directory with: cd <path>

Some commands and arguments are different in PowerShell vs. BASH. Learn more
by entering: get-help in PowerShell or checkout the compatibility aliases in the
docs.
 To run PowerShell as an Administrator, enter "PowerShell" in your Windows start
menu, then select "Run as Administrator."

2. Windows Command Line (Cmd): Windows still ships the traditional Command
Prompt (and Console – see below), providing compatibility with current and legacy
MS-DOS-compatible commands and batch files. Cmd is useful when running
existing/older batch files or command-line operations, but in general, users are
recommended to learn and use PowerShell since Cmd is now in maintenance, and
will not be receiving any improvements or new features in the future.

Linux shells
Windows Subsystem for Linux (WSL) can now be installed to support running a Linux
shell within Windows. This means that you can run bash, with whichever specific Linux
distribution you choose, integrated right inside Windows. Using WSL will provide the
kind of environment most familiar to Mac users. For example, you will ls to list the files
in a current directory, not dir as you would with the traditional Windows Cmd Shell. To
learn about installing and using WSL, see the Windows Subsystem for Linux Installation
Guide. Linux distributions that can be installed on Windows with WSL include:

1. Ubuntu 20.04 LTS

2. Kali Linux
3. Debian GNU/Linux
4. openSUSE Leap 15.1
5. SUSE Linux Enterprise Server 15 SP1

Just to name a few. Find more in the WSL install docs and install them directly from the
Microsoft Store .

Windows Terminals
In addition to many 3rd party offerings, Microsoft provides two "terminals" – GUI
applications that provide access to command-line shells and applications.

1. Windows Terminal: Windows Terminal is a new, modern, highly configurable

command-line terminal application that provides very high performance, low-
latency command-line user experience, multiple tabs, split window panes, custom
themes and styles, multiple "profiles" for different shells or command-line apps,
and considerable opportunities for you to configure and personalize many aspects
of your command-line user experience.
 You can use Windows Terminal to open tabs connected to PowerShell, WSL shells
(like Ubuntu or Debian), the traditional Windows Command Prompt, or any other
command-line app (e.g. SSH, Azure CLI, Git Bash).

2. Console: On Mac and Linux, users usually start their preferred terminal application
which then creates and connects to the user's default shell (e.g. BASH).

However, due to a quirk of history, Windows users traditionally start their shell, and
Windows automatically starts and connects a GUI Console app.

While one can still launch shells directly and use the legacy Windows Console, it's
highly recommended that users instead install and use Windows Terminal to
experience the best, fastest, most productive command-line experience.

Apps and utilities

ﾉ Expand table

App Mac Windows

Settings and Preferences System Preferences Settings

Task manager Activity Monitor Task Manager

Disk formatting Disk Utility Disk Management

Text editing TextEdit Notepad

Event viewing Console Event Viewer

Find files/apps Command+Space Windows key

Install JavaScript frameworks on
Windows
Article • 04/11/2022

This guide will help you get started using JavaScript frameworks on Windows, including
Node.js, React.js, Vue.js, Next.js, Nuxt.js, or Gatsby.

Choose a JavaScript framework to install and

set up your dev environment

Node.js overview
Learn about what you can do with Node.js and how to set up a Node.js development
environment.
Install on Windows
Install on WSL
Try a beginner-level tutorial

React overview
Learn about what you can do with React and how to set up a React development
environment.
Install on Windows for building web apps
Install on WSL for building web apps
 Install on Windows for building desktop apps
Install on Windows for building Android mobile apps
Try a beginner-level tutorial

Vue.js overview
Learn about what you can do with Vue.js and how to set up a Vue.js development
environment.
Install on Windows
Install on WSL
Try a beginner-level tutorial

Install Next.js on WSL

Next.js is a framework for creating server-rendered JavaScript apps based on React.js,
Node.js, Webpack and Babel.js. Learn how to install it on the Windows Subsystem for
Linux.

Install Nuxt.js on WSL

Nuxt.js is a framework for creating server-rendered JavaScript apps based on Vue.js,
Node.js, Webpack and Babel.js. Learn how to install it on the Windows Subsystem for
Linux.

Install Gatsby on WSL

Gatsby is a static site generator framework based on React.js. Learn how to install it on
the Windows Subsystem for Linux.
What is NodeJS?
Article • 03/01/2024

Node.js is an open-source, cross-platform, server-side JavaScript runtime environment

built on Chrome’s V8 JavaScript engine originally authored by Ryan Dahl and released in
2009.

Does Node.js work on Windows?

Yes. Windows supports two different environments for developing apps with Node.js:

Install a Node.js development environment on Windows

Install a Node.js development environment on Windows Subsystem for Linux

What can you do with NodeJS?

Node.js is primarily used for building fast and scalable web applications. It uses an
event-driven, non-blocking I/O model, making it lightweight and efficient. It's a great
framework for data-intensive real-time applications that run across distributed devices.
Here are a few examples of what you might create with Node.js.

Single-page apps (SPAs): These are web apps that work inside a browser and don't
need to reload a page every time you use it to get new data. Some example SPAs
include social networking apps, email or map apps, online text or drawing tools,
etc.
Real-time apps (RTAs): These are web apps that enable users to receive
information as soon as it's published by an author, rather than requiring that the
user (or software) check a source periodically for updates. Some example RTAs
include instant messaging apps or chat rooms, online multiplayer games that can
be played in the browser, online collaboration docs, community storage, video
conference apps, etc.
Data streaming apps: These are apps (or services) that send data/content as it
arrives (or is created) while keeping the connection open to continue downloading
further data, content, or components as needed. Some examples include video-
and audio-streaming apps.
REST APIs: These are interfaces that provide data for someone else's web app to
interact with. For example, a Calendar API service could provide dates and times
for a concert venue that could be used by someone else's local events website.
Server-side rendered apps (SSRs): These web apps can run on both the client (in
your browser / the front-end) and the server (the back-end) allowing pages that
 are dynamic to display (generate HTML for) whatever content is known and quickly
grab content that is not known as it's available. These are often referred to as
"isomorphic" or "universal" applications. SSRs utilize SPA methods in that they
don't need to reload every time you use it. SSRs, however, offer a few benefits that
may or may not be important to you, like making content on your site appear in
Google search results and providing a preview image when links to your app are
shared on social media like X or Facebook. The potential drawback being that they
require a Node.js server constantly running. In terms of examples, a social
networking app that supports events that users will want to appear in search
results and social media may benefit from SSR, while an email app may be fine as
an SPA. You can also run server-rendered no-SPA apps, which may be something
like a WordPress blog. As you can see, things can get complicated, you just need
to decide what's important.
Command line tools: These allow you to automate repetitive tasks and then
distribute your tool across the vast Node.js ecosystem. An example of a command
line tool is cURL, which stand for client URL and is used to download content from
an internet URL. cURL is often used to install things like Node.js or, in our case, a
Node.js version manager.
Hardware programming: While not quite as popular as web apps, Node.js is
growing in popularity for IoT uses, such as collecting data from sensors, beacons,
transmitters, motors, or anything that generates large amounts of data. Node.js
can enable data collection, analyzing that data, communicating back and forth
between a device and server, and taking action based on the analysis. NPM
contains more than 80 packages for Arduino controllers, raspberry pi, Intel IoT
Edison, various sensors, and Bluetooth devices.

Next steps
Install NodeJS on Windows
Install NodeJS on WSL
Build JavaScript applications with Node.js learning path

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
 Open a documentation issue
more information, see our  Provide product feedback
contributor guide.
Install Node.js on Windows Subsystem
for Linux (WSL2)
Article • 03/01/2024

If you prefer using Node.js in a Linux environment, find performance speed and system
call compatibility important, want to run Docker containers that leverage Linux
workspaces and avoid having to maintain both Linux and Windows build scripts, or just
prefer using a Bash command line, then you want to install Node.js on the Windows
Subsystem for Linux (more specifically, WSL 2).

Using Windows Subsystem for Linux (WSL), might also enable you to install your
preferred Linux distribution (Ubuntu is our default) so that you can have consistency
between your development environment (where you write code) and production
environment (the server where your code is deployed).

７ Note

If you are new to developing with Node.js and want to get up and running quickly
so that you can learn, install Node.js on Windows. This recommendation also
applies if you plan to use a Windows Server production environment.

Install WSL 2
WSL 2 is the most recent version available for Windows and we recommend it for
professional Node.js development workflows. To enable and install WSL 2, follow the
steps in the WSL install documentation. These steps will include choosing a Linux
distribution (for example, Ubuntu).

Once you have installed WSL 2 and a Linux distribution, open the Linux distribution (it
can be found in your Windows start menu) and check the version and codename using
the command: lsb_release -dc .

We recommend updating your Linux distribution regularly, including immediately after

you install, to ensure you have the most recent packages. Windows doesn't
automatically handle this update. To update your distribution, use the command: sudo
apt update && sudo apt upgrade .

Install Windows Terminal (optional)

Windows Terminal is an improved command line shell that allows you to run multiple
tabs so that you can quickly switch between Linux command lines, Windows Command
Prompt, PowerShell, Azure CLI, or whatever you prefer to use. You can also create
custom key bindings (shortcut keys for opening or closing tabs, copy+paste, etc.), use
the search feature, customize your terminal with themes (color schemes, font styles and
sizes, background image/blur/transparency), and more. Learn more in the Windows
Terminal docs.

Install Windows Terminal using the Microsoft Store : By installing via the store, updates
are handled automatically.

Install nvm, node.js, and npm

Besides choosing whether to install on Windows or WSL, there are additional choices to
make when installing Node.js. We recommend using a version manager as versions
change very quickly. You will likely need to switch between multiple versions of Node.js
based on the needs of different projects you're working on. Node Version Manager,
more commonly called nvm, is the most popular way to install multiple versions of
Node.js. We will walk through the steps to install nvm and then use it to install Node.js
and Node Package Manager (npm). There are alternative version managers to consider
as well covered in the next section.

） Important

It is always recommended to remove any existing installations of Node.js or npm

from your operating system before installing a version manager as the different
types of installation can lead to strange and confusing conflicts. For example, the
version of Node that can be installed with Ubuntu's apt-get command is currently
outdated. For help with removing previous installations, see How to remove nodejs
from ubuntu .)

For the most current information on installing NVM, see Installing and Updating in the
NVM repo on GitHub .

1. Open your Ubuntu command line (or distribution of your choice).

2. Install cURL (a tool used for downloading content from the internet in the
command-line) with: sudo apt-get install curl

3. Install nvm, with: curl -o- https://raw.githubusercontent.com/nvm-

sh/nvm/master/install.sh | bash
 ７ Note

Installing a newer version of NVM using cURL will replace the older one,
leaving the version of Node you've used NVM to install intact. For more
information, see the GitHub project page for the latest release information
on NVM .

4. To verify installation, enter: command -v nvm ...this should return 'nvm', if you receive
'command not found' or no response at all, close your current terminal, reopen it,
and try again. Learn more in the nvm github repo .

5. List which versions of Node are currently installed (should be none at this point):
nvm ls

6. Install both the current and stable LTS versions of Node.js. In a later step, you'll
learn how to switch between active versions of Node.js with an nvm command.

Install the current stable LTS release of Node.js (recommended for production
applications): nvm install --lts
Install the current release of Node.js (for testing latest Node.js features and
improvements, but more likely to have issues): nvm install node

7. List what versions of Node are installed: nvm ls ...now you should see the two
versions that you just installed listed.
 8. Verify that Node.js is installed and the currently default version with: node --
version . Then verify that you have npm as well, with: npm --version (You can also

use which node or which npm to see the path used for the default versions).

9. To change the version of Node.js you would like to use for a project, create a new
project directory mkdir NodeTest , and enter the directory cd NodeTest , then enter
nvm use node to switch to the Current version, or nvm use --lts to switch to the

LTS version. You can also use the specific number for any additional versions you've
installed, like nvm use v8.2.1 . (To list all of the versions of Node.js available, use
the command: nvm ls-remote ).

If you are using NVM to install Node.js and NPM, you should not need to use the SUDO
command to install new packages.

Alternative version managers

While nvm is currently the most popular version manager for node, there are a few
alternatives to consider:

n is a long-standing nvm alternative that accomplishes the same thing with

slightly different commands and is installed via npm rather than a bash script.
fnm is a newer version manager, claiming to be much faster than nvm . (It also
uses Azure Pipelines.)
Volta is a new version manager from the LinkedIn team that claims improved
speed and cross-platform support.
 asdf-vm is a single CLI for multiple languages, like ike gvm, nvm, rbenv & pyenv
(and more) all in one.
nvs (Node Version Switcher) is a cross-platform nvm alternative with the ability to
integrate with VS Code .

Install Visual Studio Code

We recommend using Visual Studio Code with the Remote-development extension
pack for Node.js projects. This splits VS Code into a “client-server” architecture, with
the client (the VS Code user interface) running on your Windows operating system and
the server (your code, Git, plugins, etc) running "remotely" on your WSL Linux
distribution.

７ Note

This “remote” scenario is a bit different than you may be accustomed to. WSL
supports an actual Linux distribution where your project code is running, separately
from your Windows operating system, but still on your local machine. The Remote-
WSL extension connects with your Linux subsystem as if it were a remote server,
though it’s not running in the cloud… it’s still running on your local machine in the
WSL environment that you enabled to run alongside Windows.

Linux-based Intellisense and linting is supported.

Your project will automatically build in Linux.
You can use all your extensions running on Linux (ES Lint, NPM Intellisense, ES6
snippets, etc. ).

Other code editors, like IntelliJ, Sublime Text, Brackets, etc. will also work with a WSL 2
Node.js development environment, but may not have the same sort of remote features
that VS Code offers. These code editors may run into trouble accessing the WSL shared
network location (\wsl$\Ubuntu\home) and will try to build your Linux files using
Windows tools, which likely not what you want. The Remote-WSL Extension in VS Code
handles this compatibility for you, with other IDEs you may need to set up an X server.
Support for running GUI apps in WSL (like a code editor IDE) is coming soon.

Terminal-based text editors (vim, emacs, nano) are also helpful for making quick
changes from right inside your console. The article, Emacs, Nano, or Vim: Choose your
Terminal-Based Text Editor Wisely does a nice job explaining some differences and a
bit about how to use each.

To install VS Code and the Remote-WSL Extension:

 1. Download and install VS Code for Windows . VS Code is also available for Linux,
but Windows Subsystem for Linux does not support GUI apps, so we need to
install it on Windows. Not to worry, you'll still be able to integrate with your Linux
command line and tools using the Remote - WSL Extension.

2. Install the Remote - WSL Extension on VS Code. This allows you to use WSL as
your integrated development environment and will handle compatibility and
pathing for you. Learn more .

） Important

If you already have VS Code installed, you need to ensure that you have the 1.35
May release or later in order to install the Remote - WSL Extension . We do not
recommend using WSL in VS Code without the Remote-WSL extension as you will
lose support for auto-complete, debugging, linting, etc. Fun fact: This WSL
extension is installed in $HOME/.vscode-server/extensions.

Helpful VS Code Extensions

While VS Code comes with many features for Node.js development out of the box, there
are some helpful extensions to consider installing available in the Node.js Extension
Pack . Install them all or pick and choose which seem the most useful to you.

To install the Node.js extension pack:

1. Open the Extensions window (Ctrl+Shift+X) in VS Code.

The Extensions window is now divided into three sections (because you installed
the Remote-WSL extension).

"Local - Installed": The extensions installed for use with your Windows
operating system.
"WSL:Ubuntu-18.04-Installed": The extensions installed for use with your
Ubuntu operating system (WSL).
"Recommended": Extensions recommended by VS Code based on the file
types in your current project.
 2. In the search box at the top of the Extensions window, enter: Node Extension Pack
(or the name of whatever extension you are looking for). The extension will be
installed for either your Local or WSL instances of VS Code depending on where
you have the current project opened. You can tell by selecting the remote link in
the bottom-left corner of your VS Code window (in green). It will either give you
the option to open or close a remote connection. Install your Node.js extensions in
the "WSL:Ubuntu-18.04" environment.

A few additional extensions you may want to consider include:

JavaScript Debugger : Once you finish developing on the server side with
Node.js, you'll need to develop and test the client side. This extension is a DAP-
based JavaScript debugger. It debugs Node.js, Chrome, Edge, WebView2, VS Code
extensions, and more.
 Keymaps from other editors : These extensions can help your environment feel
right at home if you're transitioning from another text editor (like Atom, Sublime,
Vim, eMacs, Notepad++, etc).
Settings Sync : Enables you to synchronize your VS Code settings across different
installations using GitHub. If you work on different machines, this helps keep your
environment consistent across them.

Set up Git (optional)

To set up Git for a Node.js project on WSL, see the article Get started using Git on
Windows Subsystem for Linux in the WSL documentation.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Install NodeJS on Windows
Article • 12/20/2023

If you are new to developing with Node.js and want to get up and running quickly so
that you can learn, follow the steps below to install Node.js directly on Windows.

７ Note

If you are using Node.js professionally, find performance speed and system call
compatibility important, want to run Docker containers that leverage Linux
workspaces and avoid having to maintain both Linux and Windows build scripts, or
just prefer using a Bash command line, then install Node.js on Windows
Subsystem for Linux (more specifically, WSL 2).

Install nvm-windows, node.js, and npm

Besides choosing whether to install on Windows or WSL, there are additional choices to
make when installing Node.js. We recommend using a version manager as versions
change very quickly. You will likely need to switch between multiple Node.js versions
based on the needs of different projects you're working on. Node Version Manager,
more commonly called nvm, is the most popular way to install multiple versions of
Node.js, but is only available for Mac/Linux and not supported on Windows. Instead, we
recommend installing nvm-windows and then using it to install Node.js and Node
Package Manager (npm). There are alternative version managers to consider as well
covered in the next section.

） Important

It is always recommended to remove any existing installations of Node.js or npm

from your operating system before installing a version manager as the different
types of installation can lead to strange and confusing conflicts. This includes
deleting any existing nodejs installation directories (e.g., "C:\Program Files\nodejs")
that might remain. NVM's generated symlink will not overwrite an existing (even
empty) installation directory. For help with removing previous installations, see
How to completely remove node.js from Windows .)

２ Warning
NVM is designed to be installed per-user, and invoked per-shell. It is not designed
for shared developer boxes or build servers with multiple build agents. NVM works
by using a symbolic link. Using nvm in shared scenarios creates a problem because
that link points to a user's app data folder -- so if user x runs nvm use lts , the link
will point node for the entire box to their app data folder. If user y runs node or
npm, they will be directed to run files under x's user account and in the case of npm
-g , they will be modifying x's files, which by default is not allowed. So nvm is only

prescribed for one developer box. This goes for build servers too. If two build
agents are on the same vm/box, they can compete and cause odd behavior in the
builds.

1. Follow the install instructions on the windows-nvm repository . We recommend

using the installer, but if you have a more advanced understanding of your needs,
you may want to consider the manual installation. The installer will point you to
the releases page for the most recent version.

2. Download the nvm-setup.zip file for the most recent release.

3. Once downloaded, open the zip file, then open the nvm-setup.exe file.

4. The Setup-NVM-for-Windows installation wizard will walk you through the setup
steps, including choosing the directory where both nvm-windows and Node.js will
be installed.
5. Once the installation is complete. Open PowerShell (recommend opening with
elevated Admin permissions) and try using windows-nvm to list which versions of
Node are currently installed (should be none at this point): nvm ls

6. Install the current release of Node.js (for testing the newest feature improvements,
but more likely to have issues than the LTS version): nvm install latest

7. Install the latest stable LTS release of Node.js (recommended) by first looking up
what the current LTS version number is with: nvm list available , then installing
the LTS version number with: nvm install <version> (replacing <version> with the
number, ie: nvm install 12.14.0 ).

8. List what versions of Node are installed: nvm ls ...now you should see the two
versions that you just installed listed.
 9. After installing the Node.js version numbers you need, select the version that you
would like to use by entering: nvm use <version> (replacing <version> with the
number, ie: nvm use 12.9.0 ).

10. To change the version of Node.js you would like to use for a project, create a new
project directory mkdir NodeTest , and enter the directory cd NodeTest , then enter
nvm use <version> replacing <version> with the version number you'd like to use

(ie v10.16.3`).

11. Verify which version of npm is installed with: npm --version , this version number
will automatically change to whichever npm version is associated with your current
version of Node.js.

Alternative version managers

While windows-nvm is currently the most popular version manager for node, there are
alternatives to consider:

nvs (Node Version Switcher) is a cross-platform nvm alternative with the ability to
integrate with VS Code .

Volta is a new version manager from the LinkedIn team that claims improved
speed and cross-platform support.

To install Volta as your version manager (rather than windows-nvm), go to the Windows
Installation section of their Getting Started guide , then download and run their
Windows installer, following the setup instructions.

） Important

You must ensure that Developer Mode is enabled on your Windows machine
before installing Volta.

To learn more about using Volta to install multiple versions of Node.js on Windows, see
the Volta Docs .
Install Visual Studio Code
We recommend you install Visual Studio Code for developing with Node.js on
Windows. For help, see Node.js tutorial in Visual Studio Code .

Alternative code editors

If you prefer to use a code editor or IDE other than Visual Studio Code, the following are
also good options for your Node.js development environment:

IntelliJ IDEA
Sublime Text
Atom
Brackets
Notepad++

Install Git
If you plan to collaborate with others, or host your project on an open-source site (like
GitHub), VS Code supports version control with Git . The Source Control tab in VS
Code tracks all of your changes and has common Git commands (add, commit, push,
pull) built right into the UI. You first need to install Git to power the Source Control
panel.

1. Download and install Git for Windows from the git-scm website .

2. An Install Wizard is included that will ask you a series of questions about settings
for your Git installation. We recommend using all of the default settings, unless
you have a specific reason for changing something.

3. If you've never worked with Git before, GitHub Guides can help you get started.

4. We recommend adding a .gitignore file to your Node projects. Here is GitHub's

default gitignore template for Node.js .

Use Windows Subsystem for Linux for

production
Using Node.js directly on Windows is great for learning and experimenting with what
you can do. Once you are ready to build production-ready web apps, which are typically
deployed to a Linux-based server, we recommend using Windows Subsystem for Linux
version 2 (WSL 2) for developing Node.js web apps. Many Node.js packages and
frameworks are created with a *nix environment in mind and most Node.js apps are
deployed on Linux, so developing on WSL ensures consistency between your
development and production environments. To set up a WSL dev environment, see Set
up your Node.js development environment with WSL 2.

７ Note

If you are in the (somewhat rare) situation of needing to host a Node.js app on a
Windows server, the most common scenario seems to be using a reverse proxy .
There are two ways to do this: 1) using iisnode or directly . We do not maintain
these resources and recommend using Linux servers to host your Node.js apps.
Tutorial: Node.js for Beginners
Article • 02/09/2022

If you're brand new to using Node.js, this guide will help you to get started with some
basics.

Try using Node.js in Visual Studio Code

Create your first Node.js web app using Express
Try using a Node.js module

Prerequisites
Installing on Node.js on Windows or on Windows Subsystem for Linux

Try NodeJS with Visual Studio Code

If you have not yet installed Visual Studio Code, return to the prerequisite section above
and follow the installation steps linked for Windows or WSL.

1. Open your command line and create a new directory: mkdir HelloNode , then enter
the directory: cd HelloNode

2. Create a JavaScript file named "app.js" with a variable named "msg" inside: echo
var msg > app.js

3. Open the directory and your app.js file in VS Code using the command: code .

4. Add a simple string variable ("Hello World"), then send the contents of the string
to your console by entering this in your "app.js" file:

JavaScript

var msg = 'Hello World';

console.log(msg);

5. To run your "app.js" file with Node.js. Open your terminal right inside VS Code by
selecting View > Terminal (or select Ctrl+`, using the backtick character). If you
need to change the default terminal, select the dropdown menu and choose Select
Default Shell.

6. In the terminal, enter: node app.js . You should see the output: "Hello World".
 ７ Note

Notice that when you type console in your 'app.js' file, VS Code displays supported
options related to the console object for you to choose from using IntelliSense.
Try experimenting with Intellisense using other JavaScript objects .

Create your first NodeJS web app using Express

Express is a minimal, flexible, and streamlined Node.js framework that makes it easier to
develop a web app that can handle multiple types of requests, like GET, PUT, POST, and
DELETE. Express comes with an application generator that will automatically create a file
architecture for your app.

To create a project with Express.js:

1. Open your command line (Command Prompt, Powershell, or whatever you prefer).

2. Create a new project folder: mkdir ExpressProjects and enter that directory: cd
ExpressProjects

3. Use Express to create a HelloWorld project template: npx express-generator

HelloWorld --view=pug

７ Note

We are using the npx command here to execute the Express.js Node package
without actually installing it (or by temporarily installing it depending on how
you want to think of it). If you try to use the express command or check the
version of Express installed using: express --version , you will receive a
response that Express cannot be found. If you want to globally install Express
to use over and over again, use: npm install -g express-generator . You can
view a list of the packages that have been installed by npm using npm list .
They'll be listed by depth (the number of nested directories deep). Packages
that you installed will be at depth 0. That package's dependencies will be at
depth 1, further dependencies at depth 2, and so on. To learn more, see
Difference between npx and npm? on StackOverflow.

4. Examine the files and folders that Express included by opening the project in VS
Code, with: code .
 The files that Express generates will create a web app that uses an architecture that
can appear a little overwhelming at first. You'll see in your VS Code Explorer
window (Ctrl+Shift+E to view) that the following files and folders have been
generated:

bin . Contains the executable file that starts your app. It fires up a server (on

port 3000 if no alternative is supplied) and sets up basic error handling.

public . Contains all the publicly accessed files, including JavaScript files, CSS

stylesheets, font files, images, and any other assets that people need when
they connect to your website.
routes . Contains all the route handlers for the application. Two files,

index.js and users.js , are automatically generated in this folder to serve as

examples of how to separate out your application’s route configuration.

views . Contains the files used by your template engine. Express is configured

to look here for a matching view when the render method is called. The
default template engine is Jade, but Jade has been deprecated in favor of
Pug, so we used the --view flag to change the view (template) engine. You
can see the --view flag options, and others, by using express --help .
app.js . The starting point of your app. It loads everything and begins serving

user requests. It's basically the glue that holds all the parts together.
package.json . Contains the project description, scripts manager, and app

manifest. Its main purpose is to track your app's dependencies and their
respective versions.

5. You now need to install the dependencies that Express uses in order to build and
run your HelloWorld Express app (the packages used for tasks like running the
server, as defined in the package.json file). Inside VS Code, open your terminal by
selecting View > Terminal (or select Ctrl+`, using the backtick character), be sure
that you're still in the 'HelloWorld' project directory. Install the Express package
dependencies with:

Bash

npm install

6. At this point you have the framework set up for a multiple-page web app that has
access to a large variety of APIs and HTTP utility methods and middleware, making
it easier to create a robust API. Start the Express app on a virtual server by
entering:

Bash
 npx cross-env DEBUG=HelloWorld:* npm start

 Tip

The DEBUG=myapp:* part of the command above means you are telling Node.js
that you want to turn on logging for debugging purposes. Remember to
replace 'myapp' with your app name. You can find your app name in the
package.json file under the "name" property. Using npx cross-env sets the

DEBUG environment variable in any terminal, but you can also set it with your

terminal specific way. The npm start command is telling npm to run the
scripts in your package.json file.

7. You can now view the running app by opening a web browser and going to:
localhost:3000

8. Now that your HelloWorld Express app is running locally in your browser, try
making a change by opening the 'views' folder in your project directory and
selecting the 'index.pug' file. Once open, change h1= title to h1= "Hello World!"
and selecting Save (Ctrl+S). View your change by refreshing the localhost:3000
URL on your web browser.

9. To stop running your Express app, in your terminal, enter: Ctrl+C

Try using a Node.js module

Node.js has tools to help you develop server-side web apps, some built in and many
more available via npm. These modules can help with many tasks:

ﾉ Expand table

Tool Used for

gm, sharp Image manipulation, including editing, resizing, compression, and so on,
directly in your JavaScript code

PDFKit PDF generation

validator.js String validation

imagemin, Minification
UglifyJS2

spritesmith Sprite sheet generation

winston Logging

commander.js Creating command-line applications

Let's use the built-in OS module to get some information about your computer's
operating system:

1. In your command line, open the Node.js CLI. You'll see the > prompt letting you
know you're using Node.js after entering: node

2. To identify the operating system you are currently using (which should return a
response letting you know that you're on Windows), enter: os.platform()

3. To check your CPU's architecture, enter: os.arch()

4. To view the CPUs available on your system, enter: os.cpus()

5. Leave the Node.js CLI by entering .exit or by selecting Ctrl+C twice.

 Tip

You can use the Node.js OS module to do things like check the platform and
return a platform-specific variable: Win32/.bat for Windows development,
darwin/.sh for Mac/unix, Linux, SunOS, and so on (for example, var isWin =
process.platform === "win32"; ).
６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
React overview
Article • 03/18/2024

What is React JS?

React is an open-source JavaScript library for building front end user interfaces. Unlike
other JavaScript libraries that provide a full application framework, React is focused
solely on creating application views through encapsulated units called components that
maintain state and generate UI elements. You can place an individual component on a
web page or nest hierarchies of components to create a complex UI.

React components are typically written in JavaScript and JSX (JavaScript XML) which is a
JavaScript extension that looks like a lot like HTML, but has some syntax features that
make it easier to do common tasks like registering event handlers for UI elements. A
React component implements the render method, which returns the JSX representing
the component's UI. In a web app, the JSX code returned by the component is
translated into browser-compliant HTML rendered in the browser.

Does React work on Windows?

Yes. Windows supports two different environments for developing React apps:

Install a React development environment on Windows

Install a React development environment on Windows Subsystem for Linux

What can you do with React?

Windows supports a wide range of scenarios for React developers, including:

Basic web apps: If you are new to React and primarily interested in learning about
building a basic web app with React, we recommend that you install create-react-
app directly on Windows. If you're planning to create a web app that will be
deployed for production, you may want to consider installing create-react-app on
Windows Subsystem for Linux (WSL), for better performance speed, system call
compatibility, and alignment between your local development environment and
deployment environment (which is often a Linux server).

Single-Page Apps (SPAs): These are websites that interact with the user by
dynamically rewriting the current web page with new data from a server, rather
than the browser default of loading entire new pages. If you want to build a static
 content-oriented SPA website, we recommend installing Gatsby on WSL. If you
want to build a server-rendered SPA website with a Node.js backend, we
recommend installing Next.js on WSL. (Though Next.js now also offers static file
serving ).

Native desktop apps: React Native for Windows + macOS enables you to build
native desktop applications with JavaScript that run across various types of
desktop PCs, laptops, tablets, Xbox, and Mixed Reality devices. It supports both the
Windows SDK and macOS SDK .

Native mobile apps: React Native is a cross-platform way to create Android and
iOS apps with JavaScript that render to native platform UI code. There are two
main ways to install React Native -- the Expo CLI and the React Native CLI. There's
a good comparison of the two on StackOverflow . Expo has a client app for iOS
and Android mobile devices for running and testing your apps. For instructions on
developing an Android app using Windows, React Native, and the Expo CLI see
React Native for Android development on Windows.

Installation options
There are several different ways to install React along with an integrated toolchain that
best works for your use-case scenario. Here are a few of the most popular.

Install React using Vite directly on Windows

Install React using Vite on Windows Subsystem for Linux (WSL)
Install the Next.js framework on WSL
Install the Gatsby framework on WSL
Install React Native for Windows desktop development
Install React Native for Android development on Windows
Install React Native for mobile development across platforms )
Install React in the browser with no toolchain : Since React is a JavaScript library
that is, in its most basic form, just a collection of text files, you can create React
apps without installing any tools or libraries on your computer. You may only want
to add a few "sprinkles of interactivity" to a web page and not need build tooling.
You can add a React component by just adding a plain <script> tag on an HTML
page. Follow the "Add React in One Minute" steps in the React docs.

React tools
While writing a simple React component in a plain text editor is a good introduction to
React, code generated this way is bulky, difficult to maintain and deploy, and slow. There
are some common tasks production apps will need to perform. These tasks are handled
by other JavaScript frameworks that are taken by the app as a dependency. These tasks
include:

Compilation - JSX is the language commonly used for React apps, but browsers
can't process this syntax directly. Instead, the code needs to be compiled into
standard JavaScript syntax and customized for different browsers. Babel is an
example of a compiler that supports JSX.
Bundling - Since performance is key for modern web apps, it's important that an
app's JavaScript includes only the needed code for the app and combined into as
few files as possible. A bundler, such as webpack performs this task for you.
Package management - Package managers make it easy to include the
functionality of third-party packages in your app, including updating them and
managing dependencies. Commonly used package managers include Yarn and
npm .

Together, the suite of frameworks that help you create, build, and deploy your app are
called a toolchain. An easy to setup development enviornment for react that uses this
toolchain is Vite which generates a simple one-page app for you. The only setup
required to use Vite is Node.js.

For Windows development, follow the instructions to install Node.js on WSL or

install Node.js on Windows.

React Native component directory

The components that can be used in a React Native app include the following:

Core components - Components that are developed and supported as part of the
React Native framework.
Community components - Components that are developed and maintained by the
community.
Native components - Components that you author yourself, using platform-native
code, and register to be accessible from React Native.

The React Native Directory provides a list of component libraries that can be filtered
by target platform.

Fullstack React toolchain options

React is a library, not a framework, so may require additional tools to create a more
complex app. In addition to using React, you may want to consider using:
 Package manager: Two popular package managers for React are npm (which is
included with NodeJS) and yarn . Both support a broad library of well-maintained
packages that can be installed.
React Router : a collection of navigational components that can help you with
things like bookmarkable URLs for your web app or a composable way to navigate
in React Native. React is really only concerned with state management and
rendering that state to the DOM, so creating React applications usually requires
the use of a routing library like React Router.
Redux : A predictable state container that helps with data-flow architecture. It is
likely not something you need until you get into more advanced React
development. To quote Dan Abramov, one of the creators of Redux: "Don't use
Redux until you have problems with vanilla React."
Webpack : A build tool that lets you compile JavaScript modules, also known as
module bundler. When webpack processes your application, it internally builds a
dependency graph which maps every module your project needs and generates
one or more bundles.
Uglify : A JavaScript parser, minifier, compressor and beautifier toolkit.
Babel : A JavaScript compiler mainly used to convert ECMAScript 2015+ code
into a backwards compatible version of JavaScript in current and older browsers or
environments. It can also be helpful to use babel-preset-env so that you don't
need to micromanage syntax transforms or browser polyfills and can define what
internet browsers to support.
ESLint : A tool for identifying and reporting on patterns found in your JavaScript
code that helps you make your code more consistent and avoid bugs.
Enzyme : A JavaScript testing utility for React that makes it easier to test your
React Components' output.
Jest : A testing framework built into the create-react-app package to help with
writing idiomatic JavaScript tests.
Mocha : A testing framework that runs on Node.js and in the browser to help
with asynchronous testing, reporting, and mapping uncaught exceptions to the
correct test cases.

React courses and tutorials

Here are a few recommended places to learn React and build sample apps:

The React learning path contains online course modules to help you get started
with the basics.
Build a single-page app (SPA) that runs in the browser (like this sample web app
that retrieves calendar info for a user with the Microsoft Graph API)
Build a server-rendered app with Next.js or a static-site-generated app with Gatsby
 Create a user interface (UI) for a native app that runs on Windows, Android, and
iOS devices (checkout these native Windows app samples or this sample
native app that retrieves calendar info for a user with the Microsoft Graph API)
Develop an app for Surface Duo dual-screen device
Create a web app or native app using Fluent UI React components
Build a React app with TypeScript

Additional resources
The official React docs offers all of the latest, up-to-date information on React
Microsoft Edge Add-ons for React Developer Tools : Adds two tabs to your
Microsoft Edge dev tools to help with your React development: Components and
Profiler.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Install React on Windows Subsystem for
Linux
Article • 03/18/2024

This guide will walk through installing React on a Linux distribution (ie. Ubuntu) running
on the Windows Subsystem for Linux (WSL) using the vite frontend tooling.

We recommend following these instructions if you are creating a single-page app (SPA)
that you would like to use Bash commands or tools with and/or plan to deploy to a
Linux server or use Docker containers. If you are brand new to React and just interested
in learning, you may want to consider installing with vite directly on Windows.

For more general information about React, deciding between React (web apps), React
Native (mobile apps), and React Native for Windows (desktop apps), see the React
overview.

Prerequisites
Install the latest version of Windows 10 (Version 1903+, Build 18362+) or Windows
11
Install Windows Subsystem for Linux (WSL), including a Linux distribution (like
Ubuntu) and make sure it is running in WSL 2 mode. You can check this by opening
PowerShell and entering: wsl -l -v
Install Node.js on WSL 2: These instructions use Node Version Manager (nvm) for
installation, you will need a recent version of NodeJS to run vite, as well as a recent
version of Node Package Manager (npm).

） Important

Installing a Linux distribution with WSL will create a directory for storing files:
\\wsl\Ubuntu-20.04 (substitute Ubuntu-20.04 with whatever Linux distribution

you're using). To open this directory in Windows File Explorer, open your WSL
command line, select your home directory using cd ~ , then enter the command
explorer.exe . Be careful not to install NodeJS or store files that you will be

working with on the mounted C drive ( /mnt/c/Users/yourname$ ). Doing so will

significantly slow down your install and build times.

Install React
To install the full React toolchain on WSL, we recommend using vite.

1. Open a WSL command line (ie. Ubuntu).

2. Create a new project folder: mkdir ReactProjects and enter that directory: cd
ReactProjects .

3. Install React using vite :

Bash

npm create vite@latest my-react-app -- --template react

4. Once installed, change directories into your new app ("my-react-app" or whatever
you've chosen to call it): cd my-react-app , install the dependencies: npm install
and then start your local development server: npm run dev

This command will start up the Node.js server and launch a new browser window
displaying your app. You can use Ctrl + c to stop running the React app in your
command line.

７ Note

Vite includes a frontend build pipeline using Babel , esbuild and Rollup , but
doesn't handle backend logic or databases. If you are seeking to build a server-
rendered website with React that uses a Node.js backend, we recommend installing
Next.js, rather than this Vite installation, which is intended more for single-page
apps(SPAs). You also may want to consider installing Gatsby if you want to build a
static content-oriented website.

6. When you're ready to deploy your web app to production, running npm run build
to create a build of your app in the "dist" folder. You can learn more in the
Deploying a Static Site .

Additional resources
React docs
Vite
Install Next.js
Install Gatsby
Install React Native for Windows
 Install NodeJS on Windows
Install NodeJS on WSL
Try the tutorial: Using React in Visual Studio Code
Try the React learning path

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Install React directly on Windows
Article • 03/18/2024

This guide will walk through installing React on a Linux distribution (ie. Ubuntu) running
on the Windows Subsystem for Linux (WSL) using the vite frontend tooling.

We recommend following these instructions if you are new to React and just interested
in learning. If you are creating a single-page app (SPA) that you would like to use Bash
commands or tools with and/or plan to deploy to a Linux server, we recommend that
you install with vite on Windows Subsystem for Linux (WSL).

For more general information about React, deciding between React (web apps), React
Native (mobile apps), and React Native for Windows (desktop apps), see the React
overview.

Create your React app

To install Create React App:

1. Open a terminal(Windows Command Prompt or PowerShell).

2. Create a new project folder: mkdir ReactProjects and enter that directory: cd
ReactProjects .

3. Install React using vite :

PowerShell

npm create vite@latest my-react-app -- --template react

4. Once installed, change directories into your new app ("my-react-app" or whatever
you've chosen to call it): cd my-react-app , install the dependencies: npm install
and then start your local development server: npm run dev

This command will start up the Node.js server and launch a new browser window
displaying your app. You can use Ctrl + c to stop running the React app in your
command line.

７ Note

Vite includes a frontend build pipeline using Babel , esbuild and Rollup , but
doesn't handle backend logic or databases. If you are seeking to build a server-
 rendered website with React that uses a Node.js backend, we recommend installing
Next.js, rather than this Vite installation, which is intended more for single-page
apps(SPAs). You also may want to consider installing Gatsby if you want to build a
static content-oriented website.

6. When you're ready to deploy your web app to production, running npm run build
to create a build of your app in the "dist" folder. You can learn more in the
Deploying a Static Site .

Additional resources
React docs
Vite
Install Next.js
Install Gatsby
Install React Native for Windows
Install NodeJS on Windows
Install NodeJS on WSL
Try the tutorial: Using React in Visual Studio Code
Try the React learning path

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Get started build a desktop app with
React Native for Windows
Article • 06/28/2023

React Native for Windows allows you to create a Universal Windows Platform (UWP)
app using React.

Overview of React Native

React Native is an open-source mobile application framework created by Facebook. It
is used to develop applications for Android, iOS, Web and UWP (Windows) providing
native UI controls and full access to the native platform. Working with React Native
requires an understanding of JavaScript fundamentals.

For more general information about React, see the React overview page.

Prerequisites
The setup requirements for using React Native for Windows can be found on the System
Requirements page. Ensure Developer Mode is turned ON in Windows Settings App.

Install React Native for Windows

You can create a Windows desktop app using React Native for Windows by following
these steps.

1. Open a command line window (terminal) and navigate to the directory where you
want to create your Windows desktop app project.

2. You can use this command with the Node Package Executor (NPX) to create a
React Native project without the need to install locally or globally install additional
tools. The command will generate a React Native app in the directory specified by
<projectName> .

PowerShell

npx react-native init <projectName>

 If you want to start a new project with a specific React Native version, you can use
the --version argument. For information about versions of React Native, see
Versions - React Native .

PowerShell

npx [email protected] init <projectName> --version X.XX.X

3. Switch to the project directory and run the following command to install the React
Native for Windows packages:

PowerShell

cd projectName
npx react-native-windows-init --overwrite

4. To run the app, first launch your web browser (ie. Microsoft Edge), then execute the
following command:

PowerShell

npx react-native run-windows

Debug your React Native desktop app using

Visual Studio
Install Visual Studio 2022 with the following options checked:
Workloads: Universal Windows Platform development & Desktop development
with C++.
Individual Components: Development activities & Node.js development
support.

Open the solution file in the application folder in Visual Studio (e.g.,
AwesomeProject/windows/AwesomeProject.sln if you used AwesomeProject as
<projectName>).

Select the Debug configuration and the x64 platform from the combo box controls
to the left of the Run button and underneath the Team and Tools menu item.

Run yarn start from your project directory, and wait for the React Native
packager to report success.
 Select Run to the right of the platform combo box control in VS, or select the
Debug->Start without Debugging menu item. You now see your new app and
Chrome should have loaded http://localhost:8081/debugger-ui/ in a new tab.

Select the F12 key or Ctrl+Shift+I to open Developer Tools in your web browser.

Debug your React Native desktop app using

Visual Studio Code
Install Visual Studio Code

Open your applications folder in VS Code.

Install the React Native Tools plugin for VS Code .

Create a new file in the applications root directory, .vscode/launch.json and paste
the following configuration:

JSON

{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Windows",
"cwd": "${workspaceFolder}",
"type": "reactnative",
"request": "launch",
"platform": "windows"
}
]
}

Press F5 or navigate to the debug menu (alternatively press Ctrl+Shift+D) and in

the Debug dropdown select "Debug Windows" and press the green arrow to run
the application.

Additional resources
React Native for Windows docs
React Native docs
React docs
Install NodeJS on Windows
Try the React learning path
６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Get started developing for Android
using React Native
Article • 06/28/2023

This guide will help you to get started using React Native on Windows to create a cross-
platform app that will work on Android devices.

Overview
React Native is an open-source mobile application framework created by Facebook. It
is used to develop applications for Android, iOS, Web and UWP (Windows) providing
native UI controls and full access to the native platform. Working with React Native
requires an understanding of JavaScript fundamentals.

Get started with React Native by installing

required tools
1. Install Visual Studio Code (or your code editor of choice).

2. Install Android Studio for Windows . Android Studio installs the latest Android
SDK by default. React Native requires Android 6.0 (Marshmallow) SDK or later. We
recommend using the latest SDK.

3. Create environment variable paths for the Java SDK and Android SDK:

In the Windows search menu, enter: "Edit the system environment variables",
this will open the System Properties window.
Choose Environment Variables... and then choose New... under User
variables.
Enter the Variable name and value (path). The default paths for the Java and
Android SDKs are as follows. If you've chosen a specific location to install the
Java and Android SDKs, be sure to update the variable paths accordingly.
JAVA_HOME: C:\Program Files\Android\Android Studio\jre\bin
ANDROID_HOME: C:\Users\username\AppData\Local\Android\Sdk
 4. Install NodeJS for Windows You may want to consider using Node Version
Manager (nvm) for Windows if you will be working with multiple projects and
version of NodeJS. We recommend installing the latest LTS version for new
projects.

７ Note

You may also want to consider installing and using the Windows Terminal for
working with your preferred command-line interface (CLI), as well as, Git for
version control . The Java JDK comes packaged with Android Studio v2.2+, but
if you need to update your JDK separately from Android Studio, use the Windows
x64 Installer .

Create a new project with React Native

1. Use npx , the package runner tool that is installed with npm to create a new
React Native project. from the Windows Command Prompt, PowerShell, Windows
Terminal , or the integrated terminal in VS Code (View > Integrated Terminal).

PowerShell

npx react-native init MyReactNativeApp

If you want to start a new project with a specific React Native version, you can use
the --version argument. For information about versions of React Native, see
Versions - React Native .
 PowerShell

npx [email protected] init <projectName> --version X.XX.X

2. Open your new "MyReactNativeApp" directory:

PowerShell

cd MyReactNativeApp

3. If you want to run your project on a hardware Android device, connect the device
to your computer with a USB cable.

4. If you want to run your project on an Android emulator, you shouldn't need to
take any action as Android Studio installs with a default emulator installed. If you
want to run your app on the emulator for a particular device. Click on the AVD
Manager button in the toolbar.

5. To run your project, enter the following command. This will open a new console
window displaying Node Metro Bundler.

PowerShell

npx react-native run-android

 ７ Note

If you are using a new install of Android Studio and haven't yet done any
other Android development, you may get errors at the command line when
you run the app about accepting licenses for the Android SDK. Such as
"Warning: License for package Android SDK Platform 29 not accepted." To

resolve this, you can click the SDK Manager button in Android Studio .
Or, you can list and accept the licenses with the following command, making
sure to use the path to the SDK location on your machine.

PowerShell

C:\Users\[User Name]\AppData\Local\Android\Sdk\tools\bin\sdkmanager --
licenses

6. To modify the app, open the MyReactNativeApp project directory in the IDE of your
choice. We recommend VS Code or Android Studio.
7. The project template created by react-native init uses a main page named
App.js . This page is pre-populated with a lot of useful links to information about
React Native development. Add some text to the first Text element, like the "HELLO
WORLD!" string shown below.

JavaScript

<Text style={styles.sectionDescription}>
Edit <Text style={styles.highlight}>App.js</Text> to change this
screen and then come back to see your edits. HELLO WORLD!
</Text>

8. Reload the app to show the changes you made. There are several ways to do this.

In the Metro Bundler console window, type "r".

In the Android device emulator, double tap "r" on your keyboard.
On a hardware android device, shake the device to bring up the React Native
debug menu and select `Reload'.
Additional resources
Develop Dual-screen apps for Android and get the Surface Duo device SDK

Add Windows Defender exclusions to improve performance

Enable Virtualization support to improve Emulator performance

Get started with Next.js on Windows
Article • 03/18/2024

A guide to help you install the Next.js web framework and get up and running on
Windows.

Next.js is a JavaScript framewpork tailored for building React-based web applications,

offering support for both static and server-side rendered web applicaions. Built with
best practices in mind, Next.js enables you to create "universal" web apps in a consistent
manner, requiring mininmal configuration. These "universal" server-rendered web apps,
also referred to as “isomorphic”, share code between the client and server. Next.js
enables developers to create fast, scalable, and SEO-friendly web applications with ease.

To learn more about React and other JavaScript frameworks based on React, see the
React overview page.

Prerequisites
This guide assumes that you've already completed the steps to set up your Node.js
development environment, including:

Install the latest version of Windows 10 (Version 1903+, Build 18362+) or Windows
11
Install Windows Subsystem for Linux (WSL), including a Linux distribution (like
Ubuntu) and make sure it is running in WSL 2 mode. You can check this by opening
PowerShell and entering: wsl -l -v
Install Node.js on WSL 2: This includes a version manager, package manager, Visual
Studio Code, and the Remote Development extension.

We recommend using the Windows Subsystem for Linux when working with NodeJS
apps for better performance speed, system call compatibility, and for parity when
running Linux servers or Docker containers.

） Important

Installing a Linux distribution with WSL will create a directory for storing files:
\\wsl\Ubuntu-20.04 (substitute Ubuntu-20.04 with whatever Linux distribution

you're using). To open this directory in Windows File Explorer, open your WSL
command line, select your home directory using cd ~ , then enter the command
explorer.exe . Be careful not to install NodeJS or store files that you will be
 working with on the mounted C drive ( /mnt/c/Users/yourname$ ). Doing so will
significantly slow down your install and build times.

Install Next.js
To install Next.js, which includes installing next, react, and react-dom:

1. Open a WSL command line (ie. Ubuntu).

2. Create a new project folder: mkdir NextProjects and enter that directory: cd
NextProjects .

3. Install Next.js and create a project (replacing 'my-next-app' with whatever you'd
like to call your app): npx create-next-app@latest my-next-app .

4. Once the package has been installed, change directories into your new app folder,
cd my-next-app , then use code . to open your Next.js project in VS Code. This will
allow you to look at the Next.js framework that has been created for your app.
Notice that VS Code opened your app in a WSL-Remote environment (as indicated
in the green tab on the bottom-left of your VS Code window). This means that
while you are using VS Code for editing on the Windows OS, it is still running your
app on the Linux OS.

5. There are 3 commands you need to know once Next.js is installed:

npm run dev to start Next.js in development mode.

npm run build to build the application for production usage.

npm start to start a Next.js production server.

Open the WSL terminal integrated in VS Code (View > Terminal). Make sure that
the terminal path is pointed to your project directory (ie. ~/NextProjects/my-next-
app$ ). Then try running a development instance of your new Next.js app using: npm

run dev

6. The local development server will start and once your project pages are done
building, your terminal will display

terminal
 - Local: http://localhost:3000
✔ Ready

Select this localhost link to open your new Next.js app in a web browser.

7. Open the app/page.tsx file in your VS Code editor. Find Get started by editing..
and replace everthing inside the <p> tag with This is my new Next.js app!the
page title . With your web browser still open to localhost:3000, save your change

and notice the hot-reloading feature automatically compile and update your
change in the browser.

You can use VS Code's debugger with your Next.js app by selecting the F5 key, or by
going to View > Debug (Ctrl+Shift+D) and View > Debug Console (Ctrl+Shift+Y) in the
menu bar. If you select the gear icon in the Debug window, a launch configuration
( launch.json ) file will be created for you to save debugging setup details. To learn more,
see VS Code Debugging .
To learn more about Next.js, see the Next.js docs .

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Get started with Gatsby.js on Windows
Article • 03/18/2024

A guide to help you install the Gatsby.js web framework and get up and running on
Windows.

Gatsby.js is a static site generator framework based on React.js, as opposed to being

server-rendered like Next.js. A static site generator generates static HTML on build time.
It doesn’t require a server. Next.js generates HTML on runtime (each time a new request
comes in), requiring a server to run. Gatsby also dictates how to handle data in your app
(with GraphQL), whereas Next.js leaves that decision up to you.

To learn more about React and other JavaScript frameworks based on React, see the
React overview page.

Prerequisites
This guide assumes that you've already completed the steps to set up your Node.js
development environment, including:

Install the latest version of Windows 10 (Version 1903+, Build 18362+) or Windows
11
Install Windows Subsystem for Linux (WSL), including a Linux distribution (like
Ubuntu) and make sure it is running in WSL 2 mode. You can check this by opening
PowerShell and entering: wsl -l -v
Install Node.js on WSL 2: This includes a version manager, package manager, Visual
Studio Code, and the Remote Development extension.

We recommend using the Windows Subsystem for Linux when working with NodeJS
apps for better performance speed, system call compatibility, and for parody when
running Linux servers or Docker containers.

） Important

Installing a Linux distribution with WSL will create a directory for storing files:
\\wsl\Ubuntu-20.04 (substitute Ubuntu-20.04 with whatever Linux distribution
you're using). To open this directory in Windows File Explorer, open your WSL
command line, select your home directory using cd ~ , then enter the command
explorer.exe . Be careful not to install NodeJS or store files that you will be
 working with on the mounted C drive ( /mnt/c/Users/yourname$ ). Doing so will
significantly slow down your install and build times.

Install Gatsby.js
To create a Gatsby.js project:

1. Open your WSL terminal (ie. Ubuntu).

2. Create a new project folder: mkdir GatsbyProjects and enter that directory: cd
GatsbyProjects

3. Use npm to install the Gatsby CLI: npm install -g gatsby-cli . Once installed,
check the version with gatsby --version .

4. Create your Gatsby.js project: gatsby new my-gatsby-app

5. Once the package has been installed, change directories into your new app folder,
cd my-gatsby-app , then use code . to open your Gatsby project in VS Code. This

will allow you to look at the Gatsby.js framework that has been created for your
app using VS Code's File Explorer. Notice that VS Code opened your app in a WSL-
Remote environment (as indicated in the green tab on the bottom-left of your VS
Code window). This means that while you are using VS Code for editing on the
Windows OS, it is still running your app on the Linux OS.

6. There are 3 commands you need to know once Gatsby is installed:

gatsby develop for running a development instance with hot-reloading.

gatsby build for creating a production build.

gatsby serve for starting your app in production mode.

Open the WSL terminal integrated in VS Code (View > Terminal). Make sure that
the terminal path is pointed to your project directory (ie. ~/GatsbyProjects/my-
gatsby-app$ ). Then try running a development instance of your new app using:
gatsby develop

7. Once your new Gatsby project finishes compiling, your terminal will display. You
can now view gatsby-starter-default in the browser. http://localhost:8000/ .
 Select this localhost link to view your new project built in a web browser.

７ Note

You'll notice that your terminal output also let's you know that you can "View
GraphiQL, an in-browser IDE, to explore your site's data and schema:
http://localhost:8000/___graphql ." GraphQL consolidates your APIs into a self-

documenting IDE (GraphiQL) built into Gatsby. In addition to exploring your site's
data and schema, you can perform GraphQL operations such as queries, mutations,
and subscriptions. For more info, see Introducing GraphiQL .

8. Open the src/pages/index.js file in your VS Code editor. Find the page title
<h1>Welcome to <b>Gatsby!</b></h1> and change it to <h1>Hello <b>World!</b>

</h1> . With your web browser still open to http://localhost:8000 , save your

change and notice the hot-reloading feature automatically compile and update
your change in the browser.
You can use VS Code's debugger with your Gatsby app by selecting the F5 key, or by
going to View > Debug (Ctrl+Shift+D) and View > Debug Console (Ctrl+Shift+Y) in the
menu bar. If you select the gear icon in the Debug window, a launch configuration
( launch.json ) file will be created for you to save debugging setup details. To learn more,
see VS Code Debugging .

To learn more about Gatsby, see the Gatsby.js docs .

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Tutorial: React on Windows for
beginners
Article • 03/18/2024

If you're brand new to using React, this guide will help you to get started with some
basics.

A few basic terms and concepts

Try using React in Visual Studio Code
Try using React with an API

Prerequisites
Install React on Windows
Install React on Windows Subsystem for Linux
Install VS Code . We recommend installing VS Code on Windows, regardless of
whether you plan to use React on Windows or WSL.

A few basic terms and concepts

React is a JavaScript library for building user interfaces.

It is open-source , meaning that you can contribute to it by filing issues or pull

requests. (Just like these docs!)

It is declarative , meaning that you write the code that you want and React takes
that declared code and performs all of the JavaScript/DOM steps to get the
desired result.

It is component-based , meaning that applications are created using

prefabricated and reusable independent code modules that manage their own
state and can be glued together using the React framework, making it possible to
pass data through your app while keeping state out of the DOM.

The React motto is "Learn once, write anywhere." The intention is for code reuse
and not making assumptions about how you will use React UI with other
technologies, but to make components reusable without the need to rewrite
existing code.
 JSX is a syntax extension for JavaScript written to be used with React that looks
like HTML, but is actually a JavaScript file that needs to be compiled, or translated
into regular JavaScript.

Virtual DOM : DOM stands for Document Object Model and represents the UI
of your app. Every time the state of your app's UI changes, the DOM gets updated
to represent the change. When a DOM is frequently updating, performance
becomes slow. A Virtual DOM is only a visual representation of the DOM, so when
the state of the app changes, the virtual DOM is updated rather than the real
DOM, reducing the performance cost. It's a representation of a DOM object, like a
lightweight copy.

Views: are what the user sees rendered in the browser. In React, view is related to
the concept of rendering elements that you want a user to see on their screen.

State : refers to the data stored by different views. The state will typically rely on
who the user is and what the user is doing. For example, signing into a website
may show your user profile (view) with your name (state). The state data will
change based on the user, but the view will remain the same. State is used to
achieve most of the user interactivity with the application.

Component Props : is a way for parent component to pass some information as a

value or data(including objects, arrays, and functions) to its child components.
Props are read-only and cannot be updated by the child component.

Try using React in Visual Studio Code

There are many ways to create an application with React (see the React Overview for
examples). This tutorial will walk through how to use vite to fast-forward the set up for
a functioning React app so that you can see it running and focus on experimenting with
the code, not yet concerning yourself with the build tools.

1. Use vite on Windows or WSL (see the prerequisites above) to create a new project:
npm create vite@latest hello-world -- --template react

2. Change directories so that you're inside the folder for your new app: cd hello-
world , install the dependencies: npm install and then start your local

development server: npm run dev

Your new React Hello World app will compile and open your default web browser
to show that it's running on http://localhost:5173 .
 3. Stop running your React app (Ctrl+c) and open it's code files in VS Code by
entering: code .

4. Find the src/App.jsx file and find the header section that reads:

JavaScript

<p>Edit <code>src/App.jsx</code> and save to test HMR</p>

Change it to read:

JavaScript

<p>Hello World! This is my first React app.</p>

5. Open your terminal window and start your local development server: npm run dev
or you can use the integrated VS Code terminal (Ctrl + `) and start your
development server from there.

Throughout the development of your React app you can keep your local development
server running and all the changes will immediately be rendered at
http://localhost:5173 in your browser.

Application file structure

The intial file structure looks like

markdown

hello-world
├── node_modules
├── README.md
├── index.html
├── package-lock.json
├── package.json
├── public
│ └── vite.svg
├── src
│ ├── App.css
│ ├── App.jsx
│ ├── assets
│ │ └── react.svg
│ ├── index.css
│ └── main.jsx
└── vite.config.js

For starters, these are the important files and folders you need to know.

index.html is the file in which Vite injects your code from src folder for your browser to

run it. This file should not be edited except to change the title of your React application.

The src folder is where the source code of your React application lives. This is the place
where you create your custom components, CSS files and other code files you need to
build your application. These files are processed by Vite's build tools to parse and build
them to create your final React project.

The public folder contains all your static files that will be served directly to your
browser. These files are not processed by Vite.

Try using React with an API

Using the same Hello World! app that you built with React and updated with Visual
Studio Code, let's try adding an API call to display some data.

1. Lets start fresh. We will remove almost all the boilerplate code provided by Vite
and keep only our code from the previous step.

Your App.jsx file should now look like this:

JavaScript
 import "./App.css";

function App() {
return (
<>
<p>Hello world! This is my first React app.</p>
</>
);
}

export default App;

2. Next, let's set a local state where we can save data from an API. A state is where we
can store data to be used in the view.

To add a local state, we need to first import the useState React Hook that lets
you add state variable to your component.

We also need to initialize the local state. The useState returns an array of two
values; current state and a set function. We will call our current state as posts
initialised as an empty array that we can fill with post data later from our API using
the setPosts function.

Your App.jsx file should now look like this:

JavaScript
 import { useState } from "react";
import "./App.css";

function App() {
const [posts, setPosts] = useState([]);

return (
<>
<p>Hello world! This is my first React app.</p>
</>
);
}

export default App;

3. To call an API with data for us to use in our React app, we will use the .fetch
JavaScript method. The API we will call is JSONPlaceholder , a free API for testing
and prototyping that serves up fake placeholder data in JSON format.

We use the useEffect React Hook to update the posts state by using the set
function .

Javascript

import { useState, useEffect } from "react";

import "./App.css";

function App() {
const [posts, setPosts] = useState([]);

useEffect(() => {
const url = "https://jsonplaceholder.typicode.com/albums/1/photos";
fetch(url)
.then((response) => response.json())
.then((data) => setPosts(data));
}, []);

return (
<>
<p>Hello world! This is my first React app.</p>
</>
);
}

export default App;

4. Let's take a look at what sort of data the API has saved in our posts state. Below is
some of the contents of the fake JSON API file . We can see the format the data is
listed in, using the categories: "albumId", "id", "title", "url", and "thumbnailUrl".
 JSON

[
{
"albumId": 1,
"id": 1,
"title": "accusamus beatae ad facilis cum similique qui sunt",
"url": "https://via.placeholder.com/600/92c952",
"thumbnailUrl": "https://via.placeholder.com/150/92c952"
},
{
"albumId": 1,
"id": 2,
"title": "reprehenderit est deserunt velit ipsam",
"url": "https://via.placeholder.com/600/771796",
"thumbnailUrl": "https://via.placeholder.com/150/771796"
}
]

5. To display the API data, we will now need to add a bit of JSX code inside the
rendered return() statement. We will use the map() method to display our data
from the posts object that we stored it in as keys. Each post will display a header
with "ID #" and then the post.id key value + post.title key value from our JSON
data. Followed by the body displaying the image based on the thumbnailUrl key
value.

JavaScript

// rest of the code

return (
<article>
<h1>Posts from our API call</h1>
{posts.map((post) => (
<article key={post.id}>
<h2>ID #{post.id} {post.title}</h2>
<img src={post.thumbnailUrl} />
</article>
))}
</article>
);
}

export default App;

Additional resources
The official React docs offer all of the latest, up-to-date information on React
Microsoft Edge Add-ons for React Developer Tools : Adds two tabs to your
Microsoft Edge dev tools to help with your React development: Components and
Profiler.
The React learning path contains online course modules to help you get started
with the basics.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
What is Vue.js?
Article • 03/01/2024

Vue is an open-source, front end JavaScript framework for building user interfaces and
single-page applications on the web. Created by Evan You, released in 2014 and
maintained by Evan and his core team, Vue focuses on declarative rendering and
component composition offering a core library for the view layer only.

If you want to build a server-rendered Vue web app with advanced features such as
routing, state management and build tooling, take a look at Nuxt.js.

What makes Vue unique?

Vue uses a model-view-viewmodel architecture. Evan You previously worked on
AngularJS at Google and extracted parts of Angular to offer a more lightweight
framework. Vue is in may ways similar to React, Angular, Ember, Knockout, etc. See the
Vue documentation for a more in-depth comparison to these other JavaScript
frameworks.

What can you do with Vue?

Build a single-page app (SPA)
Use just a component of Vue to add a simple to-do list to your app or find more
complex examples
Build a server-rendered website with a Node.js backend, with help from Nuxt.js

Vue tools
Vue.js is focused only on the view layer, so may require additional tools to create a more
complex app. You may want to consider using:

Package manager: Two popular package managers for Vue are npm (which is
included with NodeJS) and yarn . Both support a broad library of well-maintained
packages that can be installed.
Vue CLI : a standard toolkit for rapid Vue.js development with out-of-the-box
support for Babel, PostCSS, TypeScript, ESLint, etc.
Nuxt.js: A framework to make server-side rendered Vue.js apps possible. Server-
side rendering can improve SEO and make user interfaces more responsive.
 Vue extension pack for VS Code : Adds syntax highlighting, code formatting, and
code snippets to your .vue files.
Vuetify : A Vue UI library offering Material Design Framework components.
Vuesion : A Vue boilerplate for production-ready Progressive Web Apps (PWAs).
Storybook : A development and testing environment for Vue user interface
components.
Vue Router : Supports mapping application URLs to Vue components.
Vue Design System : An open source tool for building Design Systems with
Vue.js.
VueX : State management system for Vue apps.

Additional resources
Vue docs
Vue.js overview
Install Vue.js on WSL
Install Vue.js on Windows
Install Nuxt.js
Take your first steps with Vue.js learning path
Try a Vue tutorial with VS Code

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Install Vue.js on Windows Subsystem for
Linux
Article • 03/08/2024

A guide to help you set up a Vue.js development environment on Windows by installing

the Vue.js web framework on Windows Subsystem for Linux (WSL). Learn more on the
Vue.js overview page.

Vue can be installed directly on Windows or on WSL. We generally recommend installing

on WSL if you are planning to interact with a NodeJS backend, want parity with a Linux
production server, or plan to follow along with a tutorial that utilizes Bash commands.
You may also want to consider Vite as an alternative to Vue.js.

Prerequisites
Install Windows Subsystem for Linux (WSL), including a Linux distribution (like
Ubuntu) and make sure it is running in WSL 2 mode. You can check this by opening
PowerShell and entering: wsl -l -v
Install Node.js on WSL 2: This includes a version manager, package manager, Visual
Studio Code, and the Remote Development extension. The Node Package Manager
(npm) is used to install Vue.js.

） Important

Installing a Linux distribution with WSL will create a directory for storing files:
\\wsl\Ubuntu-20.04 (substitute Ubuntu-20.04 with whatever Linux distribution

you're using). To open this directory in Windows File Explorer, open your WSL
command line, select your home directory using cd ~ , then enter the command
explorer.exe . Be careful not to install or store files that you will be working with

on the mounted C drive ( /mnt/c/Users/yourname$ ). Doing so will significantly slow

down your install and build times.

Install Vue.js
To install Vue.js on WSL:

1. Open a WSL command line (ie. Ubuntu).

 2. Create a new project folder: mkdir VueProjects and enter that directory: cd
VueProjects .

3. Install Vue.js using Node Package Manager (npm):

Bash

npm install vue

Check the version number you have installed by using the command: vue --version .

７ Note

To install Vue.js using a CDN, rather than NPM, see the Vue.js install docs .

Install Vue CLI

Vue CLI is a toolkit for working with Vue in your terminal / command line. It enables you
to quickly scaffold a new project (vue create), prototype new ideas (vue serve), or
manage projects using a graphical user interface (vue ui). Vue CLI is a globally installed
npm package that handles some of the build complexities (like using Babel or Webpack)
for you. If you are not building a new single-page app, you may not need or want Vue CLI.

To install Vue CLI, use npm. You must use the -g flag to globally install in order to
upgrade ( vue upgrade --next ):

Bash

npm install -g @vue/cli

To learn more about additional plugins that can be added (such as linting or Apollo for
integrating GraphQL), visit Vue CLI plugins in the Vue CLI docs.

Additional resources
Vue docs
Vue.js overview
Install Vue.js on Windows
Install Nuxt.js
Microsoft Learn online course: Take your first steps with Vue.js
 Try a Vue tutorial with VS Code

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Install Vue.js directly on Windows
Article • 03/08/2024

A guide to help you set up a Vue.js development environment on Windows. Learn more
on the Vue.js overview page.

Vue can be installed directly on Windows or on the Windows Subsystem for Linux (WSL).
We generally recommend that you install Vue on WSL if you are planning to interact
with a NodeJS backend, want parity with a Linux production server, or plan to follow
along with a tutorial that utilizes Bash commands. You may also want to consider Vite
as an alternative to Vue.js.

Prerequisites
Install Node.js on Windows: This includes a version manager, package manager,
and Visual Studio Code. The Node Package Manager (npm) is used to install Vue.js.

Install Vue.js
To install Vue.js:

1. Open a command line (ie. Windows Command Prompt or PowerShell).

2. Create a new project folder: mkdir VueProjects and enter that directory: cd
VueProjects .

3. Install Vue.js using Node Package Manager (npm):

PowerShell

npm install vue

Check the version number you have installed by using the command: vue --version .

７ Note

To install Vue.js using a CDN, rather than NPM, see the Vue.js install docs . See
the Vue docs for an Explanation of different Vue builds .
Install Vue CLI
Vue CLI is a toolkit for working with Vue in your terminal / command line. It enables you
to quickly scaffold a new project (vue create), prototype new ideas (vue serve), or
manage projects using a graphical user interface (vue ui). Vue CLI is a globally installed
npm package that handles some of the build complexities (like using Babel or Webpack)
for you. If you are not building a new single-page app, you may not need or want Vue CLI.

To install Vue CLI, use npm. You must use the -g flag to globally install in order to
upgrade ( vue upgrade --next ):

PowerShell

npm install -g @vue/cli

To learn more about additional plugins that can be added (such as linting or Apollo for
integrating GraphQL), visit Vue CLI plugins in the Vue CLI docs.

Additional resources
Vue docs
Vue.js overview
Install Vue.js on WSL
Install Nuxt.js
Take your first steps with Vue.js learning path
Try a Vue tutorial with VS Code

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Get started with Nuxt.js on Windows
Article • 11/01/2023

A guide to help you install the Nuxt.js web framework and get up and running on
Windows.

Nuxt.js is a framework for creating server-rendered JavaScript apps based on Vue.js,

Node.js, Webpack and Babel.js. It was inspired by Next.js. It is basically a project
boilerplate for Vue. Just like Next.js, it is crafted with attention to best practices and
allows you to create "universal" web apps in a simple, consistent way, with hardly any
configuration. These "universal" server-rendered web apps are also sometimes called
“isomorphic”, meaning that code is shared between the client and server.

To learn more about Vue, see the Vue overview page.

Prerequisites
This guide assumes that you've already completed the steps to set up your Node.js
development environment, including:

Install Windows Subsystem for Linux (WSL), including a Linux distribution (like
Ubuntu) and make sure it is running in WSL 2 mode. You can check this by opening
PowerShell and entering: wsl -l -v
Install Node.js on WSL 2: This includes a version manager, package manager, Visual
Studio Code, and the Remote Development extension.

We recommend using the Windows Subsystem for Linux when working with NodeJS
apps for better performance speed, system call compatibility, and for parody when
running Linux servers or Docker containers.

） Important

Installing a Linux distribution with WSL will create a directory for storing files:
\\wsl\Ubuntu-20.04 (substitute Ubuntu-20.04 with whatever Linux distribution

you're using). To open this directory in Windows File Explorer, open your WSL
command line, select your home directory using cd ~ , then enter the command
explorer.exe . Be careful not to install NodeJS or store files that you will be

working with on the mounted C drive ( /mnt/c/Users/yourname$ ). Doing so will

significantly slow down your install and build times.
Install Nuxt.js
To install Nuxt.js, you will need to answer a series of questions about what sort of
integrated server-side framework, UI framework, testing framework, mode, modules,
and linter you would like to install:

1. Open a WSL command line (ie. Ubuntu).

2. Create a new project folder: mkdir NuxtProjects and enter that directory: cd
NuxtProjects .

3. Install Nuxt.js and create a project (replacing 'my-nuxt-app' with whatever you'd
like to call your app): npm create nuxt-app my-nuxt-app

4. The Nuxt.js installer will now ask you the following questions:

Project Name: my-nuxtjs-app

Project description: Description of my Nuxt.js app.
Author name: I use my GitHub alias.
Choose the package manager: Yarn or Npm - we use NPM for our examples.
Choose UI framework: None, Ant Design Vue, Bootstrap Vue, etc. Let's choose
Vuetify for this example, but the Vue Community created a nice summary
comparing these UI frameworks to help you choose the best fit for your
project.
Choose custom server frameworks: None, AdonisJs, Express, Fastify, etc. Let's
choose None for this example, but you can find a 2019-2020 server
framework comparison on the Dev.to site.
Choose Nuxt.js modules (use spacebar to select modules or just enter if you
don't want any): Axios (for simplifying HTTP requests) or PWA support (for
adding a service-worker, manifest.json file, etc). Let's not add a module for
this example.
Choose linting tools: ESLint, Prettier, Lint staged files. Let's choose ESLint (a
tool for analyzing your code and warning you of potential errors).
Choose a test framework: None, Jest, AVA. Let's choose None as we won't
cover testing in this quickstart.
Choose rendering mode: Universal (SSR) or Single Page App (SPA). Let's
choose Universal (SSR) for our example, but the Nuxt.js docs point out
some of the differences -- SSR requiring a Node.js server running to server-
render your app and SPA for static hosting.
Choose development tools: jsconfig.json (recommended for VS Code so
Intellisense code completion works)
5. Once your project is created, cd my-nuxtjs-app to enter your Nuxt.js project
directory, then enter code . to open the project in the VS Code WSL-Remote
environment.

6. There are 3 commands you need to know once Nuxt.js is installed:

npm run dev for running a development instance with hot-reloading, file

watching and task re-running.

npm run build for compiling your project.
npm start for starting your app in production mode.

Open the WSL terminal integrated in VS Code (View > Terminal). Make sure that
the terminal path is pointed to your project directory (ie. ~/NuxtProjects/my-nuxt-
app$ ). Then try running a development instance of your new Nuxt.js app using: npm

run dev

7. The local development server will start (displaying some kind of cool progress bars
for the client and server compiles). Once your project is done building, your
terminal will display "Compiled successfully" along with how much time it took to
compile. Point your web browser to http://localhost:3000 to open your new
Nuxt.js app.

8. Open the pages/index.vue file in your VS Code editor. Find the page title <v-card-
title class="headline">Welcome to the Vuetify + Nuxt.js template</v-card-
 title> and change it to <v-card-title class="headline">This is my new Nuxt.js
app!</v-card-title> . With your web browser still open to localhost:3000, save your

change and notice the hot-reloading feature automatically compile and update
your change in the browser.

9. Let's see how Nuxt.js handles errors. Remove the </v-card-title> closing tag so
that your title code now looks like this: <v-card-title class="headline">This is my
new Nuxt.js app! . Save this change and notice that a compiling error will display in

your browser, and in your terminal, letting your know that a closing tag for <v-
card-title> is missing, along with the line numbers where the error can be found

in your code. Replace the </v-card-title> closing tag, save, and the page will
reload.

You can use VS Code's debugger with your Nuxt.js app by selecting the F5 key, or by
going to View > Debug (Ctrl+Shift+D) and View > Debug Console (Ctrl+Shift+Y) in the
menu bar. If you select the gear icon in the Debug window, a launch configuration
( launch.json ) file will be created for you to save debugging setup details. To learn more,
see VS Code Debugging .

To learn more about Nuxt.js, see the Nuxt.js guide .

Tutorial: Vue.js for Beginners
Article • 03/01/2024

If you're brand new to using Vue.js, this guide will help you to get started with some
basics.

Try the Vue.js HelloWorld code sandbox

Try using Node.js in Visual Studio Code

Prerequisites
You must first install Vue.js on Windows or on Windows Subsystem for Linux.

Try NodeJS with Visual Studio Code

If you don't already have it, install VS Code . We recommend installing VS Code on
Windows, regardless of whether you plan to use Vue on Windows or WSL.

1. Open your command line and create a new directory: mkdir HelloVue , then enter
the directory: cd HelloVue

2. Install the Vue CLI: npm install -g @vue/cli

3. Create your Vue app: vue create hello-vue-app

You'll need to choose whether to use Vue 2 or Vue 3 Preview , or manually select
the features you want.

4. Open the directory of your new hello-vue-app: cd hello-vue-app

5. Try running you new Vue app in your web browser: npm run serve

You should see "Welcome to your Vue.js App" on http://localhost:8080 in your

browser. You can press Ctrl+C to stop the vue-cli-service server.
 ７ Note

If using WSL (with Ubuntu or your favorite Linux distribution) for this tutorial,
you'll need to make sure that you have the Remote - WSL Extension
installed for the best experience running and editing your code with VS
remote server.

6. Try updating the welcome message by opening your Vue app's source code in VS
Code, enter: code .

7. VS Code will launch and display your Vue application in the File Explorer. Run your
app in the terminal again with npm run serve and have your web browser open to
the localhost so that you can see the Vue page welcome page displayed. Find the
App.vue file in VS Code. Try changing "Welcome to your Vue.js App" to "Welcome

to the Jungle!". You will see your Vue app "hot reload" as soon as you save your
change.

Additional resources
Using Vue in Visual Studio Code : Find more about using Vue with VS Code,
including the Vetur extension that provides Vue syntax highlighting, IntelliSense,
debugging support, and more.

Vue.js docs

Vue comparison with other frameworks like React or Angular

Vue.js overview
 Take your first steps with Vue.js learning path

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Get started with Python using Windows
Get started developing with Python using Windows, including set up for your
development environment, scripting and automation, building web apps, and faqs.

Get started for beginners

ｃ HOW-TO GUIDE

Set up your development environment

ｇ TUTORIAL

Run some basic Python code

HelloWorld using VS Code

Create a simple game with Pygame

Get started with web development

ｃ HOW-TO GUIDE

Set up your development environment

ｇ TUTORIAL

HelloWorld using Flask

HelloWorld using Django

Get started with automation scripts

ｃ HOW-TO GUIDE

Set up your development environment

ｇ TUTORIAL

Example script - Display my file system

Example script - Modify all files in a directory

Get started with databases

ｆ QUICKSTART

Install and run MySQL, PostgreSQL, SQLite, Microsoft SQL Server, MongoDB, or Redis
Get started using Python on Windows
for beginners
Article • 03/10/2023

The following is a step-by-step guide for beginners interested in learning Python using
Windows.

Set up your development environment

For beginners who are new to Python, we recommend you install Python from the
Microsoft Store . Installing via the Microsoft Store uses the basic Python3 interpreter,
but handles set up of your PATH settings for the current user (avoiding the need for
admin access), in addition to providing automatic updates. This is especially helpful if
you are in an educational environment or a part of an organization that restricts
permissions or administrative access on your machine.

If you are using Python on Windows for web development, we recommend a different
set up for your development environment. Rather than installing directly on Windows,
we recommend installing and using Python via the Windows Subsystem for Linux. For
help, see: Get started using Python for web development on Windows. If you're
interested in automating common tasks on your operating system, see our guide: Get
started using Python on Windows for scripting and automation. For some advanced
scenarios (like needing to access/modify Python's installed files, make copies of binaries,
or use Python DLLs directly), you may want to consider downloading a specific Python
release directly from python.org or consider installing an alternative , such as
Anaconda, Jython, PyPy, WinPython, IronPython, etc. We only recommend this if you are
a more advanced Python programmer with a specific reason for choosing an alternative
implementation.

Install Python
To install Python using the Microsoft Store:

1. Go to your Start menu (lower left Windows icon), type "Microsoft Store", select the
link to open the store.

2. Once the store is open, select Search from the upper-right menu and enter
"Python". Select which version of Python you would like to use from the results
under Apps. We recommend using the most recent unless you have a reason not
 to (such as aligning with the version used on a pre-existing project that you plan to
work on). Once you've determined which version you would like to install, select
Get.

3. Once Python has completed the downloading and installation process, open
Windows PowerShell using the Start menu (lower left Windows icon). Once
PowerShell is open, enter Python --version to confirm that Python3 has installed
on your machine.

4. The Microsoft Store installation of Python includes pip, the standard package
manager. Pip allows you to install and manage additional packages that are not
part of the Python standard library. To confirm that you also have pip available to
install and manage packages, enter pip --version .

Install Visual Studio Code

By using VS Code as your text editor / integrated development environment (IDE), you
can take advantage of IntelliSense (a code completion aid), Linting (helps avoid
making errors in your code), Debug support (helps you find errors in your code after
you run it), Code snippets (templates for small reusable code blocks), and Unit
testing (testing your code's interface with different types of input).

VS Code also contains a built-in terminal that enables you to open a Python
command line with Windows Command prompt, PowerShell, or whatever you prefer,
establishing a seamless workflow between your code editor and command line.

1. To install VS Code, download VS Code for Windows:

https://code.visualstudio.com .

2. Once VS Code has been installed, you must also install the Python extension. To
install the Python extension, you can select the VS Code Marketplace link or
open VS Code and search for Python in the extensions menu (Ctrl+Shift+X).

3. Python is an interpreted language, and in order to run Python code, you must tell
VS Code which interpreter to use. We recommend using the most recent version of
Python unless you have a specific reason for choosing something different. Once
you've installed the Python extension, select a Python 3 interpreter by opening the
Command Palette (Ctrl+Shift+P), start typing the command Python: Select
Interpreter to search, then select the command. You can also use the Select
Python Environment option on the bottom Status Bar if available (it may already
show a selected interpreter). The command presents a list of available interpreters
 that VS Code can find automatically, including virtual environments. If you don't
see the desired interpreter, see Configuring Python environments .

4. To open the terminal in VS Code, select View > Terminal, or alternatively use the
shortcut Ctrl+` (using the backtick character). The default terminal is PowerShell.

5. Inside your VS Code terminal, open Python by simply entering the command:
python

6. Try the Python interpreter out by entering: print("Hello World") . Python will
return your statement "Hello World".

Install Git (optional)

If you plan to collaborate with others on your Python code, or host your project on an
open-source site (like GitHub), VS Code supports version control with Git . The Source
Control tab in VS Code tracks all of your changes and has common Git commands (add,
commit, push, pull) built right into the UI. You first need to install Git to power the
Source Control panel.

1. Download and install Git for Windows from the git-scm website .

2. An Install Wizard is included that will ask you a series of questions about settings
for your Git installation. We recommend using all of the default settings, unless
you have a specific reason for changing something.

3. If you've never worked with Git before, GitHub Guides can help you get started.
Hello World tutorial for some Python basics
Python, according to its creator Guido van Rossum, is a “high-level programming
language, and its core design philosophy is all about code readability and a syntax
which allows programmers to express concepts in a few lines of code.”

Python is an interpreted language. In contrast to compiled languages, in which the code

you write needs to be translated into machine code in order to be run by your
computer's processor, Python code is passed straight to an interpreter and run directly.
You just type in your code and run it. Let's try it!

1. With your PowerShell command line open, enter python to run the Python 3
interpreter. (Some instructions prefer to use the command py or python3 , these
should also work). You will know that you're successful because a >>> prompt
with three greater-than symbols will display.

2. There are several built-in methods that allow you to make modifications to strings
in Python. Create a variable, with: variable = 'Hello World!' . Press Enter for a new
line.

3. Print your variable with: print(variable) . This will display the text "Hello World!".

4. Find out the length, how many characters are used, of your string variable with:
len(variable) . This will display that there are 12 characters used. (Note that the

blank space it counted as a character in the total length.)

5. Convert your string variable to upper-case letters: variable.upper() . Now convert

your string variable to lower-case letters: variable.lower() .

6. Count how many times the letter "l" is used in your string variable:
variable.count("l") .

7. Search for a specific character in your string variable, let's find the exclamation
point, with: variable.find("!") . This will display that the exclamation point is
found in the 11th position character of the string.

8. Replace the exclamation point with a question mark: variable.replace("!", "?") .

9. To exit Python, you can enter exit() , quit() , or select Ctrl-Z.

Hope you had fun using some of Python's built-in string modification methods. Now try
creating a Python program file and running it with VS Code.

Hello World tutorial for using Python with VS

Code
The VS Code team has put together a great Getting Started with Python tutorial
walking through how to create a Hello World program with Python, run the program
file, configure and run the debugger, and install packages like matplotlib and numpy to
create a graphical plot inside a virtual environment.

1. Open PowerShell and create an empty folder called "hello", navigate into this
folder, and open it in VS Code:

Console

mkdir hello
cd hello
code .

2. Once VS Code opens, displaying your new hello folder in the left-side Explorer
window, open a command line window in the bottom panel of VS Code by
pressing Ctrl+` (using the backtick character) or selecting View > Terminal. By
starting VS Code in a folder, that folder becomes your "workspace". VS Code stores
settings that are specific to that workspace in .vscode/settings.json, which are
separate from user settings that are stored globally.

3. Continue the tutorial in the VS Code docs: Create a Python Hello World source
code file .
Create a simple game with Pygame

Pygame is a popular Python package for writing games - encouraging students to learn
programming while creating something fun. Pygame displays graphics in a new window,
and so it will not work under the command-line-only approach of WSL. However, if you
installed Python via the Microsoft Store as detailed in this tutorial, it will work fine.

1. Once you have Python installed, install pygame from the command line (or the
terminal from within VS Code) by typing python -m pip install -U pygame --user .

2. Test the installation by running a sample game : python -m pygame.examples.aliens

3. All being well, the game will open a window. Close the window when you are done
playing.

Here's how to start writing your own game.

1. Open PowerShell (or Windows Command Prompt) and create an empty folder
called "bounce". Navigate to this folder and create a file named "bounce.py". Open
the folder in VS Code:

PowerShell
 mkdir bounce
cd bounce
new-item bounce.py
code .

2. Using VS Code, enter the following Python code (or copy and paste it):

Python

import sys, pygame

pygame.init()

size = width, height = 640, 480

dx = 1
dy = 1
x= 163
y = 120
black = (0,0,0)
white = (255,255,255)

screen = pygame.display.set_mode(size)

while 1:

for event in pygame.event.get():

if event.type == pygame.QUIT: sys.exit()

x += dx
y += dy

if x < 0 or x > width:

dx = -dx

if y < 0 or y > height:

dy = -dy

screen.fill(black)

pygame.draw.circle(screen, white, (x,y), 8)

pygame.display.flip()

3. Save it as: bounce.py .

4. From the PowerShell terminal, run it by entering: python bounce.py .

Try adjusting some of the numbers to see what effect they have on your bouncing ball.

Read more about writing games with pygame at pygame.org .

Resources for continued learning

We recommend the following resources to support you in continuing to learn about
Python development on Windows.

Microsoft Dev Blogs: Python : Read the latest updates about all things Python at
Microsoft.

Online resources for learning Python

Introduction to Python: Try the interactive Microsoft Learn platform and earn
experience points for completing this module covering the basics on how to write
basic Python code, declare variables, and work with console input and output. The
interactive sandbox environment makes this a great place to start for folks who
don't have their Python development environment set up yet.

Learning Python on LinkedIn.com : A basic introduction to Python.

Python Tutorial For Beginners : A complete and free Python tutorial with
interactive (runnable) code examples, ideal for both complete beginners and those
with prior experience.
 LearnPython.org Tutorials : Get started on learning Python without needing to
install or set anything up with these free interactive Python tutorials from the folks
at DataCamp.

The Python.org Tutorials : Introduces the reader informally to the basic concepts
and features of the Python language and system.

Working with Python in VS Code

Editing Python in VS Code : Learn more about how to take advantage of VS
Code's autocomplete and IntelliSense support for Python, including how to
customize their behavior... or just turn them off.

Linting Python : Linting is the process of running a program that will analyse
code for potential errors. Learn about the different forms of linting support VS
Code provides for Python and how to set it up.

Debugging Python : Debugging is the process of identifying and removing errors

from a computer program. This article covers how to initialize and configure
debugging for Python with VS Code, how to set and validate breakpoints, attach a
local script, perform debugging for different app types or on a remote computer,
and some basic troubleshooting.

Unit testing Python : Covers some background explaining what unit testing
means, an example walkthrough, enabling a test framework, creating and running
your tests, debugging tests, and test configuration settings.
Get started using Python for web
development on Windows
Article • 11/01/2023

The following is a step-by-step guide to get you started using Python for web
development on Windows, using the Windows Subsystem for Linux (WSL).

Set up your development environment

We recommend installing Python on WSL when building web applications. Many of the
tutorials and instructions for Python web development are written for Linux users and
use Linux-based packaging and installation tools. Most web apps are also deployed on
Linux, so this will ensure you have consistency between your development and
production environments.

If you are using Python for something other than web development, we recommend you
install Python directly on Windows using the Microsoft Store. WSL does not support GUI
desktops or applications (like PyGame, Gnome, KDE, etc). Install and use Python directly
on Windows for these cases. If you're new to Python, see our guide: Get started using
Python on Windows for beginners. If you're interested in automating common tasks on
your operating system, see our guide: Get started using Python on Windows for
scripting and automation. For some advanced scenarios, you may want to consider
downloading a specific Python release directly from python.org or consider installing
an alternative , such as Anaconda, Jython, PyPy, WinPython, IronPython, etc. We only
recommend this if you are a more advanced Python programmer with a specific reason
for choosing an alternative implementation.

Install Windows Subsystem for Linux

WSL lets you run a GNU/Linux command line environment integrated directly with
Windows and your favorite tools, like Visual Studio Code, Outlook, etc. We generally
recommend using WSL 2 for Python web development work.

To enable and install WSL 2, see the WSL install documentation. These steps will include
choosing a Linux distribution (for example, Ubuntu).

Once you have installed WSL and a Linux distribution, open the Linux distribution (it can
be found in your Windows start menu) and check the version and codename using the
command: lsb_release -dc .
We recommend updating your Linux distribution regularly, including immediately after
you install, to ensure you have the most recent packages. Windows doesn't
automatically handle this update. To update your distribution, use the command: sudo
apt update && sudo apt upgrade .

 Tip

Consider installing the new Windows Terminal from the Microsoft Store to
enable multiple tabs (quickly switch between multiple Linux command lines,
Windows Command Prompt, PowerShell, Azure CLI, etc), create custom key
bindings (shortcut keys for opening or closing tabs, copy+paste, etc.), use the
search feature, and set up custom themes (color schemes, font styles and sizes,
background image/blur/transparency). Learn more.

Set up Visual Studio Code

Take advantage of IntelliSense , Linting , Debug support , Code snippets , and Unit
testing by using VS Code. VS Code integrates nicely with the Windows Subsystem for
Linux, providing a built-in terminal to establish a seamless workflow between your
code editor and your command line, in addition to supporting Git for version control
with common Git commands (add, commit, push, pull) built right into the UI.

1. Download and install VS Code for Windows . VS Code is also available for Linux,
but Windows Subsystem for Linux does not support GUI apps, so we need to
install it on Windows. Not to worry, you'll still be able to integrate with your Linux
command line and tools using the Remote - WSL Extension.

2. Install the Remote - WSL Extension on VS Code. This allows you to use WSL as
your integrated development environment and will handle compatibility and
pathing for you. Learn more .

） Important

If you already have VS Code installed, you need to ensure that you have the 1.35
May release or later in order to install the Remote - WSL Extension . We do not
recommend using WSL in VS Code without the Remote-WSL extension as you will
lose support for auto-complete, debugging, linting, etc. Fun fact: This WSL
extension is installed in $HOME/.vscode-server/extensions.
Create a new project
Let's create a new project directory on our Linux (Ubuntu) file system that we will then
work on with Linux apps and tools using VS Code.

1. Close VS Code and open Ubuntu 18.04 (your WSL command line) by going to your
Start menu (lower left Windows icon) and typing: "Ubuntu 18.04".

2. In your Ubuntu command line, navigate to where you want to put your project,
and create a directory for it: mkdir HelloWorld .

 Tip

An important thing to remember when using Windows Subsystem for Linux (WSL)
is that you are now working between two different file systems: 1) your Windows
file system, and 2) your Linux file system (WSL), which is Ubuntu for our example.
You will need to pay attention to where you install packages and store files. You can
install one version of a tool or package in the Windows file system and a
completely different version in the Linux file system. Updating the tool in the
Windows file system will have no effect on the tool in the Linux file system, and
vice-versa. WSL mounts the fixed drives on your computer under the /mnt/<drive>
folder in your Linux distribution. For example, your Windows C: drive is mounted
under /mnt/c/ . You can access your Windows files from the Ubuntu terminal and
use Linux apps and tools on those files and vice-versa. We recommend working in
the Linux file system for Python web development given that much of the web
tooling is originally written for Linux and deployed in a Linux production
environment. It also avoids mixing file system semantics (like Windows being case-
insensitive regarding file names). That said, WSL now supports jumping between
the Linux and Windows files systems, so you can host your files on either one.
Learn more .

Install Python, pip, and venv

Ubuntu 18.04 LTS comes with Python 3.6 already installed, but it does not come with
some of the modules that you may expect to get with other Python installations. We will
still need to install pip, the standard package manager for Python, and venv, the
standard module used to create and manage lightweight virtual environments.
Remember that you may need to update your Linux distribution so that it has the latest
version using the command: sudo apt update && sudo apt upgrade .

1. Confirm that Python3 is already installed by opening your Ubuntu terminal and
entering: python3 --version . This should return your Python version number. If
you need to update your version of Python, first update your Ubuntu version by
entering: sudo apt update && sudo apt upgrade , then update Python using sudo
apt upgrade python3 .

2. Install pip by entering: sudo apt install python3-pip . Pip allows you to install and
manage additional packages that are not part of the Python standard library.

3. Install venv by entering: sudo apt install python3-venv .

Create a virtual environment

Using virtual environments is a recommended best practice for Python development
projects. By creating a virtual environment, you can isolate your project tools and avoid
versioning conflicts with tools for your other projects. For example, you may be
maintaining an older web project that requires the Django 1.2 web framework, but then
an exciting new project comes along using Django 2.2. If you update Django globally,
outside of a virtual environment, you could run into some versioning issues later on. In
addition to preventing accidental versioning conflicts, virtual environments let you install
and manage packages without administrative privileges.

1. Open your terminal and, inside your HelloWorld project folder, use the following
command to create a virtual environment named .venv: python3 -m venv .venv .

2. To activate the virtual environment, enter: source .venv/bin/activate . If it worked,

you should see (.venv) before the command prompt. You now have a self-
contained environment ready for writing code and installing packages. When
you're finished with your virtual environment, enter the following command to
deactivate it: deactivate .

 Tip
 We recommend creating the virtual environment inside the directory in which you
plan to have your project. Since each project should have its own separate
directory, each will have its own virtual environment, so there is not a need for
unique naming. Our suggestion is to use the name .venv to follow the Python
convention. Some tools (like pipenv) also default to this name if you install into
your project directory. You don't want to use .env as that conflicts with
environment variable definition files. We generally do not recommend non-dot-
leading names, as you don't need ls constantly reminding you that the directory
exists. We also recommend adding .venv to your .gitignore file. (Here is GitHub's
default gitignore template for Python for reference.) For more information
about working with virtual environments in VS Code, see Using Python
environments in VS Code .

Open a WSL - Remote window

VS Code uses the Remote - WSL Extension (installed previously) to treat your Linux
subsystem as a remote server. This allows you to use WSL as your integrated
development environment. Learn more .

1. Open your project folder in VS Code from your Ubuntu terminal by entering: code
. (the "." tells VS Code to open the current folder).

2. A Security Alert will pop-up from Windows Defender, select "Allow access". Once
VS Code opens, you should see the Remote Connection Host indicator, in the
bottom-left corner, letting you know that you are editing on WSL: Ubuntu-18.04.

3. Close your Ubuntu terminal. Moving forward we will use the WSL terminal
integrated into VS Code.

4. Open the WSL terminal in VS Code by pressing Ctrl+` (using the backtick
character) or selecting View > Terminal. This will open a bash (WSL) command-line
opened to the project folder path that you created in your Ubuntu terminal.
Install the Microsoft Python extension
You will need to install any VS Code extensions for your Remote - WSL. Extensions
already installed locally on VS Code will not automatically be available. Learn more .

1. Open the VS Code Extensions window by entering Ctrl+Shift+X (or use the menu
to navigate to View > Extensions).

2. In the top Search Extensions in Marketplace box, enter: Python.

3. Find the Python (ms-python.python) by Microsoft extension and select the green
Install button.

4. Once the extension is finished installing, you will need to select the blue Reload
Required button. This will reload VS Code and display a WSL: UBUNTU-18.04 -
Installed section in your VS Code Extensions window showing that you've installed
the Python extension.

Run a simple Python program

Python is an interpreted language and supports different types of interpreters (Python2,
Anaconda, PyPy, etc). VS Code should default to the interpreter associated with your
project. If you have a reason to change it, select the interpreter currently displayed in
blue bar on the bottom of your VS Code window or open the Command Palette
(Ctrl+Shift+P) and enter the command Python: Select Interpreter. This will display a list
of the Python interpreters that you currently have installed. Learn more about
configuring Python environments .

Let's create and run a simple Python program as a test and ensure that we have the
correct Python interpreter selected.
 1. Open the VS Code File Explorer window by entering Ctrl+Shift+E (or use the menu
to navigate to View > Explorer).

2. If it's not already open, open your integrated WSL terminal by entering
Ctrl+Shift+` and ensure that your HelloWorld python project folder is selected.

3. Create a python file by entering: touch test.py . You should see the file you just
created appear in your Explorer window under the .venv and .vscode folders
already in your project directory.

4. Select the test.py file that you just created in your Explorer window to open it in VS
Code. Because the .py in our file name tells VS Code that this is a Python file, the
Python extension you loaded previously will automatically choose and load a
Python interpreter that you will see displayed on the bottom of your VS Code
window.

5. Paste this Python code into your test.py file and then save the file (Ctrl+S):

Python

print("Hello World")

6. To run the Python "Hello World" program that we just created, select the test.py
file in the VS Code Explorer window, then right-click the file to display a menu of
options. Select Run Python File in Terminal. Alternatively, in your integrated WSL
terminal window, enter: python test.py to run your "Hello World" program. The
Python interpreter will print "Hello World" in your terminal window.

Congratulations. You're all set up to create and run Python programs! Now let's try
creating a Hello World app with two of the most popular Python web frameworks: Flask
and Django.

Hello World tutorial for Flask

Flask is a web application framework for Python. The Flask documentation offers
guidance on getting started and a more detailed tutorial about how to create a small
but complete application.
Following the steps below, you can create a small "Hello World" Flask app using VS
Code and WSL.

1. Open Ubuntu 18.04 (your WSL command line) by going to your Start menu (lower
left Windows icon) and typing: "Ubuntu 18.04".

2. Create a directory for your project: mkdir HelloWorld-Flask , then cd HelloWorld-

Flask to enter the directory.

3. Create a virtual environment to install your project tools: python3 -m venv .venv

4. Open your HelloWorld-Flask project in VS Code by entering the command: code .

5. Inside VS Code, open your integrated WSL terminal (aka Bash) by entering
Ctrl+Shift+` (your HelloWorld-Flask project folder should already be selected).
Close your Ubuntu command line as we will be working in the WSL terminal
integrated with VS Code moving forward.

6. Activate the virtual environment that you created in step #3 using your Bash
terminal in VS Code: source .venv/bin/activate . If it worked, you should see
(.venv) before the command prompt.

7. Install Flask in the virtual environment by entering: python3 -m pip install flask .
Verify that it's installed by entering: python3 -m flask --version .

8. Create a new file for your Python code: touch app.py

9. Open your app.py file in VS Code's File Explorer ( Ctrl+Shift+E , then select your
app.py file). This will activate the Python Extension to choose an interpreter. It
should default to Python 3.6.8 64-bit ('.venv': venv). Notice that it also detected
your virtual environment.

10. In app.py, add code to import Flask and create an instance of the Flask object:

Python

from flask import Flask

app = Flask(__name__)
11. Also in app.py, add a function that returns content, in this case a simple string. Use
Flask's app.route decorator to map the URL route "/" to that function:

Python

@app.route("/")
def home():
return "Hello World! I'm using Flask."

 Tip

You can use multiple decorators on the same function, one per line,
depending on how many different routes you want to map to the same
function.

12. Save the app.py file (Ctrl+S).

13. In the terminal, run the app by entering the following command:

Python

python3 -m flask run

This runs the Flask development server. The development server looks for app.py
by default. When you run Flask, you should see output similar to the following:

Bash

(env) user@USER:/mnt/c/Projects/HelloWorld$ python3 -m flask run

* Environment: production
WARNING: This is a development server. Do not use it in a production
deployment.
Use a production WSGI server instead.
* Debug mode: off
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

14. Open your default web browser to the rendered page, Ctrl+Click the
http://127.0.0.1:5000/ URL in the terminal. You should see the following message
in your browser:

15. Observe that when you visit a URL like "/", a message appears in the debug
terminal showing the HTTP request:
 Bash

127.0.0.1 - - [19/Jun/2019 13:36:56] "GET / HTTP/1.1" 200 -

16. Stop the app by using Ctrl+C in the terminal.

 Tip

If you want to use a different filename than app.py, such as program.py, define an
environment variable named FLASK_APP and set its value to your chosen file.
Flask's development server then uses the value of FLASK_APP instead of the default
file app.py. For more information, see the Flask documentation .

Congratulations, you've created a Flask web application using Visual Studio Code and
Windows Subsystem for Linux! For a more in-depth tutorial using VS Code and Flask,
see Flask Tutorial in Visual Studio Code .

Hello World tutorial for Django

Django is a web application framework for Python. In this brief tutorial, you'll create a
small "Hello World" Django app using VS Code and WSL.

1. Open Ubuntu 18.04 (your WSL command line) by going to your Start menu (lower
left Windows icon) and typing: "Ubuntu 18.04".

2. Create a directory for your project: mkdir HelloWorld-Django , then cd HelloWorld-

Django to enter the directory.

3. Create a virtual environment to install your project tools: python3 -m venv .venv

4. Open your HelloWorld-Django project in VS Code by entering the command: code

.

5. Inside VS Code, open your integrated WSL terminal (aka Bash) by entering
Ctrl+Shift+` (your HelloWorld-Django project folder should already be selected).
Close your Ubuntu command line as we will be working in the WSL terminal
integrated with VS Code moving forward.

6. Activate the virtual environment that you created in step #3 using your Bash
terminal in VS Code: source .venv/bin/activate . If it worked, you should see
(.venv) before the command prompt.
7. Install Django in the virtual environment with the command: python3 -m pip
install django . Verify that it's installed by entering: python3 -m django --version .

8. Next, run the following command to create the Django project:

Bash

django-admin startproject web_project .

The startproject command assumes (by use of . at the end) that the current
folder is your project folder, and creates the following within it:

manage.py : The Django command-line administrative utility for the project.

You run administrative commands for the project using python manage.py
<command> [options] .

A subfolder named web_project , which contains the following files:

__init__.py : an empty file that tells Python that this folder is a Python

package.
wsgi.py : an entry point for WSGI-compatible web servers to serve your

project. You typically leave this file as-is as it provides the hooks for
production web servers.
settings.py : contains settings for Django project, which you modify in the

course of developing a web app.

urls.py : contains a table of contents for the Django project, which you

also modify in the course of development.

9. To verify the Django project, start Django's development server using the
command python3 manage.py runserver . The server runs on the default port 8000,
and you should see output like the following output in the terminal window:

Output

Performing system checks...

System check identified no issues (0 silenced).

June 20, 2019 - 22:57:59

Django version 2.2.2, using settings 'web_project.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

When you run the server the first time, it creates a default SQLite database in the
file db.sqlite3 , which is intended for development purposes, but can be used in
 production for low-volume web apps. Also, Django's built-in web server is
intended only for local development purposes. When you deploy to a web host,
however, Django uses the host's web server instead. The wsgi.py module in the
Django project takes care of hooking into the production servers.

If you want to use a different port than the default 8000, specify the port number
on the command line, such as python3 manage.py runserver 5000 .

10. Ctrl+click the http://127.0.0.1:8000/ URL in the terminal output window to

open your default browser to that address. If Django is installed correctly and the
project is valid, you'll see a default page. The VS Code terminal output window also
shows the server log.

11. When you're done, close the browser window and stop the server in VS Code using
Ctrl+C as indicated in the terminal output window.

12. Now, to create a Django app, run the administrative utility's startapp command in
your project folder (where manage.py resides):

Bash

python3 manage.py startapp hello

The command creates a folder called hello that contains a number of code files
and one subfolder. Of these, you frequently work with views.py (that contains the
functions that define pages in your web app) and models.py (that contains classes
defining your data objects). The migrations folder is used by Django's
administrative utility to manage database versions as discussed later in this
tutorial. There are also the files apps.py (app configuration), admin.py (for creating
an administrative interface), and tests.py (for tests), which are not covered here.

13. Modify hello/views.py to match the following code, which creates a single view
for the app's home page:

Python

from django.http import HttpResponse

def home(request):
return HttpResponse("Hello, Django!")

14. Create a file, hello/urls.py , with the contents below. The urls.py file is where you
specify patterns to route different URLs to their appropriate views. The code below
 contains one route to map root URL of the app ( "" ) to the views.home function
that you just added to hello/views.py :

Python

from django.urls import path

from hello import views

urlpatterns = [
path("", views.home, name="home"),
]

15. The web_project folder also contains a urls.py file, which is where URL routing is
actually handled. Open web_project/urls.py and modify it to match the following
code (you can retain the instructive comments if you like). This code pulls in the
app's hello/urls.py using django.urls.include , which keeps the app's routes
contained within the app. This separation is helpful when a project contains
multiple apps.

Python

from django.contrib import admin

from django.urls import include, path

urlpatterns = [
path("", include("hello.urls")),
]

16. Save all modified files.

17. In the VS Code Terminal, run the development server with python3 manage.py
runserver and open a browser to http://127.0.0.1:8000/ to see a page that

renders "Hello, Django".

Congratulations, you've created a Django web application using VS Code and Windows
Subsystem for Linux! For a more in-depth tutorial using VS Code and Django, see
Django Tutorial in Visual Studio Code .

Additional resources
Microsoft Dev Blogs: Python : Read the latest updates about all things Python at
Microsoft.
Python Tutorial with VS Code : An intro tutorial to VS Code as a Python
environment, primarily how to edit, run, and debug code.
Git support in VS Code : Learn how to use Git version control basics in VS Code.
Learn about updates coming soon with WSL 2!: This new version changes how
Linux distributions interact with Windows, increasing file system performance and
adding full system call compatibility.
Working with multiple Linux distributions on Windows: Learn how to manage
multiple different Linux distributions on your Windows machine.
Get started using Python on Windows
for scripting and automation
Article • 05/25/2021

The following is a step-by-step guide for setting up your developer environment and
getting you started using Python for scripting and automating file system operations on
Windows.

７ Note

This article will cover setting up your environment to use some of the helpful
libraries in Python that can automate tasks across platforms, like searching your file
system, accessing the internet, parsing file types, etc., from a Windows-centered
approach. For Windows-specific operations, check out ctypes , a C-compatible
foreign function library for Python, winreg , functions exposing the Windows
registry API to Python, and Python/WinRT , enabling access Windows Runtime
APIs from Python.

Set up your development environment

When using Python to write scripts that perform file system operations, we recommend
you install Python from the Microsoft Store . Installing via the Microsoft Store uses the
basic Python3 interpreter, but handles set up of your PATH settings for the current user
(avoiding the need for admin access), in addition to providing automatic updates.

If you are using Python for web development on Windows, we recommend a different
setup using the Windows Subsystem for Linux. Find a walkthrough in our guide: Get
started using Python for web development on Windows. If you're brand new to Python,
try our guide: Get started using Python on Windows for beginners. For some advanced
scenarios (like needing to access/modify Python's installed files, make copies of binaries,
or use Python DLLs directly), you may want to consider downloading a specific Python
release directly from python.org or consider installing an alternative , such as
Anaconda, Jython, PyPy, WinPython, IronPython, etc. We only recommend this if you are
a more advanced Python programmer with a specific reason for choosing an alternative
implementation.

Install Python
To install Python using the Microsoft Store:

1. Go to your Start menu (lower left Windows icon), type "Microsoft Store", select the
link to open the store.

2. Once the store is open, select Search from the upper-right menu and enter
"Python". Select which version of Python you would like to use from the results
under Apps. We recommend using the most recent unless you have a reason not
to (such as aligning with the version used on a pre-existing project that you plan to
work on). Once you've determined which version you would like to install, select
Get.

3. Once Python has completed the downloading and installation process, open
Windows PowerShell using the Start menu (lower left Windows icon). Once
PowerShell is open, enter Python --version to confirm that Python3 has been
installed on your machine.

4. The Microsoft Store installation of Python includes pip, the standard package
manager. Pip allows you to install and manage additional packages that are not
part of the Python standard library. To confirm that you also have pip available to
install and manage packages, enter pip --version .

Install Visual Studio Code

By using VS Code as your text editor / integrated development environment (IDE), you
can take advantage of IntelliSense (a code completion aid), Linting (helps avoid
making errors in your code), Debug support (helps you find errors in your code after
you run it), Code snippets (templates for small reusable code blocks), and Unit
testing (testing your code's interface with different types of input).

Download VS Code for Windows and follow the installation instructions:

https://code.visualstudio.com .

Install the Microsoft Python extension

You will need to install the Microsoft Python extension in order to take advantage of the
VS Code support features. Learn more .

1. Open the VS Code Extensions window by entering Ctrl+Shift+X (or use the menu
to navigate to View > Extensions).

2. In the top Search Extensions in Marketplace box, enter: Python.

 3. Find the Python (ms-python.python) by Microsoft extension and select the green
Install button.

Open the integrated PowerShell terminal in VS

Code
VS Code contains a built-in terminal that enables you to open a Python command line
with PowerShell, establishing a seamless workflow between your code editor and
command line.

1. Open the terminal in VS Code, select View > Terminal, or alternatively use the
shortcut Ctrl+` (using the backtick character).

７ Note

The default terminal should be PowerShell, but if you need to change it, use
Ctrl+Shift+P to enter the command pallette. Enter Terminal: Select Default
Shell and a list of terminal options will display containing PowerShell,
Command Prompt, WSL, etc. Select the one you'd like to use and enter
Ctrl+Shift+` (using the backtick) to create a new terminal.

2. Inside your VS Code terminal, open Python by entering: python

3. Try the Python interpreter out by entering: print("Hello World") . Python will
return your statement "Hello World".

4. To exit Python, you can enter exit() , quit() , or select Ctrl-Z.

Install Git (optional)

If you plan to collaborate with others on your Python code, or host your project on an
open-source site (like GitHub), VS Code supports version control with Git . The Source
Control tab in VS Code tracks all of your changes and has common Git commands (add,
commit, push, pull) built right into the UI. You first need to install Git to power the
Source Control panel.

1. Download and install Git for Windows from the git-scm website .

2. An Install Wizard is included that will ask you a series of questions about settings
for your Git installation. We recommend using all of the default settings, unless
you have a specific reason for changing something.

3. If you've never worked with Git before, GitHub Guides can help you get started.

Example script to display the structure of your

file system directory
Common system administration tasks can take a huge amount of time, but with a
Python script, you can automate these tasks so that they take no time at all. For
example, Python can read the contents of your computer's file system and perform
operations like printing an outline of your files and directories, moving folders from one
directory to another, or renaming hundreds of files. Normally, tasks like these could take
up a ton of time if you were to perform them manually. Use a Python script instead!

Let's begin with a simple script that walks a directory tree and displays the directory
structure.

1. Open PowerShell using the Start menu (lower left Windows icon).

2. Create a directory for your project: mkdir python-scripts , then open that directory:
cd python-scripts .

3. Create a few directories to use with our example script:

PowerShell

mkdir food, food\fruits, food\fruits\apples, food\fruits\oranges,

food\vegetables

4. Create a few files within those directories to use with our script:

PowerShell
 new-item food\fruits\banana.txt, food\fruits\strawberry.txt,
food\fruits\blueberry.txt, food\fruits\apples\honeycrisp.txt,
food\fruits\oranges\mandarin.txt, food\vegetables\carrot.txt

5. Create a new python file in your python-scripts directory:

PowerShell

mkdir src
new-item src\list-directory-contents.py

6. Open your project in VS Code by entering: code .

7. Open the VS Code File Explorer window by entering Ctrl+Shift+E (or use the menu
to navigate to View > Explorer) and select the list-directory-contents.py file that
you just created. The Microsoft Python extension will automatically load a Python
interpreter. You can see which interpreter was loaded on the bottom of your VS
Code window.

７ Note

Python is an interpreted language, meaning that it acts as a virtual machine,

emulating a physical computer. There are different types of Python
interpreters that you can use: Python 2, Python 3, Anaconda, PyPy, etc. In
order to run Python code and get Python IntelliSense, you must tell VS Code
which interpreter to use. We recommend sticking with the interpreter that VS
Code chooses by default (Python 3 in our case) unless you have a specific
reason for choosing something different. To change the Python interpreter,
select the interpreter currently displayed in blue bar on the bottom of your VS
Code window or open the Command Palette (Ctrl+Shift+P) and enter the
command Python: Select Interpreter. This will display a list of the Python
interpreters that you currently have installed. Learn more about configuring
Python environments .

8. Paste the following code into your list-directory-contents.py file and then select
save:
 Python

import os

root = os.path.join('..', 'food')

for directory, subdir_list, file_list in os.walk(root):
print('Directory:', directory)
for name in subdir_list:
print('Subdirectory:', name)
for name in file_list:
print('File:', name)
print()

9. Open the VS Code integrated terminal (Ctrl+`, using the backtick character) and
enter the src directory where you just saved your Python script:

PowerShell

cd src

10. Run the script in PowerShell with:

PowerShell

python3 .\list-directory-contents.py

You should see output that looks like this:

PowerShell

Directory: ..\food
Subdirectory: fruits
Subdirectory: vegetables

Directory: ..\food\fruits
Subdirectory: apples
Subdirectory: oranges
File: banana.txt
File: blueberry.txt
File: strawberry.txt

Directory: ..\food\fruits\apples
File: honeycrisp.txt

Directory: ..\food\fruits\oranges
File: mandarin.txt

Directory: ..\food\vegetables
File: carrot.txt
 11. Use Python to print that file system directory output to it's own text file by
entering this command directly in your PowerShell terminal: python3 list-
directory-contents.py > food-directory.txt

Congratulations! You've just written an automated systems administration script that

reads the directory and files you created and uses Python to display, and then print, the
directory structure to it's own text file.

７ Note

If you're unable to install Python 3 from the Microsoft Store, see this issue for an
example of how to handle the pathing for this sample script.

Example script to modify all files in a directory

This example uses the files and directories you just created, renaming each of the files
by adding the file's last modified date to the beginning of the filename.

1. Inside the src folder in your python-scripts directory, create a new Python file for
your script:

PowerShell

new-item update-filenames.py

2. Open the update-filenames.py file, paste the following code into the file, and save
it:

７ Note

os.getmtime returns a timestamp in ticks, which is not easily readable. It must

be converted to a standard datetime string first.

Python

import datetime
import os

root = os.path.join('..', 'food')

for directory, subdir_list, file_list in os.walk(root):
for name in file_list:
source_name = os.path.join(directory, name)
 timestamp = os.path.getmtime(source_name)
modified_date =
str(datetime.datetime.fromtimestamp(timestamp)).replace(':', '.')
target_name = os.path.join(directory,
f'{modified_date}_{name}')

print(f'Renaming: {source_name} to: {target_name}')

os.rename(source_name, target_name)

3. Test your update-filenames.py script by running it: python3 update-filenames.py

and then running your list-directory-contents.py script again: python3 list-
directory-contents.py

4. You should see output that looks like this:

PowerShell

Renaming: ..\food\fruits\banana.txt to: ..\food\fruits\2019-07-18

12.24.46.385185_banana.txt
Renaming: ..\food\fruits\blueberry.txt to: ..\food\fruits\2019-07-18
12.24.46.391170_blueberry.txt
Renaming: ..\food\fruits\strawberry.txt to: ..\food\fruits\2019-07-18
12.24.46.389174_strawberry.txt
Renaming: ..\food\fruits\apples\honeycrisp.txt to:
..\food\fruits\apples\2019-07-18 12.24.46.395160_honeycrisp.txt
Renaming: ..\food\fruits\oranges\mandarin.txt to:
..\food\fruits\oranges\2019-07-18 12.24.46.398151_mandarin.txt
Renaming: ..\food\vegetables\carrot.txt to: ..\food\vegetables\2019-07-
18 12.24.46.402496_carrot.txt

PS C:\src\python-scripting\src> python3 .\list-directory-contents.py

..\food\
Directory: ..\food
Subdirectory: fruits
Subdirectory: vegetables

Directory: ..\food\fruits
Subdirectory: apples
Subdirectory: oranges
File: 2019-07-18 12.24.46.385185_banana.txt
File: 2019-07-18 12.24.46.389174_strawberry.txt
File: 2019-07-18 12.24.46.391170_blueberry.txt

Directory: ..\food\fruits\apples
File: 2019-07-18 12.24.46.395160_honeycrisp.txt

Directory: ..\food\fruits\oranges
File: 2019-07-18 12.24.46.398151_mandarin.txt

Directory: ..\food\vegetables
 File: 2019-07-18 12.24.46.402496_carrot.txt

5. Use Python to print the new file system directory names with the last-modified
timestamp prepended to it's own text file by entering this command directly in
your PowerShell terminal: python3 list-directory-contents.py > food-directory-
last-modified.txt

Hope you learned a few fun things about using Python scripts for automating basic
systems administration tasks. There is, of course, a ton more to know, but we hope this
got you started on the right foot. We've shared a few additional resources to continue
learning below.

Additional resources
Python Docs: File and Directory Access : Python documentation about working
with file systems and using modules for reading the properties of files,
manipulating paths in a portable way, and creating temporary files.
Learn Python: String_Formatting tutorial : More about using the "%" operator for
string formatting.
10 Python File System Methods You Should Know : Medium article about
manipulating files and folders With os and shutil .
The Hitchhikers Guide to Python: Systems Administration : An "opinionated
guide" that offers overviews and best practices on topics related to Python. This
section covers System Admin tools and frameworks. This guide is hosted on
GitHub so you can file issues and make contributions.
Frequently Asked Questions about
using Python on Windows
FAQ

Trouble installing a package with pip

install
There are a number of reasons why an installation will fail--in many cases the right
solution is to contact the package developer.

A common cause for trouble is trying to install into a location that you do not have
permission to modify. For example, the default install location might require
Administrative privileges, but by default Python will not have them. The best solution is
to create a virtual environment and install there.

Some packages include native code that requires a C or C++ compiler to install. In
general, package developers should publish pre-compiled versions, but often do not.
Some of these packages might work if you install Build Tools for Visual Studio and
select the C++ option, however in most cases you will need to contact the package
developer.

Follow the discussion on StackOverflow

Trouble installing pip with WSL

When installing a package (like Flask) with pip on Windows Subsystem for Linux (WSL or
WSL2), for example python3 -m pip install flask , you may specifically encounter an
error like this:

Bash

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None,

status=None))
after connection broken by
'NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection
object at 0x7f655471da30>: Failed to establish a new connection: [Errno -3]
Temporary failure in name resolution')': /simple/flask/
When researching this problem you may be led down several rabbit holes, none of
which are particularly productive with a WSL linux distribution. (Warning: on WSL do not
try editing resolv.conf , that file is a symbolic link and modifying it is a can of worms).
Unless you are running an aftermarket firewall, the likely solution is to simply re-install
pip:

Bash

sudo apt -y purge python3-pip

sudo python3 -m pip uninstall pip
sudo apt -y install python3-pip --fix-missing

*Further discussion in the WSL product repo on GitHub . Thanks to our user community
for contributing this issue to the docs.

What is py.exe?
You may end up with multiple versions of Python installed on your machine because you
are working on different types of Python projects. Because these all use the python
command, it may not be obvious which version of Python you are using. As a standard,
it is recommended to use the python3 command (or python3.7 to select a specific
version).

The py.exe launcher will automatically select the most recent version of Python you've
installed. You can also use commands like py -3.7 to select a particular version, or py -
-list to see which versions can be used. HOWEVER, the py.exe launcher will only work

if you are using a version of Python installed from python.org . When you install
Python from the Microsoft Store, the py command is not included. For Linux, macOS,
WSL and the Microsoft Store version of Python, you should use the python3 (or
python3.7 ) command.

Why does running python.exe open the

Microsoft Store?
To help new users find a good installation of Python, we added a shortcut to Windows
that will take you directly to the latest version of the community's package published in
the Microsoft Store. This package can be installed easily, without administrator
permissions, and will replace the default python and python3 commands with the real
ones.
Running the shortcut executable with any command-line arguments will return an error
code to indicate that Python was not installed. This is to prevent batch files and scripts
from opening the Store app when it was probably not intended.

If you install Python using the installers from python.org and select the "add to PATH"
option, the new python command will take priority over the shortcut. Note that other
installers may add python at a lower priority than the built-in shortcut.

You can disable the shortcuts without installing Python by opening "Manage app
execution aliases" from Start, finding the "App Installer" Python entries and switching
them to "Off".

Why don’t file paths work in Python

when I copy-paste them?
Python strings use “escapes” for special characters. For example, to insert a new line
character into a string, you would type \n . Because file paths on Windows use
backslashes, some parts might be being converted into special characters.

To paste a path as a string in Python, add the r prefix. This indicates that it is a raw
string, and no escape characters will be used except for \” (you might need to remove
the last backslash in your path). So your path might look like:
r"C:\Users\MyName\Documents\Document.txt"

When working with paths in Python, we recommend using the standard pathlib module.
This will let you convert the string to a rich Path object that can do path manipulations
consistently whether it uses forward slashes or backslashes, making your code work
better across different operating systems.

What is PYTHONPATH?
The PYTHONPATH environment variable is used by Python to specify a list of directories
that modules can be imported from. When running, you can inspect the sys.path
variable to see which directories will be searched when you import something.

To set this variable from the Command Prompt, use: set PYTHONPATH=list;of;paths .

To set this variable from PowerShell, use: $env:PYTHONPATH=’list;of;paths’ just before

you launch Python.
Setting this variable globally through the Environment Variables settings is not
recommended, as it may be used by any version of Python instead of the one that you
intend to use.

Where can I find help with packaging

and deployment?
Docker : VSCode extension helps you quickly package and deploy with Dockerfile
and docker-compose.yml templates (generate the proper Docker files for your project).

Azure Kubernetes Service (AKS) enables you to deploy and manage containerized
applications while scaling resources on demand.

What if I need to work across different

machines?
Settings Sync allows you to synchronize your VS Code settings across different
installations using GitHub. If you work on different machines, this helps keep your
environment consistent across them.

What if I'm used to using PyCharm,

Atom, Sublime Text, Emacs, or Vim?
The VSCode extension Keymaps can help your environment feel right at home.

How do Mac shortcut keys map to

Windows shortcut keys?
Some of the keyboard buttons and system shortcuts are slightly different between a
Windows machine and a Macintosh. This Mac to Windows transition guide covers the
basics.

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Overview of Android development on
Windows
Article • 09/29/2023

A guide to help you set up your development environment on a Windows 10 or

Windows 11 machine for developing Android apps. Android is a trademark of Google
LLC. If you're a developer interested in using Windows operating system to build apps
that work on Android devices and across other device platforms, this guide is for you.

You can also learn about using Windows Subsystem for Android™️to update and test
your Android application so that it will run on a Windows 11 device using the Amazon
Appstore. Learn more.

Windows as your development environment

There are multiple paths for developing an Android device app using the Windows
operating system. These paths fall into three main types: Native Android development,
Cross-platform development, and Android game development. This overview will help
you decide which development path to follow for developing an Android app and then
provide next steps to help you get started using Windows to develop with:

Native Android
.NET MAUI
React Native
PWA with Cordova or Ionic
C/C++ for game development

*If you have been using Xamarin for cross-platform apps, see Migrate from Xamarin to
.NET MAUI.

In addition, this guide will provide tips on using Windows to:

Test on an Android device or emulator

Update Windows Defender settings to improve performance
Develop dual-screen apps for Android and get the Surface Duo device SDK

Native Android
Native Android development on Windows means that your app is targeting only
Android (not iOS or Windows devices). You can use Android Studio or Visual Studio
to develop within the ecosystem designed specifically for the Android operating system.
Performance will be optimized for Android devices, the user-interface look and feel will
be consistent with other native apps on the device, and any features or capabilities of
the user's device will be straight-forward to access and utilize. Developing your app in a
native format will help it to just 'feel right' because it follows all of the interaction
patterns and user experience standards established specifically for Android devices.

Cross-platform
Cross-platform frameworks provide a single codebase that can (mostly) be shared
between Android, iOS, and Windows devices. Using a cross-platform framework can
help your app to maintain the same look, feel, and experience across device platforms,
as well as benefiting from the automatic rollout of updates and fixes. Instead of needing
to understand a variety of device-specific code languages, the app is developed in a
shared codebase, typically in one language.

While cross-platform frameworks aim to look and feel as close to native apps as
possible, they will never be as seamlessly integrated as a natively developed app and
may suffer from reduced speed and degraded performance. Additionally, the tools used
to build cross-platform apps may not have all of the features offered by each different
device platform, potentially requiring workarounds.

A codebase is typically made up of UI code, for creating the user interface like pages,
buttons controls, labels, lists, etc., and logic code, for calling web services, accessing a
database, invoking hardware capabilities and managing state. On average, 90% of this
can be reused, though there is typically some need to customize code for each device
platform. This generalization largely depends on the type of app you're building, but
provides a bit of context that hopefully will help with your decision-making.

Choosing a cross-platform framework

.NET MAUI

A cross-platform framework for creating native mobile and desktop apps with C#
and XAML.
Develop apps that can run on Android, iOS, macOS, and Windows from a single
shared code-base, with deep access to every aspect of each native platform from a
single unified API that enables a write-once, run-anywhere dev experience.
Share UI layout and design across platforms.
An open-source evolution of Xamarin.Forms, extended from mobile to desktop
scenarios, with UI controls rebuilt for performance and extensibility.
 Migrate Xamarin.Android projects to .NET MAUI

React Native

UI code: JavaScript
Logic code: JavaScript
The goal of React Native isn't to write the code once and run it on any platform,
rather to learn-once (the React way) and write-anywhere.
The community has added tools such as Expo and Create React Native App to help
those wanting to build apps without using Xcode or Android Studio.
Similar to .NET MAUI (C#), React Native (JavaScript) calls native UI elements
(without the need for writing Java/Kotlin or Swift).

Progressive Web Apps (PWAs)

UI code: HTML, CSS, JavaScript

Logic code: JavaScript
PWAs are web apps built with standard patterns to allow them to take advantage
of both web and native app features. They can be built without a framework, but a
couple of popular frameworks to consider are Ionic and Apache Cordova .
PWAs can be installed on a device (Android, iOS, or Windows) and can work offline
thanks to the incorporation of a service-worker.
PWAs can be distributed and installed without an app store using only a web URL.
The Microsoft Store and Google Play Store allow PWAs to be listed, the Apple
Store currently does not, though they can still be installed on any iOS device
running 12.2 or later.
To learn more, check out this introduction to PWAs on MDN.

Game development
Game development for Android is often unique from developing a standard Android
app since games typically use custom rendering logic, often written in OpenGL or
Vulkan. For this reason, and because of the many C libraries available that support game
development, it's common for developers to use C/C++ with Visual Studio, along with
the Android Native Development Kit (NDK), to create games for Android. Get started
with C/C++ for game development.

For more guidance on developing Android games, see the Android Developer site:
Game development basics . You will find guidance on using a game engine (like Unity,
Unreal, Defold, Godot), as well as using IDEs (like Android Studio or Visual Studio).

Next steps
Get started with native Android development on Windows
Get started with Windows Subsystem for Android
Get started developing for Android using .NET MAUI
Get started developing for Android using React Native
Get started developing a PWA for Android
Develop Dual-screen apps for Android and get the Surface Duo device SDK
Enable Virtualization support to improve emulator performance
Windows Subsystem for Android™️
Article • 03/05/2024

Windows Subsystem for Android™️enables your Windows 11 device to run Android

applications that are available in the Amazon Appstore. Android is a trademark of
Google LLC. If you're a developer interested in targeting Windows desktop devices and
optimizing for the Windows operating system, this guide is for you.

） Important

Microsoft is ending support for the Windows Subsystem for Android™️(WSA). As a

result, the Amazon Appstore on Windows and all applications and games
dependent on WSA will no longer be supported beginning March 5, 2025. Until
then, technical support will remain available to customers.
Customers that have installed the Amazon Appstore or Android apps prior to
March 5, 2024, will continue to have access to those apps through the deprecation
date of March 5, 2025. Please reach out to our support team for further questions
at support.microsoft.com . We are grateful for the support of our developer
community and remain committed to listening to feedback as we evolve
experiences.

To make your Android app available on Windows 11 devices, you must:

Submit your app to the Amazon Appstore .

For more information or support:

Sign up for updates to the Amazon Appstore on Windows program .

Visit the Amazon developer support portal where you can find articles, forums,
FAQs, or reach out for direct support via the Appstore "Contact us" page once you
set up an Amazon Developer account.

This guide can help you test and debug your Android app on Windows:

Set up your development environment, including prerequisites, installing the

Amazon Appstore, and using the Settings.
Test and debug your app on a Windows 11 device.
Handle input compatibility considerations for Windows devices, such as: keyboard
input, mouse input, and window management and resizing.
Troubleshoot and find answers.
Developer GitHub
Want to learn more about Windows Subsystem for Android™️roadmap, discuss
developer issues and file bugs or feature requests with the subsystem team? Visit the
Windows Subsystem for Android™️Developers GitHub .

Preview Program
The Windows Subsystem for Android™️Preview Program allows users to receive early-
preview builds of the Windows Subsystem for Android™ and Amazon Appstore on
Windows. For more details, visit the Preview Program page.

Set up your development environment

To test your Android app in the Windows desktop environment, a bit of set up will be
required.

Prerequisites
Windows Subsystem for Android™️is available on Windows 11. Your device must meet
specific requirements: Device requirements .

Install the Amazon Appstore

The Microsoft Store will automatically install Windows Subsystem for Android™️silently
in the background when either of the two following user actions are taken:

1. Install the Amazon Appstore from the Microsoft Store . Selecting Get will begin
the installation of the app.
2. Install an Android app from the Microsoft Store for the first time, which will also
install the Amazon Appstore.

The Amazon Appstore app will then appear in the Windows 11 Start menu and be
available on search, offering a catalogue of Android apps. The Windows Subsystem for
Android™️app, which lets you control mobile app settings and features, will also appear
in the Start menu.
 ７ Note

The Amazon Appstore on Windows (a requirement for running Android apps on

Windows 11) is available in select regions .

Windows Subsystem for Android™️Settings

To modify Windows Subsystem for Android™️settings, go to: Start > All Apps >
Windows Subsystem for Android™️. Learn more about specific settings app features:
Manage settings for mobile apps on Windows .
Test and debug
To test and debug your app on a Windows 11 device using the Windows Subsystem for
Android™️the following set up steps are required.

Enable developer mode in Windows Settings

You must first enable developer mode. Open the Windows Subsystem for Android™️
settings. Once open, enable Developer mode under Advanced settings.

Connect to the Windows Subsystem for Android™️for

debugging
To connect to the Windows Subsystem for Android™️VM for debugging:

1. Launch an Android app that was installed using the Amazon Appstore.

2. You can connect using adb connect with the following command (you must have
adb installed ):

PowerShell

adb connect 127.0.0.1:58526

Connect to a test device
To connect to a test device (with Windows Subsystem for Android™️installed) on the
same network from Windows/Mac:

1. On the test device (where Windows Subsystem for Android™️is installed) open a
PowerShell window and identify the IP address of the test device by running the
command:

PowerShell

ipconfig

2. Using the debugging device terminal where Android Studio and the Android SDK
is installed (Mac/Windows), enter the command:

Console

adb connect <TEST DEVICE IP ADDRESS>:58526

The <TEST DEVICE IP ADDRESS> can be found in the output of "ipconfig" from the test
device. You can also deploy and debug apps from Android Studio.

To use Android Debug Bridge (ADB) to connect your development workstation directly
to your Android device so you can install packages and evaluate changes, see Android
Debug Bridge in the Android Open Source Project docs .

Debug your app

While apps should be installed using the Amazon Appstore, debugging an Android app
on a Windows device is possible using an APK (Android application package) and adb
(Android Debug Bridge).

To debug an APK using adb:

1. Follow the steps to connect to the Windows Subsystem for Android™️VM above.

2. Install the APK using the adb install command: adb install app-debug.apk

Expected Output:

PowerShell
 Performing Streamed Install
Success

3. A successful “app installed” notification will appear in the Windows notification

menu and the app will launch once selected.

Building Universal APKs

Windows Subsystem for Android™️utilizes Intel Bridge Technology to enable Arm
applications on x86 based processors. Arm applications will run on Arm-based
processors natively. The emulation layer will induce a performance overhead – for
optimal performance, submit your application for both the x86-64 and Arm64
architectures.

Input compatibility considerations for Windows

devices
There are a few unique input behaviors to consider that will likely require updates to
your Android app code, designed for handheld devices, to be compatible when running
on a Windows desktop device via the Amazon Appstore.

Keyboard input
For text input fields handled by an on-screen virtual keyboard input method (or IME),
such as EditText , apps should behave as expected. (EditText class in the Android
docs ).

For keystrokes that cannot be anticipated by the framework, apps will need to handle
the behavior themselves. If this is already implemented in-app, no extra work is
required.

As an example, some games may already support movement facilitated via keyboard,
through w a s d keys, alongside touch input.

The following are keyboard inputs that developers should consider code updates for
when building for Windows 11 devices:

Enter Key
Arrow-key and Tab-key Navigation
Change Selected Item Highlight Color
 Ctrl-based Shortcuts

Learn more about how to optimize for these keyboard input scenarios on desktop
devices by following the Android documentation:

Input compatibility guide in the Android docs

Handle keyboard input guide in the Android docs
Use touch gestures guide in the Android docs

Mouse input
Developers should consider updating code for the following mouse inputs when
building for Windows devices:

Right Click
Tooltips / Hover Text
Hover Effects
Mouse Scroll Wheel Action
Drag and Drop

Mouse input, similar to keyboard input, must follow the official Android app guidelines.
This means using the InputDevice class paired with the SOURCE_MOUSE constant. Learn
more about how to optimize for these mouse input scenarios on desktop devices by
following the Android documentation:

Input compatibility guide in the Android docs

InputDevice reference in the Android docs
SOURCE_MOUSE reference in the Android docs

Window management and resizing

Unlike traditional mobile form factors, Android apps running on Windows 11 can be
freely resized, should be responsive in their resizing, and can be snapped using
Windows actions/gestures.

Minimum screen requirement

Windows 11 enforces a minimum screen requirement of 720p resolution (1280x720)
with a >9” screen.

Letter & pillar boxing

When the aspect ratio of a window size does not align between the device screen sizes
that window is being displayed on, the result may be Letterboxing (the window is wider
than it is high, or horizontally longer) or Pillarboxing (the window is more narrow than it
is wide, or vertically longer). The result is bars being placed on the sides of the window
in order to center it. These bars may be light- or dark-themed depending on the system
settings selected. This will only occur as necessary when the Android app is snapped or
maximized, allowing Android apps to take advantage of the rich snapping features in
Windows and integrate into the windowing model.

Additional resizing considerations

The following should also be considered when updating an Android app to run on a
Windows 11 device with respect to window management and resizing:

Initial launch size

Window dimensions
Content bounds
Free form resizing
Screen Orientation

Learn more about how to optimize for window resizing scenarios on desktop devices by
following the Window Management guide in the Android docs .

Application Lifecycle Events

Developing Android applications for a multi-window environment has an impact on the
lifecycle events that you choose to utilize in your application. While overriding the
onPause event may achieve the results you’d like on a phone or tablet, it’s typically the

wrong event to use if you’re changing your app’s UX.

See the Android documentation for a description of the lifecycle events. More often
than not, you’ll want to use the onStop event and not the onPause or onUserLeaveHint
events. In fact, many multi-window Android implementations do not deliver the
onUserLeaveHint notification, and thus any business critical logic that might be in that
event handler will not be called on these platforms, including Windows Subsystem for
Android™️.

VM lifecycle considerations
Windows Subsystem for Android™️utilizes a virtual machine (VM) which provides
compatibility with the AOSP framework and devices like keyboards, mice, touch, pen,
etc.

There are three possible states for the VM running apps with Windows Subsystem for
Android™️:

1. Running
2. Lightweight Doze: Activated after no app activity for 3 minutes. Deactivated by
user activity or an app notification.
3. Not Running: Activated after no app activity for 7 minutes.

Transitions between these states are triggered by user activity, such as launching or
interaction with the Android app or an app notification. Android apps are paused and
then stopped when their window is minimized.

VM Properties
The properties for the Windows Subsystem for Android™️VM are listed below.
Hardcoding these values is not recommended as that could cause future
incompatibilities.

ﾉ Expand table
 Property Value

Build.MANUFACTURER Microsoft Corporation

Build.MODEL Subsystem for Android(TM)

Build.VERSION.SDK_INT 33

Build.BOARD windows

Redirect to Windows apps

Windows Subsystem for Android™️automatically redirects intents for files and common
URI schemes to the corresponding Windows default file/protocol handler (if multiple
intent filters match, users see a "Windows default app" option in the chooser dialog).
Supported file intents include ACTION_VIEW , ACTION_EDIT , ACTION_SEND , and
ACTION_SEND_MULTIPLE , which copy the file to the Windows Downloads folder
before opening it. Supported URI intents include ACTION_VIEW for the http/https
schemes and ACTION_VIEW and ACTION_SENDTO for the mailto scheme.

Android apps can also manually redirect to Windows apps using custom URI schemes.
Set the intent action to com.microsoft.windows.LAUNCH_URI and add a string extra to the
intent named com.microsoft.windows.EXTRA_URI with the custom URI as the value. For
example, to launch the Windows Calculator app from an Android app (Java):

Java

Intent intent = new Intent("com.microsoft.windows.LAUNCH_URI");

intent.putExtra("com.microsoft.windows.EXTRA_URI", "ms-calculator:");

try {
startActivity(intent);
} catch (ActivityNotFoundException e) {
// Not running in Windows Subsystem for Android™️(or running on an older
build that did not contain this feature).
}

Security
Both Windows kernel-mode drivers and Windows applications running at medium
integrity level (IL) can inspect arbitrary Android containers and Android app memory.
There are no plans to add detection for cheats/macro/bot/suspicious behaviors
detection in the short-term.
Developers querying getSecurityLevel will get SECURITY_LEVEL_SW_SECURE_CRYPTO . Learn
more about getSecurityLevel in the Android API Reference guide .

Uninstalling Windows Subsystem for Android™️

You can uninstall the Windows Subsystem for Android™️, but note that all associated
apps will also be uninstalled.

Uninstalling the Amazon Appstore will uninstall the Windows Subsystem for
Android™️and all other Android apps.
Uninstalling an Amazon Appstore app will only uninstall the app (same behavior as
Windows apps).
Uninstalling the Windows Subsystem for Android™️will uninstall the Amazon
Appstore and all Android apps.

Troubleshooting issues
If you encounter issues specific to the Amazon Appstore on Windows, try the following
troubleshooting steps:

1. Select Windows search from the Windows task bar.

2. Search for “Amazon Appstore” and right-click on the Amazon Appstore icon.
3. Select “App Settings” in the dropdown options.
4. Select “Storage and Cache” and click both “Clear Storage” and “Clear cache”.
5. Go back and select “Force Stop”.
6. Close the Amazon Appstore Settings window.
7. Relaunch the Amazon Appstore.

For further troubleshooting steps relating to the Windows Subsystem for Android™️
Settings app or to leave feedback using Feedback Hub, see Troubleshooting and FAQ for
mobile apps on Windows .

For any other developer questions and support, use the Windows Subsystem for
Android™️tag on Microsoft Q&A.

Additional resources
Apps from the Amazon Appstore
Accessibility on Windows Subsystem for Android™️
６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Release Notes for Windows Subsystem
for Android™️
Article • 03/05/2024

） Important

Windows Subsystem for Android™️and the Amazon Appstore will no longer be

available in the Microsoft Store after March 5, 2025. Learn more.

These release notes are based on updates to the Windows Subsystem for Android™️. For
basic information on how to install and run Android™️apps on Windows, see the
Support article: Installing the Amazon Appstore and Android™️Apps .

Build 2304.40000.3.0
June 1, 2023

Package verification for apps on WSA: Android apps are scanned using anti-virus
software installed on Windows prior to app installation.
Ability for users to configure how much memory to assign to Android
Android apps will be launched when a user opens the supported app link from any
app (Android AppLink support)
Linux kernel updated to 5.15.94
Improvements to platform reliability and performance

Build 2303.40000.3.0
April 11, 2023

Picture-in-picture mode now supported

A new "Partially running" system setting added to WSA Settings app, which runs
the subsystem with minimal resources but apps launch quicker than "As needed"
mode
Linux kernel updated to 5.15.78
Improvements to platform reliability
Android 13 security updates

Build 2302.4000
March 15, 2023

Stability improvements to graphics card selection

Updates to the Windows Subsystem for Android Settings app to include
performance options for graphics cards
Docking and undocking with external monitors issues fixed with the subsystem
Fixes to apps with audio buffer issues
Android 13 security updates

Build 2301.40000.4.0
February 9, 2023

Improved audio input latency and reliability

Improvements to camera experience (camera metadata now exposed to camera
apps)
Improvements to framerate performance: certain benchmarks have improved by
10%-20% on ARM and 40%-50% on x64
Fixed zooming out in apps using touchpad or mouse
Improvements to platform reliability
Using latest Chromium WebView to version 108
Synchronizing global microphone and camera privacy toggles between Windows
and Android apps
Android 13 security updates

Build 2211.40000.11.0
January 10, 2023

Windows Subsystem for Android updated to Android 13

Improvements in boot performance
Improvements to mouse click input
Improvements in clipboard stability
Improvements to application resizing
Reliability improvements to media files opening in Windows
Jumplist entries for applications supporting app shortcuts

Build 2210.40000.7.0
November 17, 2022
 Enhancement of audio recording quality
Enhancement of OAuth scenarios
Support for MPEG2 decoding
Improvements to the camera experience when the device is not equipped with a
camera
Improvements in input reliability
Chromium update to 106

Build 2209.40000.26.0
October 20, 2022

Improvements to the Camera HAL

Improvements to clipboard stability
Improvements to multi-threaded (>8 core) performance
Improved security for graphic streaming
Reliability improvements for package launches
Security updates for ANGLE and GSK
Annotated telemetry with package installation sources
Window with legal information has been fixed
Security updates to the Linux kernel
Enhancements to platform stability
Updated to Chromium WebView 105

Build 2208.40000.4.0
September 15, 2022

Reliability fixes for App Not Responding (ANR) errors

Improvements to input compatibility shims
Improvements to scrolling (smoothness) in apps
Usability Improvements to the Windows Subsystem for Android Settings app
Startup performance improvements
Fixed crashes when copying and pasting extremely large content
UX improvements for the game controls dialog
Improvements to networking
General graphics improvements
Improvements for gamepad when using multiple apps
Improved performance of uninstalling apps
Fixed video playback issue for apps
Updated to Chromium WebView 104
 Linux kernel security updates

Build 2207.40000.8.0
August 31, 2022

New compatibility shim to allow apps to maintain aspect ratio but still support
resize
Accessibility improvements to the Windows Subsystem for Android Settings app
New compatibility shims in the Windows Subsystem for Android Settings app
Fixed problems with restarting apps
Apps that update toast notifications instead of using progress toasts have better
behavior
Game controls user education dialog for apps with compatibility shims enabled
Improvements with handling VPN
Scrollbar fix for Windows Subsystem for Android Settings compatibility page
User crash data and system app crash data is now being reported
“No internet available” toast notification is now suppressed
Custom Android toasts now render correctly
Amazon Appstore 60.09 update
Android security update
Improved reliability

Build 2206.40000.15.0
August 2, 2022

New suite of shims available to toggle in the Windows Subsystem for Android
Settings app which enables better experiences in several apps
Compatibility for games with joysticks (mapped to WASD)
Compatibility for gamepad in games
Compatibility for aiming in games with arrow keys
Compatibility for sliding in games with arrow keys
Scrolling improvements
Networking improvements
Android minimum window size defaulted to 220dp
Improved dialog when unsupported VPN is detected
New toggle to view/save diagnostic data in the Windows Subsystem for Android
Settings app
Security updates
General reliability fixes, including improvements to diagnostic sizes
 Graphics improvements

Build 2205.40000.14.0
July 6, 2022

Enabled Advanced Networking functionality, including app access to local network

devices for ARM
VM IP address removed from Settings app. With Advanced Networking, now the IP
address of the VM is the same as the host/computer IP
Fixes for non-resizable app content on maximize or resizing
Fixes for scrolling with mouse and trackpad in apps
Android May Kernel patches
Android windows marked secure can no longer be screenshotted
Improve web browser launching
Enable doze and app standby while charging for improved power saving
ADB debug prompts redirected to Windows for improved security
Updated to Chromium WebView 101
Fixes for graphics including app flickering and graphics corruption
Fixes for video playback
AV1 Codec support
Enabled IPv6 and VPN Connectivity
Increased the performance and reliability connecting to virtual WIFI in the
container
Video playback apps can now prevent the screen from turning off in Windows

Known Issues:

Some VPNs may not work with Advanced Networking. If you use a VPN and find
Android apps do not have network connectivity, please disable Advanced
Networking in the Windows Subsystem for Android Settings app

Build 2204.40000.19.0
May 20, 2022

Windows Subsystem for Android updated to Android 12.1

Advanced networking on by default for newer x64 Windows builds
Updated Windows Subsystem for Android Settings app: redesigned UX and
diagnostics data viewer added
 Simpleperf CPU profiler recording now works with Windows Subsystem for
Android
Windows taskbar now shows which Android apps are using microphone and
location
Improvements to Android app notifications appearing as Windows notifications
Reduced flicker when apps are restored from minimized state
Apps are not restarted when devices come out of connected standby on recent
Windows builds
New video hardware decoding (VP8 and VP9)
Fixes for on-screen keyboard in apps
Fixes for full screen Android apps and auto-hidden Windows taskbar
Windows Subsystem for Android updated with Chromium WebView 100
Added support for Android NetworkLocationProvider in addition to
GpsLocationProvider
Improved general stability, performance, and reliability

Known Issues:

Instability with camera on ARM devices

Instability printing via Android apps
Some apps rendered at lower resolutions may lay out incorrectly
Some VPNs may not work with Advanced Networking. If you use a VPN and find
Android apps do not have network connectivity, please disable Advanced
Networking in the Windows Subsystem for Android Settings app
Some apps that were previously available might be missing from the experience,
fail to launch, or function incorrectly for various known issues. We’re working with
our partners to address these issues as soon as possible.

Build 2203.40000.3.0
March 22, 2022.

H.264 Video Hardware Decoding

Networking changes enabling future improvements in the platform
Mail Integration with Windows email clients and Android apps
Disabled force-enabling MSAA (Multisample anti-aliasing)
Improved scrolling in the Amazon Appstore and Kindle apps

Known Issues:

Video playback in some apps may be choppy on certain systems.

Coming out of connected standby, apps may be restarted.
Public Preview Build 1.8.32837.0
February 15, 2022. Windows Subsystem for Android is available for public preview.

General improvements to performance and reliability

Full screen support for apps (via F11)
Taking pictures with camera metadata and encoding fixed
Improvements to the OAuth experience
Improved screen reader support for the Amazon Appstore
Fix for issue with file attachments not displaying an email dialog correctly
When Windows Subsystem for Android™️Settings subsystem resources are
configured for continuous mode, the subsystem will restart at Windows boot up
Windows Subsystem for Android™️Settings App now includes the ability to choose
GPU
Copy and paste clipboard reliability improvements
Fixes to camera rotation and aspect ratio
Fixes for onscreen keyboard in apps

Known Issues:

Apps coming out of modern standby may encounter issues

Performance may vary when running multiple concurrent apps

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Windows Subsystem for Android™️
Preview Program
Article • 06/07/2023

） Important

Windows Subsystem for Android™️and the Amazon Appstore will no longer be

available in the Microsoft Store after March 5, 2025. Learn more.

The Windows Subsystem for Android™️Preview Program allows users to receive early-
preview builds of the Windows Subsystem for Android™ and Amazon Appstore on
Windows. Installing the Amazon Appstore on Windows automatically installs Windows
Subsystem for Android™️. Learn more about installing the Amazon Appstore .

７ Note

This program is separate from the Windows Insider Program and only enrolls your
account into receiving preview builds of Windows Subsystem for Android™️.

Preview builds may not always be stable and users may encounter issues that block apps
or require workarounds. Visit Troubleshooting and FAQ for mobile apps on Windows
to find help and information on how to leave feedback using Windows Feedback Hub.
Your feedback will be useful in improving the quality of Windows Subsystem for
Android™️.

Please note that the Windows Subsystem for Android™ may be substantially modified
before it’s public release. Microsoft makes no warranties, express or implied, with
respect to the information provided here. Microsoft respects your privacy:

Microsoft Privacy Statement

Microsoft Global Data Privacy Notice .

Prerequisites
Windows Subsystem for Android™️is available on Windows 11.

Your device must meet specific requirements. Install mobile apps and the Amazon
Appstore: Device requirements .
 You must have the Amazon Appstore installed on your Windows 11 device to
participate in the preview. An Amazon account is also required to download
mobile apps from the Amazon Appstore.
Windows Subsystem for Android™️is currently available in select countries and
regions .

Sign Up
You will need a Microsoft Account (MSA) email address that you use to sign in to the
Microsoft Store. If you do not yet have a Microsoft Account, create an account here .

Sign Up for Preview Program

Once you submit your MSA email, you will see a confirmation that you have joined the
program and receive a confirmation email. You will be added to a special app flight ring
to receive Windows Subsystem for Android™️preview updates. These updates will be
pushed to the Amazon Appstore that you previously installed via the Microsoft Store
(see prerequisites). This may take up to 7 days before you begin receiving updates.

Opt Out
If you have previously joined the program and would like to stop receiving preview
builds, you can opt out using the form linked below. After opting out of the program,
you will receive a confirmation email. It may take up to 7 days before you are no longer
in the preview program and return to receiving the general public builds. Opting out of
this program will not opt your account out of the Windows Insider Program.

Opt out of the Preview Program

Share your feedback

If you run into an issue while using Windows Subsystem for Android™️or your Amazon
Appstore installation, select Windows key + F to launch Feedback Hub and Use the
category Apps > Windows Subsystem for Android™️. Provide as many details as
possible regarding the issue to help us diagnose and resolve the problem. For more
details: Troubleshooting and FAQ .
６ Collaborate with us on Windows developer
GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Get started with native Android
development on Windows
Article • 07/13/2021

This guide will get you started using Windows to create native Android applications. If
you would prefer a cross-platform solution, see Overview of Android development on
Windows for a brief summary of some options.

The most straight-forward way to create a native Android app is using Android Studio
with either Java or Kotlin, though it is also possible to use C or C++ for Android
development if you have a specific purpose. The Android Studio SDK tools compile your
code, data, and resource files into an archive Android package, .apk file. One APK file
contains all the contents of an Android app and is the file that Android-powered devices
use to install the app.

Install Android Studio

Android Studio is the official integrated development environment for Google's Android
operating system. Download the latest version of Android Studio for Windows .

If you downloaded an .exe file (recommended), double-click to launch it.

If you downloaded a .zip file, unpack the ZIP, copy the android-studio folder into
your Program Files folder, and then open the android-studio > bin folder and
launch studio64.exe (for 64-bit machines) or studio.exe (for 32-bit machines).

Follow the setup wizard in Android Studio and install any SDK packages that it
recommends. As new tools and other APIs become available, Android Studio will notify
you with a pop-up, or check for updates by selecting Help > Check for Update.

Create a new project

Select File > New > New Project.

In the Choose your project window, you will be able to choose between these
templates:

Basic Activity: Creates a simple app with an app bar, a floating action button and
two layout files: one for the activity and one to separate out text content.
 Empty Activity: Creates an empty activity and a single layout file with sample text
content.

Bottom Navigation Activity: Creates a standard bottom navigation bar for an

activity. For more information on this, see the Bottom Navigation Component
section of the Material Design guidelines by Google.

Templates are commonly used to add activities to new and existing app modules.
For example, to create a login screen for your app's users, add an activity with the
Login Activity template. To learn more about selecting an activity and how to add
code from a template, see Android Developer guide by Google.

７ Note

The Android operating system is based on the idea of components and uses the
terms activity and intent to define interactions. An activity represents a single,
focused task that a user can do. An activity provides a window for building the user
interface using classes based on the View class. There is a lifecycle for activities in
the Android operating system, defined by six callbacks: onCreate() , onStart() ,
onResume() , onPause() , onStop() , and onDestroy() . The activity components

interact with one another using intent objects. Intent either defines the activity to
start or describes the type of action to perform (and the system selects the
appropriate activity for you, which can even be from a different application). Learn
more about Activities, the Activity Lifecycle, and Intents in the Android Developer
guide by Google.

Java or Kotlin
Java became a language in 1991, developed by what was then Sun Microsystems, but
which is now owned by Oracle. It has become one of the most popular and powerful
programming languages with one of the largest support communities in the world. Java
is class-based and object-oriented, designed to have as few implementation
dependencies as possible. The syntax is similar to C and C++, but it has fewer low-level
facilities than either of them.

Kotlin was first announced as a new open-source language by JetBrains in 2011 and has
been included as an alternative to Java in Android Studio since 2017. In May 2019,
Google announced Kotlin as it's preferred language for Android app developers, so
despite being a newer language, it also has a strong support community and has been
identified as one of the fastest growing programming languages. Kotlin is cross-
platform, statically typed, and designed to interoperate fully with Java.
Java is more widely used for a broader range of applications and offers some features
that Kotlin does not, such as checked exceptions, primitive types that are not classes,
static members, non-private fields, wildcard-types, and ternary-operators. Kotlin is
specifically designed for and recommended by Android. It also offers some features that
Java does not, such as null references controlled by the type system, no raw types,
invariant arrays, proper function types (as opposed to Java's SAM-conversions), use-site
variance without wildcards, smart casts, and more. Find a more in-depth look at the
comparison to Java in the Kotlin documentation .

Minimum API Level

You will need to decide the minimum API level for your application. This determines
which version of Android your application will support. Lower API levels are older and
therefore generally support more devices, but higher API levels are newer and therefore
provide more features.

Select the Help me choose link to open a comparison chart showing the device support
distribution and key features associated with the platform version release.

Instant app support and Androidx artifacts

You may notice a checkbox to Support instant apps and another to Use androidx
artifacts in your project creation options. The instant apps support is not checked and
the androidx is checked as the recommended default.
Google Play Instant apps provide a way for people to try an app or game without
installing it first. These instant apps can be surfaced across the Play Store, Google
Search, social networks, and anywhere you share a link. By checking the Support instant
apps box, you are asking Android Studio to include the Google Play Instant
Development SDK with your project. Learn more about Google Play Instant apps in the
Android developer guide .

AndroidX artifacts represents the new version of the Android support library and
provides backwards-compatibility across Android releases. AndroidX provides a
consistent namespace starting with the string androidx for all available packages.

７ Note

AndroidX is now the default library. To uncheck this box and use the previous
support library requires removing the lastest Android Q SDK. See Uncheck use
Androidx artifacts on StackOverflow for instructions, but first note that the
former Support Library packages have been mapped into corresponding androidx.*
packages. For a full mapping of all the old classes and build artifacts to the new
ones, see Migrating to AndroidX .

Project files
The Android Studio Project window, contains the following files (be sure that the
Android view is selected from the drop-down menu):

app > java > com.example.myfirstapp > MainActivity

The main activity and entry point for your app. When you build and run your app, the
system launches an instance of this Activity and loads its layout.

app > res > layout > activity_main.xml

The XML file defining the layout for the activity's user interface (UI). It contains a
TextView element with the text "Hello World"

app > manifests > AndroidManifest.xml

The manifest file describing the fundamental characteristics of the app and each of its
components.

Gradle Scripts > build.gradle

There are two files with this name: "Project: My First App", for the entire project, and
"Module: app", for each app module. A new project will initially only have one module.
Use the module's build.file to control how the Gradle plugin builds your app. Learn more
about how to configure your build in the Android developer guide .

Use C or C++ for Android game development

The Android operating system is designed to support applications written in Java or
Kotlin, benefiting from tooling embedded in the system's architecture. Many system
features, like Android UI and Intent handling, are only exposed through Java interfaces.
There are a few instances where you may want to use C or C++ code via the Android
Native Development Kit (NDK) despite some of the associated challenges. Game
development is an example, since games typically use custom rendering logic written in
OpenGL or Vulkan and benefit from a wealth of C libraries focused on game
development. Using C or C++ might also help you squeeze extra performance out of a
device to achieve low latency or run computationally intensive applications, such as
physics simulations. The NDK is not appropriate for most novice Android
programmers however. Unless you have a specific purpose for using the NDK, we
recommend sticking with Java, Kotlin, or one of the cross-platform frameworks.

To create a new project with C/C++ support:

In the Choose your project section of the Android Studio wizard, select the Native
C++* project type. Select Next, complete the remaining fields, then select Next
again.

In the Customize C++ Support section of the wizard, you can customize your
project with the C++ Standard field. Use the drop-down list to select which
standardization of C++ you want to use. Selecting Toolchain Default uses the
default CMake setting. Select Finish.

Once Android Studio creates your new project, you can find a cpp folder in the
Project pane that contains the native source files, headers, build scripts for CMake
or ndk-build, and prebuilt libraries that are a part of your project. You can also find
a sample C++ source file, native-lib.cpp , in the src/main/cpp/ folder which
provides a simple stringFromJNI() function returning the string "Hello from C++".
Additionally, you should see a CMake build script, CMakeLists.txt , in your
module's root directory required for building your native library.

To learn more, about adding C and C++ code to your project, see the Android
developer guide . To find Android NDK samples with C++ integration, see the Android
NDK samples repo on GitHub. To compile and run a C++ game on Android, use the
Google Play Game services API .

Design guidelines
Device users expect applications to look and behave a certain way... whether swiping or
tapping or using voice-controls, users will hold specific expectations for what your
application should look like and how to use it. These expectations should remain
consistent in order to reduce confusion and frustration. Android offers a guide to these
platform and device expectations that combines the Google Material Design foundation
for visual and navigational patterns, along with quality guidelines for compatibility,
performance, and security.

Learn more in the Android design documentation .

Fluent Design System for Android

Microsoft also offers design guidance with the goal of providing a seamless experience
across the entire portfolio of Microsoft's mobile apps.

Fluent Design System for Android design and build custom apps that are natively
Android while still uniquely Fluent.

Sketch toolkit
Figma toolkit
Android font
Android User Interface Guidelines
Guidelines for Android app icons

Additional resources
Android Application Fundamentals

Develop Dual-screen apps for Android and get the Surface Duo device SDK

Add Windows Defender exclusions to improve performance

Enable Virtualization support to improve emulator performance

Get started developing for Android
using React Native
Article • 06/28/2023

This guide will help you to get started using React Native on Windows to create a cross-
platform app that will work on Android devices.

Overview
React Native is an open-source mobile application framework created by Facebook. It
is used to develop applications for Android, iOS, Web and UWP (Windows) providing
native UI controls and full access to the native platform. Working with React Native
requires an understanding of JavaScript fundamentals.

Get started with React Native by installing

required tools
1. Install Visual Studio Code (or your code editor of choice).

2. Install Android Studio for Windows . Android Studio installs the latest Android
SDK by default. React Native requires Android 6.0 (Marshmallow) SDK or later. We
recommend using the latest SDK.

3. Create environment variable paths for the Java SDK and Android SDK:

In the Windows search menu, enter: "Edit the system environment variables",
this will open the System Properties window.
Choose Environment Variables... and then choose New... under User
variables.
Enter the Variable name and value (path). The default paths for the Java and
Android SDKs are as follows. If you've chosen a specific location to install the
Java and Android SDKs, be sure to update the variable paths accordingly.
JAVA_HOME: C:\Program Files\Android\Android Studio\jre\bin
ANDROID_HOME: C:\Users\username\AppData\Local\Android\Sdk
 4. Install NodeJS for Windows You may want to consider using Node Version
Manager (nvm) for Windows if you will be working with multiple projects and
version of NodeJS. We recommend installing the latest LTS version for new
projects.

７ Note

You may also want to consider installing and using the Windows Terminal for
working with your preferred command-line interface (CLI), as well as, Git for
version control . The Java JDK comes packaged with Android Studio v2.2+, but
if you need to update your JDK separately from Android Studio, use the Windows
x64 Installer .

Create a new project with React Native

1. Use npx , the package runner tool that is installed with npm to create a new
React Native project. from the Windows Command Prompt, PowerShell, Windows
Terminal , or the integrated terminal in VS Code (View > Integrated Terminal).

PowerShell

npx react-native init MyReactNativeApp

If you want to start a new project with a specific React Native version, you can use
the --version argument. For information about versions of React Native, see
Versions - React Native .
 PowerShell

npx [email protected] init <projectName> --version X.XX.X

2. Open your new "MyReactNativeApp" directory:

PowerShell

cd MyReactNativeApp

3. If you want to run your project on a hardware Android device, connect the device
to your computer with a USB cable.

4. If you want to run your project on an Android emulator, you shouldn't need to
take any action as Android Studio installs with a default emulator installed. If you
want to run your app on the emulator for a particular device. Click on the AVD
Manager button in the toolbar.

5. To run your project, enter the following command. This will open a new console
window displaying Node Metro Bundler.

PowerShell

npx react-native run-android

 ７ Note

If you are using a new install of Android Studio and haven't yet done any
other Android development, you may get errors at the command line when
you run the app about accepting licenses for the Android SDK. Such as
"Warning: License for package Android SDK Platform 29 not accepted." To

resolve this, you can click the SDK Manager button in Android Studio .
Or, you can list and accept the licenses with the following command, making
sure to use the path to the SDK location on your machine.

PowerShell

C:\Users\[User Name]\AppData\Local\Android\Sdk\tools\bin\sdkmanager --
licenses

6. To modify the app, open the MyReactNativeApp project directory in the IDE of your
choice. We recommend VS Code or Android Studio.
7. The project template created by react-native init uses a main page named
App.js . This page is pre-populated with a lot of useful links to information about
React Native development. Add some text to the first Text element, like the "HELLO
WORLD!" string shown below.

JavaScript

<Text style={styles.sectionDescription}>
Edit <Text style={styles.highlight}>App.js</Text> to change this
screen and then come back to see your edits. HELLO WORLD!
</Text>

8. Reload the app to show the changes you made. There are several ways to do this.

In the Metro Bundler console window, type "r".

In the Android device emulator, double tap "r" on your keyboard.
On a hardware android device, shake the device to bring up the React Native
debug menu and select `Reload'.
Additional resources
Develop Dual-screen apps for Android and get the Surface Duo device SDK

Add Windows Defender exclusions to improve performance

Enable Virtualization support to improve Emulator performance

Get started developing a PWA or Hybrid
web app for Android
Article • 05/24/2022

This guide will help you to get started creating a hybrid web app or Progressive Web
App (PWA) on Windows using a single HTML/CSS/JavaScript codebase that can be used
on the web and across device platforms (Android, iOS, Windows).

By using the right frameworks and components, web-based applications can work on an
Android device in a way that looks to users very similar to a native app.

Features of a PWA or Hybrid web app

There are two main types of web apps that can be installed on Android devices. The
main difference being whether your application code is embedded in an app package
(hybrid) or hosted on a web server (pwa).

Hybrid web apps: Code (HTML, JS, CSS) is packaged in an APK and can be
distributed via the Google Play Store. The viewing engine is isolated from the
users' internet browser, no session or cache sharing.

Progressive Web Apps (PWAs): Code (HTML, JS, CSS) lives on the web and doesn't
need to be packaged as an APK. Resources are downloaded and updated as
needed using a Service Worker. The Chrome browser will render and display your
app, but will look native and not include the normal browser address bar, etc. You
can share storage, cache, and sessions with the browser. This is basically like
installing a shortcut to the Chrome browser in a special mode. PWAs can also be
listed in the Google Play Store using Trusted Web Activity.

PWAs and hybrid web apps are very similar to a native Android app in that they:

Can be installed via the App Store (Google Play Store and/or Microsoft Store)
Have access to native device features like camera, GPS, Bluetooth, notifications,
and list of contacts
Work Offline (no internet connection)

PWAs also have a few unique features:

Can be installed on the Android home screen directly from the web (without an
App Store)
 Can additionally be installed via the Google Play Store using a Trusted Web
Activity
Can be discovered via web search or shared via a URL link
Rely on a Service Worker to avoid the need to package native code

You don't need a framework to create a Hybrid app or PWA, but there are a few popular
frameworks that will be covered in this guide, including PhoneGap (with Cordova) and
Ionic (with Cordova or Capacitor using Angular or React).

Apache Cordova
Apache Cordova is an open-source framework that can simplify the communication
between your JavaScript code living in a native WebView and the native Android
platform by using plugins . These plugins expose JavaScript endpoints that can be
called from your code and used to call native Android device APIs. Some example
Cordova plugins include access to device services like battery status, file access,
vibration / ring tones, etc. These features are not typically available to web apps or
browsers.

There are two popular distributions of Cordova:

PhoneGap: Support has been discontinued by Adobe.

Ionic

Ionic
Ionic is a framework that adjusts the user interface (UI) of your app to match the
design language of each platform (Android, iOS, Windows). Ionic enables you to use
either Angular or React .

７ Note

There is a new version of Ionic that uses an alternative to Cordova, called

Capacitor . This alternative uses containers to make your app more web-
friendly .

Get started with Ionic by installing required tools

To get started building a PWA or hybrid web app with Ionic, you should first install the
following tools:
 Node.js for interacting with the Ionic ecosystem. Download NodeJS for Windows
or follow the NodeJS installation guide using Windows Subsystem for Linux (WSL).
You may want to consider using Node Version Manager (nvm) if you will be
working with multiple projects and version of NodeJS.

VS Code for writing your code. Download VS Code for Windows . You may also
want to install the WSL Remote Extension if you prefer to build your app with a
Linux command line.

Windows Terminal for working with your preferred command-line interface (CLI).
Install Windows Terminal from Microsoft Store .

Git for version control. Download Git .

Create a new project with Ionic Cordova and

Angular
Install Ionic and Cordova by entering the following in your command line:

Bash

npm install -g @ionic/cli cordova

Create an Ionic Angular app using the "Tabs" app template by entering the command:

Bash

ionic start photo-gallery tabs

Change into the app folder:

Bash

cd photo-gallery

Run the app in your web browser:

Bash

ionic serve
For more information, see the Ionic Cordova Angular docs . Visit the Making your
Angular app a PWA section of the Ionic docs to learn how to move your app from
being a hybrid to a PWA.

Create a new project with Ionic Capacitor and

Angular
Install Ionic and Cordova-Res by entering the following in your command line:

Bash

npm install -g @ionic/cli native-run cordova-res

Create an Ionic Angular app using the "Tabs" app template and adding Capacitor by
entering the command:

Bash

ionic start photo-gallery tabs --type=angular --capacitor

Change into the app folder:

Bash

cd photo-gallery

Add components to make the app a PWA:

Bash

npm install @ionic/pwa-elements

Import @ionic/pwa-elements by add the following to your src/main.ts file:

TypeScript

import { defineCustomElements } from '@ionic/pwa-elements/loader';

// Call the element loader after the platform has been bootstrapped
defineCustomElements(window);

Run the app in your web browser:

 Bash

ionic serve

For more information, see the Ionic Capacitor Angular docs . Visit the Making your
Angular app a PWA section of the Ionic docs to learn how to move your app from
being a hybrid to a PWA.

Create a new project with Ionic and React

Install the Ionic CLI by entering the following in your command line:

Bash

npm install -g @ionic/cli

Create a new project with React by entering the command:

Bash

ionic start myApp blank --type=react

Change into the app folder:

Bash

cd myApp

Run the app in your web browser:

Bash

ionic serve

For more information, see the Ionic React docs . Visit the Making your React app a
PWA section of the Ionic docs to learn how to move your app from being a hybrid to
a PWA.

Test your Ionic app on a device or emulator

To test your Ionic app on an Android device, plug-in your device (make sure it is first
enabled for development), then in your command line enter:
 Bash

ionic cordova run android

To test your Ionic app on an Android device emulator, you must:

1. Install the required components -- Java Development Kit (JDK), Gradle, and the
Android SDK .

2. Create an Android Virtual Device (AVD): See the [Android developer guide]]
(https://developer.android.com/studio/run/managing-avds.html ).

3. Enter the command for Ionic to build and deploy your app to the emulator: ionic
cordova emulate [<platform>] [options] . In this case, the command should be:

Bash

ionic cordova emulate android --list

See the Cordova Emulator in the Ionic docs for more info.

Additional resources
Develop Dual-screen apps for Android and get the Surface Duo device SDK

Add Windows Defender exclusions to improve performance

Enable Virtualization support to improve emulator performance

Add Microsoft Defender exceptions to
speed up Android build performance
Article • 03/08/2024

This guide covers how to set up exclusions in your Microsoft Defender security settings
in order to improve your build times when developing Android apps using a Windows
machine.

Microsoft Defender Antivirus Overview

In Windows 10, version 1703 and later, the Microsoft Defender Antivirus app is part of
Windows Security. Microsoft Defender aims to keep your PC safe with built-in, real-time
protection against viruses, ransomware, spyware, and other security threats.

However, Microsoft Defender's real-time protection will also dramatically slow file
system access and build speed when developing Android apps.

During the Android build process, many files are created on your computer. With
antivirus real-time scanning enabled, the build process will halt each time a new file is
created while the antivirus scans that file.

Fortunately, Microsoft Defender has the capability to exclude files, project directories, or
file types that you know to be secure from it's antivirus scanning process.

２ Warning

To ensure that your computer is safe from malicious software, you should not
completely disable real-time scanning or your Microsoft Defender antivirus
software. Defining exclusions lowers the protection offered by Defender. You
should always evaluate the risks that are associated with implementing exclusions,
and only exclude files that you are confident are not malicious.

How to add antivirus exclusions to Microsoft

Defender
To add exclusions in the Microsoft Defender Security Center :

1. Select the Windows menu Start button

2. Enter Windows Security
 3. Select Virus and threat protection
4. Select Manage settings under Virus & threat protection settings
5. Scroll to the Exclusions heading and select Add or remove exclusions
6. Select + Add an exclusion. You will then need to choose whether the exclusion you
wish to add is a File, Folder, File type, or Process.

Exclusions to consider for Android

development
Use Microsoft Defender Antivirus exclusions sparingly. See Configure custom exclusions
for Microsoft Defender Antivirus for more details about using exclusions.

Microsoft Defender Antivirus interprets user environment variables in the context of the
system user, using the LocalSystem account, which means it gets information from the
system environment variable, and not from the user environment variable. See Using
incorrect environment variables as wildcards in the file name and folder path or
extension exclusion lists. You can find a list of System environment variables in the
Microsoft Defender for Endpoint documentation. You can also Use wildcards in the file
name and folder path or extension exclusion lists. This explains the use of the asterisk * ,
question mark ? , or environment variables (such as %ALLUSERSPROFILE% ) as wildcards
when defining items in the file name or folder path exclusion list. The way these
wildcards are interpreted differs from their usual usage in other apps and languages.

Microsoft Defender Antivirus expands %USERPROFILE% to

C:\Windows\system32\config\systemprofile , not a wildcard expression applying to all
user profiles. Instead of %USERPROFILE% , for a single user scenario use a pre-expanded
user environment variable. For example: "${env:UserProfile}\AndroidStudioProjects"
or, for the all users scenario, use a wildcard pattern like:
"%SystemDrive%\Users\*\AndroidStudioProjects" to include Android Studio project files.

Additional exclusions you may want to consider include:

Visual Studio dev environment process: devenv.exe

Visual Studio build process: msbuild.exe
JetBrains directory: %LOCALAPPDATA%\JetBrains\<Transient directory (folder)>

For more information on adding antivirus scanning exclusions, including how to

customize directory locations for Group Policy controlled environments, see the
Antivirus Impact section of the Android Studio documentation .

Please remember that adding exclusions lowers the protection offered by Defender. You
should always evaluate the risks that are associated with implementing exclusions, and
only exclude files that you are confident are not malicious.

７ Note

Daniel Knoodle has set up a GitHub repo with recommended scripts to add
Microsoft Defender exclusions for Visual Studio 2017 .

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
Test on an Android device or emulator
Article • 04/29/2024

There are several ways to test and debug your Android application using a real device or
emulator on your Windows machine. We have outlined a few recommendations in this
guide.

Run on a real Android device

To run your app on a real Android device, you will first need to enable your Android
device for development. Developer options on Android have been hidden by default
since version 4.2 and enabling them can vary based on the Android version.

Enable your device for development

For a device running a recent version of Android 9.0+:

1. Connect your device to your Windows development machine with a USB cable. You
may receive a notification to install a USB driver.
2. Open the Settings screen on your Android device.
3. Select About phone.
4. Scroll to the bottom and tap Build number seven times, until You are now a
developer! is visible.
5. Return to the previous screen, select System.
6. Select Advanced, scroll to the bottom, and tap Developer options.
7. In the Developer options window, scroll down to find and enable USB debugging.

Run your app on the device

1. In the Android Studio toolbar, select your app from the run configurations drop-
down menu.
 2. From the target device drop-down menu, select the device that you want to run
your app on.

3. Select Run ▷. This will launch the app on your connected device.

Run your app on a virtual Android device using

an emulator
The first thing to know about running an Android emulator on your Windows machine is
that regardless of your IDE (Android Studio, Visual Studio, etc), emulator performance is
vastly improved by enabling virtualization support.

Enable virtualization support

Before creating a virtual device with the Android emulator, it is recommended that you
enable virtualization by turning on the Hyper-V and Windows Hypervisor Platform
(WHPX) features. This will allow your computer's processor to significantly improve the
execution speed of the emulator.

To run Hyper-V and Windows Hypervisor Platform, your computer must:

Have 4GB of memory available

Have a 64-bit Intel processor or AMD Ryzen CPU with Second Level Address
Translation (SLAT)
Be running Windows 10 build 1803+ (Check your build #)
Have updated graphics drivers (Device Manager > Display adapters > Update
driver)
 If your machine doesn't fit this criteria, you may be able to run Intel HAXM or
AMD Hypervisor . For more info, see the Android Studio Emulator
documentation .

1. Verify that your computer hardware and software is compatible with Hyper-V by
opening a command prompt and entering the command: systeminfo

2. In the Windows search box (lower left), enter "windows features". Select Turn
Windows features on or off from the search results.

3. Once the Windows Features list appears, scroll to find Hyper-V (includes both
Management Tools and Platform) and Windows Hypervisor Platform, ensure that
the box is checked to enable both, then select OK.

4. Restart your computer when prompted.

Emulator for native development with Android Studio

When building and testing a native Android app, we recommend using Android Studio.
Once your app is ready for testing, you can build and run your app by:

1. In the Android Studio toolbar, select your app from the run configurations drop-
down menu.

2. From the target device drop-down menu, select the device that you want to run
your app on.
 3. Select Run ▷. This will launch the Android Emulator .

 Tip

Once your app is installed on the emulator device, you can use Apply Changes to
deploy certain code and resource changes without building a new APK. See the
Android developer guide for more information.

Emulator for cross-platform development with Visual

Studio
There are many Android emulator options available for Windows PCs. We recommend
using the Google Android emulator , as it offers access to the latest Android OS
images and Google Play services.

Android emulator with Visual Studio

Learn more about using the latest version of Visual Studio for Android Development .
Open the latest version of Visual Studio , create a new C++ Android project, set the
platform configuration, run the project, and the default Android Emulator will appear. It
is recommended to use the .NET Multi-platform App UI (MAUI) development workload.
You may need to use the Visual Studio Installer to Modify your workloads.

Additional resources
Develop Dual-screen apps for Android and get the Surface Duo device SDK
 Add Windows Defender exclusions to improve performance

６ Collaborate with us on Windows developer

GitHub feedback
The source for this content can Windows developer is an open
be found on GitHub, where you source project. Select a link to
can also create and review provide feedback:
issues and pull requests. For
more information, see our  Open a documentation issue
contributor guide.
 Provide product feedback
 Microsoft C++, C, and Assembler
documentation
Learn how to use C++, C, and assembly language to develop applications, services, and tools for
your platforms and devices.

DOWNLOAD OVERVIEW
Install Visual Studio and choose Welcome to C++ in Visual
your C++ workloads Studio

GET STARTED W H AT ' S N E W

Get started with Visual Studio What's new for C++ in Visual
and C++ Studio

Get started with C++ and C

Learn to use the Visual Studio IDE Write C++ and C apps in Visual Studio
ｅ Start a guided tour of Visual Studio ｇ Create a console calculator app
ｇ Open code from a repo ｇ Create a Windows Desktop app with Win32
ｇ Write and edit code ｇ Create a Windows Desktop app with MFC
ｇ Build your code ｇ Create a Windows DLL
ｇ Debug your code ｇ Create a static library
ｇ Test your code ｇ Create a .NET component
ｇ Create a Universal Windows Platform app

Use the command-line tools Use C++ and C in Visual Studio Code
ｇ Compile C++ code ｇ Get started with Visual Studio Code
ｇ Compile C code ｇ Install the Microsoft C/C++ extension
ｇ Compile C++/CX ｇ Use Microsoft C/C++ in Windows
ｇ Compile C++/CLI ｇ Use C++ in the Windows Subsystem for Linux
 ｇ Use C++ on Linux
ｇ Use C++ on macOS

Languages and frameworks

C++ C

Microsoft Assembler C++/CX for Windows Runtime

C++/CLI for .NET Active Template Library (ATL)

Microsoft Foundation Classes (MFC) C++/WinRT for Windows Runtime

C++ and C workloads, features, and libraries

Develop for your choice of platforms with Visual Studio tools.

Workloads Features Libraries

Universal Windows Platform Build reliable and secure C++ standard library reference
development programs
C runtime library reference
Windows Desktop Edit and refactor code
MFC and ATL Windows
development
Build code projects Desktop libraries
Linux development
Debug your code Parallel programming libraries
Embedded development
Analyze your code Cloud and networking libraries
Mobile development
Profile app performance Universal Windows Platform
Game development libraries
Port and upgrade code
 Sanitize code for bugs vcpkg package manager

Microsoft Learn Q&A - C++ Team Blog - Twitter - Developer Community - Stack Overflow - How to report an
issue - Suggest a feature - Contribute to C++ docs: Read our contributor guide.
 C# language documentation
The C# guide contains articles, tutorials, and code samples to help you get started with C# and
the .NET platform. Experienced developers can learn about new features in the What's new
section. Experienced developers can learn details of language behavior from the reference and
language specifications.

GET STARTED CONCEPT W H AT ' S N E W

Tour of C# C# What's new in
fundamentals C#

VIDEO TRAINING TRAINING

Learn C# video C# learning Foundational
series paths C# Certification
-…

Learn to program with C#

Major concepts and features of the C# language

Get started with C# C# fundamentals

A tour of C# Type system
Beginner C# tutorials Object oriented programming
Try C# in your browser Functional techniques
Inside a C# program Exceptions
C# for beginners video series Coding style
Foundational C# Certification C# language strategy
 Language concepts Advanced language concepts
Programming concepts Reflection and attributes
LINQ Interface implementations
Asynchronous programming Expression trees
Native interoperability
Performance engineering
.NET compiler platform (roslyn) SDK

C# reference
Read C# language reference material, and the C# language specifications. The C# reference provides an
informative reference for the C# language. The C# language specification is the normative reference for
the C# language. It's the official source for C# language syntax and semantics. Feature specifications
document features not yet incorporated in the standard.

Language reference C# Language reference C# specification

The C# language reference Unsafe code and compiler The official specification for the
provides an informative options C# language
explanation of the C#
language. ｉ Special attributes ｉ Standard and specifications
ｉ Unsafe code ｉ The specification process
ｉ C# language reference
ｉ Preprocessor directives ｉ C# draft standard
ｉ Built-in types
ｉ Compiler options ｉ Feature specifications
ｉ Keywords
ｉ Operators
ｉ Statements
ｉ Special characters
ｉ Documentation comments

Build C# apps with the Visual Studio family

Choose Visual Studio or Visual Studio Code to build your C# applications.

Visual Studio Visual Studio Code

Create your application

You can choose web, mobile, desktop, gaming, IoT, and more.

Web Mobile and Desktop Microservices

ASP.NET Core tutorials Windows Presentation Dapr for .NET developers
Foundation (.NET 5+)
What is ASP.NET Core? Cloud native .NET apps
Windows Forms (.NET 5+)
ASP.NET Core in Visual Studio Serverless apps with Azure
.NET Multi-platform App UI
ASP.NET MVC apps in Architecture for containerized
(.NET MAUI)
Windows containers .NET apps
Develop mobile apps with
Blazor: Interactive client-side Deploy a Worker Service to
Azure
web UI with .NET Azure
Windows Presentation
F# for web development
Foundation (.NET Framework)
Windows Forms (.NET
Framework)

Cloud Machine learning and Game development

AI
Azure for .NET developers Game development with Visual
Build custom AI solutions with Studio
.NET Aspire (Preview)
ML.NET Learn how to use CRYENGINE
Migrate on-premises .NET web
Azure Cognitive Services to build games with C#
apps or services
Azure Machine Learning Build games with C# using the
Azure services for .NET
MonoGame library
developers F# for machine learning
Learn how to use Unity to build
Azure SDK for .NET
2D and 3D games with C#
Deploy Azure resources with
F#

Internet of things (IoT)

 .NET IoT libraries
Get started in 5 minutes
Blink an LED
.NET IoT 101 video series

API and language reference

Search the .NET API and language reference documentation.

.NET API reference .NET Framework API ASP.NET Core API

API reference documentation reference reference
for .NET API reference documentation API reference documentation
for .NET Framework for ASP.NET Core

ML.NET API reference .NET Platform Extensions

API reference documentation API reference
for ML.NET API reference documentation
for .NET Platform Extensions

Are you interested in contributing to the .NET docs? For more information, see our contributor guide.
F# documentation
Learn how to write any application using the F# programming language on .NET.

Learn to program in F#

ｂ GET STARTED

What is F#?

F# strategy

First steps in F#

Install F#

Get started with F# in Visual Studio

Get started with F# in Visual Studio Code

Further learning

ｑ VIDEO

Beginning F# video series

ａ DOWNLOAD

Download the .NET SDK

F# language guide

ｅ OVERVIEW

F# language guide

ｉ REFERENCE

F# language specification

F# RFCs

F# library reference
.NET library reference

F# fundamentals

ｅ OVERVIEW

Overview

Tour of F#

Values

ｐ CONCEPT

Types and inference

Functional concepts

Type providers

ｇ TUTORIAL

Using Functions

Pattern matching

Object programming

Async programming

F# in practice

ｅ OVERVIEW

F# for web development

F# for machine learning

F# for deploying Azure resources

ｄ TRAINING

F# style guide

F# code formatting guidelines

F# coding conventions

F# tools

ｅ OVERVIEW

F# Interactive

F# development tools

F# notebooks

F# for JavaScript

New features in F#

ｈ WHAT'S NEW

What's new in F# 8

What's new in F# 7

What's new in F# 6

What's new in F# 5

What's new in F# 4.7

ｇ TUTORIAL

Explore tasks

Explore interpolated strings

Explore anonymous records

Overview of Docker remote
development on Windows
Article • 09/20/2022

Using containers for remote development and deploying applications with the Docker
platform is a very popular solution with many benefits. Learn more about the variety of
support offered by Microsoft tools and services, including Windows Subsystem for Linux
(WSL), Visual Studio, Visual Studio Code, .NET, and a broad variety of Azure services.

Docker on Windows

Install Docker Desktop for Windows

Find installation steps, system requirements, what's included in the installer, how to
uninstall, differences between stable and edge versions, and how to switch between
Windows and Linux containers.
Get started with Docker
Docker orientation and setup docs with step-by-step instructions on how to get started,
including a video walk-through.

MS Learn course: Introduction to Docker containers

Microsoft Learn offers a free intro course on Docker containers, in addition to a variety
of courses on get started with Docker and connecting with Azure services.
Get started with Docker remote containers on WSL 2
Learn how to set up Docker Desktop for Windows to use with a Linux command line
(Ubuntu, Debian, SUSE, etc) using WSL 2 (Windows Subsystem for Linux, version 2).

VS Code and Docker

Create a Docker container with VS Code
Set up a full-featured dev environment inside of a container with the Remote -
Containers extension and find tutorials to set up a NodeJS container, a Python
container, or a ASP.NET Core container.

Attach VS Code to a Docker container

Learn how to attach Visual Studio Code to a Docker container that is already running or
to a container in a Kubernetes cluster.
Advanced Container Configuration
Learn about advanced setup scenarios for using Docker containers with Visual Studio
Code or read this article on how to Inspect Containers for debugging with VS Code.

Using Remote Containers in WSL 2

Read about using Docker containers with WSL 2 (Windows Subsystem for Linux, version
2) and how to set everything up with VS Code. You can also read about how it works.
Visual Studio and Docker

Docker support in Visual Studio

Learn about the Docker support available for ASP.NET projects, ASP.NET Core projects,
and .NET Core and .NET Framework console projects in Visual Studio, in addition to
support for container orchestration.

Quickstart: Docker in Visual Studio

Learn how to build, debug, and run containerized .NET, ASP.NET, and ASP.NET Core
apps and publish them to Azure Container Registry (ACR), Docker Hub, Azure App
Service, or your own container registry with Visual Studio.
Tutorial: Create a multi-container app with Docker Compose
Learn how to manage more than one container and communicate between them when
using Container Tools in Visual Studio. You can also find links to tutorials like how to Use
Docker with a React Single-page App.

Container Tools in Visual Studio

Find topics covering how to run build tools in a container, debugging Docker apps,
troubleshoot development tools, deploy Docker containers, and bridge Kubernetes with
Visual Studio.
.NET and Docker

.NET Guide: Microservice apps and containers

Intro guide to microservices-based apps managed with containers.
What is Docker?
Basic explanation of Docker containers, including Comparing Docker containers with
Virtual machines and a basic taxonomy of Docker terms and concepts explaining the
difference between containers, images, and registries.

Tutorial: Containerize a .NET app

Learn how to containerize a .NET application with Docker, including creation of a
Dockerfile, essential commands, and cleaning up resources.
Development workflow for Docker apps
Describes the inner-loop development workflow for Docker container-based
applications.

Azure Container Services

Azure Container Instances

Learn how to run Docker containers on-demand in a managed, serverless Azure
environment, includes ways to deploy with Docker CLI, ARM, Azure Portal, create multi-
container groups, share data between containers, connect to a virtual network, and
more.
Azure Container Registry
Learn how to build, store, and manage container images and artifacts in a private
registry for all types of container deployments. Create Azure container registries for your
existing container development and deployment pipelines, set up automation tasks, and
learn how to manage your registries, including geo-replication and best practices.

Azure Service Fabric

Learn about Azure Service Fabric, a distributed systems platform for packaging,
deploying, and managing scalable and reliable microservices and containers.
Azure App Service
Learn how to build and host web apps, mobile back ends, and RESTful APIs in the
programming language of your choice without managing infrastructure. Try the Azure
App Service Learn module to deploy a web app based on a Docker image and configure
continuous deployment.

Learn about more Azure services that support containers .

Docker Containers Explainer Video

https://www.youtube-nocookie.com/embed/0oEsMwSxBsk

Kubernetes and Container Orchestration

Explainer Video
https://www.youtube-nocookie.com/embed/3RTvoI-A7UQ

Containers on Windows
Containers on Windows docs
Package apps with their dependencies and leverage operating system-level
virtualization for fast, fully isolated environments on a single system. Learn about
Windows containers, including quick starts, deployment guides, and samples.

FAQs about Windows containers

Find frequently asked questions about containers. Also see this explanation in
StackOverflow on "What's the difference between Docker for Windows and Docker on
Windows?"
Set up your environment
Learn how to set up Windows 11, Windows 10, or Windows Server to create, run, and
deploy containers, including prerequisites, installing Docker, and working with Windows
Container Base Images.

Create a Windows Server container on an Azure Kubernetes Service (AKS)

Learn how to deploy an ASP.NET sample app in a Windows Server container to an AKS
cluster using the Azure CLI.
 PowerShell Documentation
Official product documentation for PowerShell

GET STARTED DOWNLOAD HOW-TO…

Overview Setup and Sample scripts
installation

DEPLOY REFERENCE ARCHITECTU…

PowerShell PowerShell PowerShell on
Gallery Module GitHub
Browser

PowerShell Editions + Tools

Available editions, tools, and technology that supports PowerShell

PowerShell PowerShell Utility PowerShell DSC

Install PowerShell on modules DSC Overview
Windows PowerShell utility modules DSC 1.1 in Windows
Install PowerShell on Linux Crescendo overview PowerShell
Install PowerShell on macOS PlatyPS overview DSC 2.0
What's new in PowerShell PSScriptAnalyzer overview DSC 3.0 (preview)

SecretManagement DSC Community

overview
 PowerShell Gallery Developer resources Related technologies
PowerShell Gallery Visual Studio Code Quickstart for Azure Cloud
PowerShell Extension Shell
What is the PowerShell
Gallery Using VSCode for remote Azure PowerShell modules
editing and debugging
Best practices Azure Automation runbooks
Windows PowerShell SDK
FAQs Create a PowerShell function
documentation
in Azure
PowerShell SDK API
Windows management
reference
modules

Community Resources
Connect with other PowerShell users

PowerShell Tech
User Groups DSC Community
Community

PowerShell.org StackOverFlow r/PowerShell

PowerShell Slack PowerShell Discord Spiceworks

Digital Art

PowerShell Team
Communicate with the PowerShell team

PowerShell Team Blog PowerShell Community Blog

Official news and announcements
 A place for the community to learn PowerShell and
share insights

PowerShell Team on Twitter GitHub Issues

PowerShell news 280 characters at a time The place for bugs in the current release
Developing with Rust on Windows
Get started developing with Rust using Windows, including setup for your development
environment, Rust for Windows, and code examples.

Overview

ｅ OVERVIEW

What is Rust?

The pieces of the Rust development toolset/ecosystem

Rust for Windows, and the windows crate

Set up your development environment

ｃ HOW-TO GUIDE

Set up your dev environment on Windows for Rust

Tutorials

ｇ TUTORIAL

Hello, world! tutorial (Rust with VS Code)

RSS reader tutorial (Rust for Windows with VS Code)

Additional resources

ｄ TRAINING

The Rust website

Rust documentation for the Windows API

Minesweeper sample app

Overview of developing on Windows
with Rust
Article • 02/22/2022

It's not hard to get started with Rust . If you're a beginner who's interested in learning
Rust using Windows, then we recommend that you follow each detail of this step-by-
step guide. It shows you what to install, and how to set up your development
evironment.

 Tip

If you're already sold on Rust and you have your Rust environment already set up,
and you just want to start calling Windows APIs, then feel free to jump forward to
the Rust for Windows, and the windows crate topic.

What is Rust?
Rust is a systems programming language, so it's used for writing systems (such as
operating systems). But it can also be used for applications where performance and
trustworthiness are important. The Rust language syntax is comparable to that of C++,
provides performance on par with modern C++, and for many experienced developers
Rust hits all the right notes when it comes to compilation and runtime model, type
system, and deterministic finalization.

In addition, Rust is designed around the promise of guaranteed memory safety, without
the need for garbage collection.

So why did we choose Rust for the latest language projection for Windows? One factor
is that Stack Overflow's annual developer survey shows Rust to be the best-loved
programming language by far, year after year. While you might find that the language
has a steep learning curve, once you're over the hump it's hard not to fall in love.

Furthermore, Microsoft is a founding member of the Rust Foundation . The Foundation

is an independent non-profit organization, with a new approach to sustaining and
growing a large, participatory, open source ecosystem.

The pieces of the Rust development

toolset/ecosystem
We'll introduce some Rust tools and terms in this section. You can refer back here to
refresh yourself on any of the descriptions.

A crate is a Rust unit of compilation and linking. A crate can exist in source code
form, and from there it can be processed into a crate in the form of either a binary
executable (binary for short), or a binary library (library for short).
A Rust project is known as a package. A package contains one or more crates,
together with a Cargo.toml file that describes how to build those crates.
rustup is the installer and updater for the Rust toolchain.

Cargo is the name of Rust's package management tool.

rustc is the compiler for Rust. Most of the time, you won't invoke rustc directly;

you'll invoke it indirectly via Cargo.

crates.io ( https://crates.io/ ) is the Rust community's crate registry.

Setting up your development environment

In the next topic, we'll see how to set up your dev environment on Windows for Rust.

Related
The Rust website
Rust for Windows, and the windows crate
Stack Overflow annual developer survey
Rust Foundation
crates.io
Set up your dev environment on Windows for Rust
Set up your dev environment on
Windows for Rust
Article • 08/02/2022

In the Overview of developing on Windows with Rust topic, we introduced Rust and
talked about what it is and what some of its main moving parts are. In this topic, we'll
set up our development environment.

We recommend that you do your Rust development on Windows. However, if you plan
to locally compile and test on Linux, then developing with Rust on the Windows
Subsystem for Linux (WSL) is also an option.

Install Visual Studio (recommended) or the

Microsoft C++ Build Tools
On Windows, Rust requires certain C++ build tools.

You can either download the Microsoft C++ Build Tools , or (recommended) you might
prefer just to install Microsoft Visual Studio .

） Important

Use of the Microsoft C++ Build Tools, or Visual Studio Build Tools, requires a valid
Visual Studio license (either Community, Pro, or Enterprise).

７ Note

We'll be using Visual Studio Code as our integrated development environment

(IDE) for Rust, and not Visual Studio. But you can still install Visual Studio without
expense. A Community edition is available—it's free for students, open-source
contributors, and individuals.

While installing Visual Studio, there are several Windows workloads that we recommend
you select—.NET desktop development, Desktop development with C++, and
Universal Windows Platform development. You might not think that you'll need all
three, but it's likely enough that some dependency will arise where they're required that
we feel it's just simpler to select all three.
New Rust projects default to using Git. So also add the individual component Git for
Windows to the mix (use the search box to search for it by name).

Install Rust
Next, install Rust from the Rust website . The website detects that you're running
Windows, and it offers you 64- and 32-bit installers of the rustup tool for Windows, as
well as instructions on installing Rust to the Windows Subsystem for Linux (WSL).

 Tip

Rust works very well on Windows; so there's no need for you to go the WSL route
(unless you plan to locally compile and test on Linux). Since you have Windows, we
recommend that you just run the rustup installer for 64-bit Windows. Also install
the Microsoft C and C++ (MSVC) toolchain by running rustup default stable-
msvc . You'll then be all set to write apps for Windows using Rust.

When the Rust installer is finished, you'll be ready to program with Rust. You won't have
a convenient IDE yet (we'll cover that in the next section—Install Visual Studio Code).
And you're not yet set up to call Windows APIs. But you could launch a command
prompt ( cmd.exe ), and perhaps issue the command cargo --version . If you see a
version number printed, then that confirms that Rust installed correctly.

If you're curious about the use of the cargo keyword above, Cargo is the name of the
tool in the Rust development environment that manages and builds your projects (more
properly, packages) and their dependencies.

And if you really do want to dive in to some programming at this point (even without
the convenience of an IDE), then you could read the Hello, World! chapter of The Rust
Programming Language book on the Rust website.

Install Visual Studio Code

By using Visual Studio Code (VS Code) as your text editor/integrated development
environment (IDE), you can take advantage of language services such as code
completion, syntax highlighting, formatting, and debugging.

VS Code also contains a built-in terminal that enables you to issue command-line
arguments (to issue commands to Cargo, for example).

1. First, download and install Visual Studio Code for Windows .

2. After you've installed VS Code, install the rust-analyzer extension. You can either
install the rust-analyzer extension from the Visual Studio Marketplace , or you
can open VS Code, and search for rust-analyzer in the extensions menu
(Ctrl+Shift+X).

3. For debugging support, install the CodeLLDB extension. You can either install the
CodeLLDB extension from the Visual Studio Marketplace , or you can open VS
Code, and search for CodeLLDB in the extensions menu (Ctrl+Shift+X).

７ Note

An alternative to the CodeLLDB extension for debugging support is the

Microsoft C/C++ extension. The C/C++ extension doesn't integrate as well
with the IDE as CodeLLDB does. But the C/C++ extension provides superior
debugging information. So you might want to have that standing by in case
you need it.

You can either install the C/C++ extension from the Visual Studio
Marketplace , or you can open VS Code, and search for C/C++ in the
extensions menu (Ctrl+Shift+X).

4. If you want to open the terminal in VS Code, select View > Terminal, or
alternatively use the shortcut Ctrl+` (using the backtick character). The default
terminal is PowerShell.

Hello, world! tutorial (Rust with VS Code)

Let's take Rust for a spin with a simple "Hello, world!" app.
1. First, launch a command prompt ( cmd.exe ), and cd to a folder where you want to
keep your Rust projects.

2. Then ask Cargo to create a new Rust project for you with the following command.

Console

cargo new first_rust_project

The argument you pass to the cargo new command is the name of the project that
you want Cargo to create. Here, the project name is first_rust_project. The
recommendation is that you name your Rust projects using snake case (where
words are lower-case, with each space replaced by an underscore).

Cargo creates a project for you with the name that you supply. And in fact Cargo's
new projects contain the source code for a very simple app that outputs a Hello,
world! message, as we'll see. In addition to creating the first_rust_project project,
Cargo has created a folder named first_rust_project, and has put the project's
source code files in there.

3. So now cd into that folder, and then launch VS Code from within the context of
that folder.

Console

cd first_rust_project
code .

4. In VS Code's Explorer, open the src > main.rs file, which is the Rust source code
file that contains your app's entry point (a function named main). Here's what it
looks like.

Rust

// main.rs
fn main() {
println!("Hello, world!");
}

７ Note

When you open the first .rs file in VS Code, you'll get a notification saying
that some Rust components aren't installed, and asking whether you want to
 install them. Click Yes, and VS Code will install the Rust language server.

You can tell from glancing at the code in main.rs that main is a function definition,
and that it prints the string "Hello, world!". For more details about the syntax, see
Anatomy of a Rust Program on the Rust website.

5. Now let's try running the app under the debugger. Put a breakpoint on line 2, and
click Run > Start Debugging (or press F5). There are also Debug and Run
commands embedded inside the text editor.

７ Note

When you run an app under the CodeLLDB extension and debugger for the
first time, you'll see a dialog box saying "Cannot start debugging because no
launch configuration has been provided". Click OK to see a second dialog box
saying "Cargo.toml has been detected in this workspace. Would you like to
generate launch configurations for its targets?". Click Yes. Then close the
launch.json file and begin debugging again.

6. As you can see, the debugger breaks at line 2. Press F5 to continue, and the app
runs to completion. In the Terminal pane, you'll see the expected output "Hello,
world!".

Rust for Windows

Not only can you use Rust on Windows, you can also write apps for Windows using Rust.
Via the windows crate, you can call any Windows API past, present, and future. There are
more details about that, and code examples, in the Rust for Windows, and the windows
crate topic.

Related
Rust for Windows, and the windows crate
Windows Subsystem for Linux (WSL)
Microsoft C++ Build Tools
Microsoft Visual Studio
Visual Studio Code for Windows
rust-analyzer extension
CodeLLDB extension
C/C++ extension
Rust for Windows, and the windows
crate
Article • 08/11/2023

https://www.youtube-nocookie.com/embed/-oZrsCPKsn4

Introducing Rust for Windows

In the Overview of developing on Windows with Rust topic, we demonstrated a simple
app that outputs a Hello, world! message. But not only can you use Rust on Windows,
you can also write apps for Windows using Rust.

You can find all of the latest updates in the Release log of the Rust for Windows repo
on GitHub.

Rust for Windows lets you use any Windows API (past, present, and future) directly and
seamlessly via the windows crate (crate is Rust's term for a binary or a library, and/or
the source code that builds into one).

Whether it's timeless functions such as CreateEventW and WaitForSingleObject,

powerful graphics engines such as Direct3D, traditional windowing functions such as
CreateWindowExW and DispatchMessageW, or more recent user interface (UI)
frameworks such as Composition, the windows crate has you covered.

The win32metadata project aims to provide metadata for Win32 APIs. This metadata
describes the API surface—strongly-typed API signatures, parameters, and types. This
enables the entire Windows API to be projected in an automated and complete way for
consumption by Rust (as well as languages such as C# and C++). Also see Making
Win32 APIs more accessible to more languages .

As a Rust developer, you'll use Cargo (Rust's package management tool)—along with
https://crates.io (the Rust community's crate registry)—to manage the dependencies

in your projects. The good news is that you can reference the windows crate from your
Rust apps, and then immediately begin calling Windows APIs. You can also find Rust
documentation for the windows crate over on https://docs.rs .

Similar to C++/WinRT, Rust for Windows is an open source language projection

developed on GitHub. Use the Rust for Windows repo if you have questions about
Rust for Windows, or if you wish to report issues with it.
The Rust for Windows repo also has some simple examples that you can follow. And
there's an excellent sample app in the form of Robert Mikhayelyan's Minesweeper .

Contribute to Rust for Windows

Rust for Windows welcomes your contributions!

Rust documentation for the Windows API

Rust for Windows benefits from the polished toolchain that Rust developers enjoy. But if
having the entire Windows API at your fingertips seems a little daunting, there's also
Rust documentation for the Windows API .

This resource essentially documents how the Windows APIs and types are projected into
idiomatic Rust. Use it to browse or search for the APIs you need to know about, and that
you need to know how to call.

Writing an app with Rust for Windows

The next topic is the RSS reader tutorial, where we'll walk through writing a simple app
with Rust for Windows.

Related
Overview of developing on Windows with Rust
RSS reader tutorial
The windows crate
Documentation for the windows crate
Win32 metadata
Making Win32 APIs more accessible to more languages
Rust documentation for the Windows API
Rust for Windows
Minesweeper sample app
RSS reader tutorial (Rust for Windows
with VS Code)
Article • 05/22/2023

The previous topic introduced Rust for Windows, and the windows crate.

Now let's try out Rust for Windows by writing a simple console app that downloads the
titles of blog posts from a Really Simple Syndication (RSS) feed.

1. Launch a command prompt ( cmd.exe ), and cd to a folder where you want to keep
your Rust projects.

2. Using Cargo, create a new Rust project named rss_reader, and cd to the newly-
created folder:

Console

> cargo new rss_reader

> Created binary (application) `rss_reader` package
> cd rss_reader

3. Then open the rss_reader project in VS Code.

Console

code .

4. Let's implement the main rss_reader project. First, open the Cargo.toml file at the
root of the project. A Cargo.toml file is a text file that describes a Rust project,
including any dependencies it has.

Add a dependency on the windows crate, as shown in the listing below. The
windows crate is large. To keep build times fast, we'll select just the
Foundation_Collections and Web_Syndication features that we need for this code.

toml

# Cargo.toml
...

[dependencies.windows]
version = "0.43.0"
features = [
 "Foundation_Collections",
"Web_Syndication",
]

5. Then, open the rss_reader project's src/main.rs source code file. There you'll find
the Cargo default "Hello, world!" code. Add the following use statement to the
beginning of main.rs :

Rust

// src\main.rs
use windows::{
core::*,
Foundation::Uri,
Web::Syndication::SyndicationClient
};

fn main() {
println!("Hello, world!");
}

The use declaration shortens the path to the types that we'll be using. There's the
Uri type that we mentioned earlier.

6. To create a new Uri, replace Cargo's default main function with this:

Rust

// src\main.rs
...

fn main() -> Result<()> {

let uri = Uri::CreateUri(h!("https://blogs.windows.com/feed"))?;

Ok(())
}

Notice that the return type of the main function is a Result, from windows::core::.
That will make things easier, as it's common to deal with errors from operating
system (OS) APIs. windows::core::Result helps us with error propagation, and
concise error handling.

You can see the question-mark operator at the end of the line of code. To save on
typing, we do that to use Rust's error-propagation and short-circuiting logic. That
means we don't have to do a bunch of manual error handling for this simple
 example. For more info about this feature of Rust, see The ? operator for easier
error handling .

Also notice the h! macro from the windows crate. We use that to construct an
HSTRING reference from a Rust string literal. The WinRT API uses HSTRING
extensively for string values.

7. To download the RSS feed, we'll create a new SyndicationClient.

Rust

// src\main.rs
...

fn main() -> windows::core::Result<()> {

let uri = Uri::CreateUri(h!("https://blogs.windows.com/feed"))?;
let client = SyndicationClient::new()?;

Ok(())
}

The new function is a Rust constructor. All objects in the windows crate follow the
Rust convention and name their constructors new.

8. Now we can use the SyndicationClient to retrieve the feed.

Rust

// src\main.rs
...

fn main() -> windows::core::Result<()> {

let uri = Uri::CreateUri(h!("https://blogs.windows.com/feed"))?;
let client = SyndicationClient::new()?;
let feed = client.RetrieveFeedAsync(&uri)?.get()?;

Ok(())
}

Because RetrieveFeedAsync is an asynchronous API, we use the blocking get

function to keep the example simple. Alternatively, we could use the await
operator within an async function to cooperatively wait for the results. A more
complex app with a graphical user interface will frequently use async .

9. Now we can iterate over the resulting items, and let's print out just the titles. You'll
also see a few extra lines of code below to set a user-agent header, since some
RSS feeds require that.
 Rust

// src\main.rs
...

fn main() -> windows::core::Result<()> {

let uri = Uri::CreateUri(h!("https://blogs.windows.com/feed"))?;
let client = SyndicationClient::new()?;

client.SetRequestHeader(
h!("User-Agent"),
h!("Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64;
Trident/6.0)"),
)?;

let feed = client.RetrieveFeedAsync(&uri)?.get()?;

for item in feed.Items()? {

println!("{}", item.Title()?.Text()?);
}

Ok(())
}

10. Now let's confirm that we can build and run by clicking Run > Run Without
Debugging (or pressing Ctrl+F5). If you see any unexpected messages, then make
sure you've successfully completed the Hello, world! tutorial (Rust with VS Code).

There are also Debug and Run commands embedded inside the text editor.
Alternatively, from a command prompt in the rss_reader folder, type cargo run ,
which will build and then run the program.
 Down in the VS Code Terminal pane, you can see that Cargo successfully
downloads and compiles the windows crate, caching the results, and using them
to make subsequent builds complete in less time. It then builds the sample, and
runs it, displaying a list of blog post titles.

That's as simple as it is to program Rust for Windows. Under the hood, however, a lot of
love goes into building the tooling so that Rust can both parse .winmd files based on
ECMA-335 (Common Language Infrastructure, or CLI), and also faithfully honor the
COM-based application binary interface (ABI) at run-time with both safety and efficiency
in mind.

Showing a message box

We did say that Rust for Windows lets you call any Windows API (past, present, and
future). So in this section we'll show a couple of Windows message boxes.

1. Just like we did for the RSS project, at the command prompt cd to the folder with
your Rust projects.

2. Create a new project named message_box, and open it in VS Code:

Console

> cargo new message_box

> Created binary (application) `message_box` package
> cd message_box
> code .
 3. In VS Code, open the Cargo.toml , and add the Windows dependencies for this
project:

Rust

# message_box\Cargo.toml
...

[dependencies.windows]
version = "0.43.0"
features = [
"Win32_Foundation",
"Win32_UI_WindowsAndMessaging",
]

4. Now open the project's src/main.rs file, and add the use declarations with the
new namespaces (as shown below). And finally add code to call the MessageBoxA
and MessageBoxW functions. The Windows API docs are mainly written with
C/C++ in mind, so it's useful to compare the API docs to the docs for the Rust
projections in the windows crate: MessageBoxA (Rust) and MessageBoxW
(Rust) .

Rust

// src\main.rs
use windows::{
core::*,
Win32::UI::WindowsAndMessaging::*
};

fn main() {
unsafe {
MessageBoxA(None, s!("Ansi"), s!("World"), MB_OK);
MessageBoxW(None, w!("Wide"), w!("World"), MB_OK);
}
}

As you can see, we must use these Win32 APIs in an unsafe block (see Unsafe
blocks ). Also note the s! and w! macros, which create LPCSTR and LPCWSTR
arguments from Rust UTF-8 string literals; much like we created an HSTRING with
the h! macro for rss_reader. Rust is natively Unicode with UTF-8 strings, so using
the wide Unicode (W-suffix) Windows APIs is preferred over the ANSI (A-suffix)
APIs. This can be important if you use non-English text in your code.

This time when you build and run, Rust displays two Windows message boxes.
Related
Rust for Windows, and the windows crate
ECMA-335
The ? operator for easier error handling
Unsafe blocks
 Visual Studio documentation
Learn how to use Visual Studio to develop applications, services, and tools in the language of
your choice, for your platforms and devices.

DOWNLOAD OVERVIEW W H AT ' S N E W

Setup and What is Visual Visual Studio
installation Studio 2022

GET STARTED OVERVIEW

GitHub Copilot Previous
versions

Get started

Learn how to use Visual Follow a tutorial Visual Studio language

Studio guidance
ｂ Simple C# console app
ｇ Write and edit code ｂ C++ console calculator ｂ C#
ｇ Build your code ｂ Visual Basic console app ｂ C++
ｇ Debug your code ｂ Python app ｂ Visual Basic
ｇ Test your code ｂ ASP.NET Core and Angular ｂ Python
ｇ Open code from a repo web app ｂ JavaScript
ｅ Get AI assistance with ｂ ASP.NET Core and React ｂ F#
GitHub Copilot web app
ｂ F# web service

Tasks
 Edit code Build
Write and manage your code using the code editor. Compile and build your source code.

Debug Test
Investigate and fix bugs in your code. Run tests on your projects.

Deploy AI-assisted development

Share your apps and code by using Web Deploy, Get answers and suggestions from GitHub Copilot
InstallShield, NuGet, Continuous Integration, and and code assistance with IntelliCode.
more.

Track version changes Extend Visual Studio

Share code using version control technologies such Add your own functionality to the Visual Studio IDE
as Git and GitHub. to improve your development experience.

Development with Visual Studio

Web and cloud Desktop and mobile

Web development Windows app development
ASP.NET Core and JavaScript .NET desktop development with WPF
Azure development and management .NET development with Windows Forms
Python .NET Framework
Node.js MAUI (.NET Multi-platform App UI) development
Data storage and processing Mobile development with .NET (Xamarin)
Data science Windows development with C++
Office/Sharepoint development Mobile development with C++

Game development Other toolsets

Unity Visual Studio extension development
Unreal Engine Linux development with C++
Universal Windows Platform (UWP) .NET cross-platform development

Blogs - Twitter - Stack Overflow - Issue Reporting - Developer Community - Troubleshooting

 Azure documentation
Learn how to build and manage powerful applications using Microsoft Azure cloud services. Get
documentation, example code, tutorials, and more.

GET STARTED ARCHITECTURE

Get started for Azure developers Design your app using the Azure
Architecture Center

OVERVIEW TRAINING
Prepare your org with the Cloud Build your skills with Microsoft
Adoption Framework Learn training

Browse Azure products

Popular

App Service Azure AI services Azure Arc

Quickly create powerful cloud Build cutting-edge, market- Bring Azure services and
apps for web and mobile ready, responsible applications management to any
for your organization with AI infrastructure
 Azure Cosmos DB Azure Functions Azure Kubernetes Service
Fast NoSQL database with Process events with serverless (AKS)
open APIs for any scale code Simplify the deployment,
management, and operations
of Kubernetes

Azure Operator Insights Azure Quantum (Preview) Azure SQL

Analyze network data from Experience quantum impact Modern SQL family for
multiple sources today on Azure migration and app
modernization

Azure Virtual Desktop Microsoft Copilot for Virtual Machines

The best virtual desktop Azure (Preview) Provision virtual machines for
experience, delivered on Azure Simplify operations and Ubuntu, Red Hat, Windows,
management from cloud to and more
edge with an AI companion

Languages and tools

Python .NET

JavaScript Java
 Go REST API

Azure PowerShell Azure CLI

ARM templates Bicep

Jenkins Terraform

Azure clouds

Azure Government Microsoft Azure operated

A dedicated cloud for U.S. by 21Vianet
government agencies and their A dedicated cloud located in
partners. China and operated by
21Vianet.

Partner solutions

Azure Native ISV Services Commercial marketplace

Integrated partner solutions An online marketplace of
that you can use in Azure to applications and services from
enhance your cloud independent software vendor
infrastructure. (ISV) partners.
 .NET documentation
Learn to use .NET to create applications on any platform using C#, F#, and Visual Basic. Browse
API reference, sample code, tutorials, and more.

DOWNLOAD TRAINING
Download .NET Build .NET apps with C#

TRAINING GET STARTED

Create your first web app Interactive introduction to C#

ARCHITECTURE OVERVIEW
.NET architecture docs Azure for .NET developers

OVERVIEW W H AT ' S N E W
.NET Aspire (Preview) What's new in .NET

.NET: Free. Cross platform. Open source.

A developer platform for building all your apps: web, mobile, desktop, gaming, IoT, and more.
Supported on Windows, Linux, and macOS.

Open source .NET .NET concepts

ｅ .NET overview ｑ What is .NET?
ｇ .NET tutorials ｐ .NET fundamentals
ｈ What's new in .NET 8 ｐ .NET implementations
ｅ .NET Foundation ｅ .NET Framework (for Windows)
 ｈ .NET developer community ｅ .NET Standard
ｅ Community Toolkits ｂ .NET Q&A
ｐ .NET tech community forums
ｅ Security in .NET

Develop .NET apps .NET tools and diagnostics

ｇ Create .NET desktop apps for Windows ｅ .NET SDK overview
ｅ Create web apps with ASP.NET Core ｅ .NET CLI overview
ｅ Build cloud-native .NET apps with Orleans ｉ MSBuild property reference
ｆ Build cloud-native apps with .NET Aspire ｅ Global and local tools
ｇ Containerize .NET apps with Docker ｅ Diagnostics tools
ｅ Code analysis
ｅ Package validation

Migrate and upgrade DevOps and testing

ｅ Port from .NET Framework to .NET ｀ Deploy .NET apps
ｐ .NET breaking changes ｅ Unit test .NET apps
ａ Download .NET ｅ GitHub Actions and .NET

Data access in .NET Advanced .NET programming

ｅ LINQ overview ｅ Async programming patterns overview
ｅ Entity Framework Core ｅ Threading overview
ｅ Azure Storage ｅ Parallel programming overview
ｅ XML data ｅ Native interoperability
ｅ Garbage collection

Programming languages
Write your app in your favorite language
 Write .NET apps in C#, F#, or Visual A modern, object-oriented, and type-
Basic safe language
A simple language for succinct, An approachable language with
robust, and performant code readable syntax

Create your application

You can choose web, mobile, desktop, gaming, IoT, and more.

Web Mobile
ASP.NET Core tutorials .NET Multi-platform App UI (.NET MAUI)
What is ASP.NET Core? Xamarin.Forms
ASP.NET Core in Visual Studio Xamarin.iOS
ASP.NET MVC apps in Windows containers Xamarin.Android
Blazor: Interactive client-side web UI with .NET Develop Xamarin apps with Azure
F# for web development

Desktop Microservices
Universal Windows apps Dapr for .NET developers
Windows Presentation Foundation (.NET 5+) Cloud native .NET apps
Windows Presentation Foundation (.NET Serverless apps with Azure
Framework)
Architecture for containerized .NET apps
Windows Forms (.NET 5+)
Deploy a Worker Service to Azure
Windows Forms (.NET Framework)
.NET Multi-platform App UI (.NET MAUI)
Xamarin for macOS

Cloud Machine learning and AI

Azure for .NET developers Build custom AI solutions with ML.NET
.NET Aspire (Preview) Azure Cognitive Services
Migrate on-premises .NET web apps or services Azure machine learning
Azure services for .NET developers F# for Machine Leaning
 Azure SDK for .NET
Deploying Azure Resources with F#

Game development Internet of things (IoT)

Game development with Visual Studio .NET IoT Libraries
Learn how to use CRYENGINE to build games with Get started in 5 minutes
C#
Blink an LED
Build games with C# using the MonoGame library
.NET IoT 101 video series
Learn how to use Unity to build 2D and 3D games
with C#

API and language reference

Search the .NET API and language reference documentation.

.NET API reference .NET Framework API reference

API reference documentation for .NET API reference documentation for .NET Framework

ASP.NET Core API reference ML.NET API reference

API reference documentation for ASP.NET Core API reference documentation for ML.NET

.NET Platform Extensions API reference C# language reference

API reference documentation for .NET Platform C# language reference and specification
Extensions

F# language reference Visual Basic language reference

F# language reference Visual Basic language reference and specification

Are you interested in contributing to the .NET docs? For more information, see our contributor guide.