Tell us about your PDF experience.

Set up your development environment

on Windows
Article • 11/22/2024

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 [Link] 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

[Link]
40e28ce2ba96&locale=en-us&embedUrl=%2Fwindows%2Fdev-environment%2F

AI for Windows apps

Windows AI Hub
A new era of AI has arrived at Microsoft. See how AI is being integrated in Windows 11.
Visit Windows AI Hub
Copilot+ PCs Developer Guide
Copilot+ PCs are a new class of Windows 11 hardware powered by a high-performance
Neural Processing Unit (NPU).
Develop for Copilot+ PCs

DirectML
Pairing DirectML with the ONNX Runtime is often the most straightforward way for
many developers to bring hardware-accelerated AI to their users at scale.
Get Started with DirectML
Responsible AI guidance for Windows
Recommended responsible development practices to use as you create apps that utilize
AI features on Windows.
Develop Responsibly

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 [Link], React, Vue, Express, Gatsby, [Link], or
[Link].
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 [Link] 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, [Link],
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.

[Link]
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.

[Link]
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
What is Dev Home?
Article • 11/19/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 [Link]
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.

Environments in Dev Home

Environments in Dev Home 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
Environments in Dev Home.
Experimental features
Dev Home supports experimenting with developer-focused features. Features that are
identified as "Experimental" may be added and removed from release to release.

A few recent Dev Home Experimental features have included "Dev Diagnostics," a way to
consolidate diagnostic tools, and "Quickstart Playground," an AI integration for
generating app development projects in Visual Studio Code. You can find these
Experimental features tracked in the Dev Home Release Notes .

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 .
Dev Home Machine Configuration - Set
up your Windows development
environment
Article • 12/12/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: Create a new local or cloud environment for development.

Once created you can launch it from the environments page, or select it for
configuration. You can also target an existing dev environment to configure by
selecting applications to install and public repositories to clone. Examples include
Hyper-V (local virtual machines), Microsoft Dev Box (cloud-based dev
environments)... 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.

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. 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.

Use developer utilities delivered with
Dev Home
Article • 05/21/2024

Dev Home brings a set of utilities that are helpful to developers directly to Windows.
Microsoft PowerToys now delivers some of its utilities within Dev Home, making it even
easier to use these tools.

Environment Variables
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.
Hosts File Editor
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.
Registry Preview
Registry Preview simplifies the process of visualizing and editing complex Windows
Registry files. It can also write changes to the Windows Registry.
６ 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 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

Environments in Dev Home
Article • 07/24/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 and maintained by
Microsoft currently include:

Local Hyper-V virtual machine (VM)

Microsoft Dev Box
Windows Subsystem for Linux (WSL) distribution

To add your own environment to Dev Home, see: Build an extension for Environments in
Dev Home.

Environments in Dev Home centralize your interactions with virtual or cloud

environments in a single place.

View all of your environments in a single place

Create new environments and quickly configure them with 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

To get started using environments in Dev Home, select the Environments tab in the left
column user interface inside Dev Home. Your existing environments will be displayed
here. To create new environments, select + Create Environment.

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.

Windows Subsystem for Linux extension: Installed by default in Dev Home. By

default, your local WSL distributions will be visible on the Dev Home Environments
page.

Microsoft Dev Box: To display Dev Box cloud environments, install the Dev Home
Azure extension. Once installed, each Dev Box that you have in your Azure account
will be visible on the Dev Home Environments page.
Each type of environment in Dev Home is supported by a Dev Home extension. To add a
new environment, you must ensure that the Dev Home extension supporting the
associated environment that you wish to use is installed.

 Tip

If you do not see the Environments tab in Dev Home or are having trouble, ensure
that you have the latest version of Dev Home by running the command: winget
upgrade [Link] .

Manage your Environments in Dev Home

Each environment in Dev Home can display some key information:

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

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

3. Status of the 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 for a native experience, 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 to
refresh the list of environments. 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 environment using Dev Home

To create a new 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 Windows and Linux 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 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 an Extension for Environments in Dev
Home
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 • 07/16/2024

Windows Customization in Dev Home enables you to configure your Windows

environment to suit your development needs.

Adjust advanced File Explorer settings, such as showing file extensions, hidden and
system files, full paths in the title bar, and empty drives.
Optimize the performance of your Windows machine using Dev Drive insights.
Enable or disable optional Windows virtualization features.
Customize general system settings such as long paths and taskbar behaviors.
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 [Link] .

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.

Virtualization Feature Management

Configure optional virtualization features to enable/disable virtualization behavior on
your machine, including:

Containers: Provides services and tools to create and manage Windows Server
Containers and their resources.
Guarded Host: Enables the device to create and run Shielded Virtual Machine
using remote attestation.
Hyper-V: Provides services and management tools for creating and running virtual
machines and their resources.
Hyper-V Management Tools: Includes GUI and command-line tools for managing
Hyper-V.
Hyper-V Platform: Provides the services you can use to create and manage virtual
machines and their resources.
Virtual Machine Platform: Enables platform support for virtual machines.
Windows Hypervisor Platform: Enables virtualization software to run on the
Windows hypervisor.
Windows Sandbox: Enables the dependencies required to run Windows Sandbox
scenarios.
Windows Subsystem for Linux: Provides services and environments for running
native-user-mode Linux shells and tools on Windows.

General System Settings

Configure various general system settings for developer workfloows, including:

End Task: Enable end task in taskbar by right-click.

Enable long paths: Remove MAX_PATH limitations from common Win32 file and
directory functions.

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 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
Set up a Dev Drive on Windows 11
Article • 08/27/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. Existing
storage volumes cannot be converted to be a Dev Drive. The Dev Drive designation
happens only at the original format time.

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.
Local administrator permissions.

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.

How to choose between using a disk partition or VHD

There are advantages and trade-offs to consider when choosing whether to create a
disk partition or create a new VHD to store your Dev Drive.

Create a disk partition: Storing your Dev Drive on a disk partition will generally
offer faster performance because it directly uses the physical disk without any
additional layers. The trade-offs are that using a partitioned disk will be less
flexible, since resizing partitions can be more complex and risky, and less
portability, since the partition is tied to the physical disk.

Create a new VHD: Storing your Dev Drive in a Virtual Hard Disk (VHD) may have
slightly lower performance due to the overhead of managing the virtual disk layer.
The trade-offs are that VHDs offer more flexibility for dynamic resizing (if you need
 to manage disk space efficiently), moving, or backing up data. VHDs are also highly
portable,allowing the VHD file to be transferred to another machine or backup
location. However, keep in mind that when a VHD is 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.

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.
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

Considerations for Installing Developer Tools and SDKs on Dev Drive: Developer tools
and SDKs are typically placed in either an administrator or per-user location. These
locations provide specific security and isolation guarantees on Windows and impact
Microsoft Defender behavior. However, many tools provide the flexibility to choose the
installation location, including a Dev Drive.

Before proceeding with the installation of developer tools or SDKs on a Dev Drive,
evaluate the trade-offs associated with the system and asynchronous scanning to ensure
it aligns with the security requirements of your device and organization. You have the
option to create an administrator or per-user folder on the Dev Drive. Additionally, it is
important to verify that Microsoft Defender Performance Mode (e.g., asynchronous
scanning) meets your needs for handling binaries.

７ 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. After changing your environment variables,
you may need to either restart all open console windows or reboot the device for the
new values to be applied.

Npm cache (NodeJS): Create an npm cache directory in your Dev Drive, for
example D:\packages\npm , then set a global environment variable
npm_config_cache to that path, for example 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 [Link] , 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.

７ Note
There is currently a known issue: Dotnet tool command doesn't respect nuget
packages path . The .NET team is aware and investigating a fix for .NET 10 and a
servicing release update for 8.0 and 9.0.

vcpkg cache: Create a vcpkg cache directory in your Dev Drive, for example
D:\packages\vcpkg , then set a global environment variable

VCPKG_DEFAULT_BINARY_CACHE to that path, for example 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, for example
D:\packages\pip , then set a global environment variable PIP_CACHE_DIR to that

path, for example 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, for example
D:\packages\cargo , then set a global environment variable CARGO_HOME to that

path, for example 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, for
example D:\packages\maven , then set a global environment variable MAVEN_OPTS to
add a configuration setting to that path, for example setx /M MAVEN_OPTS "-
[Link]=D:\packages\maven" . Move the contents of

%USERPROFILE%\.m2\repository to this directory (this includes only the

dependencies, plugins, and other artifacts that Maven downloads into the
repository folder and uses for your projects). Learn more in the Maven docs

and see StackOverflow for How to specify an alternate location for the .m2 folder
or [Link] 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 [Link], 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

Windows Defender Application Control (WDAC): Managed installer tracking with applockerfltr
 Scenario: Description Filter Name

AppLocker identity services

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".

Block Cloning Support

Beginning in Windows 11 24H2 & Windows Server 2025, Block cloning is now supported
on Dev Drive. Because Dev Drive utilizes the ReFS file system format, Block cloning
support will mean free performance benefits whenever you copy a file using Dev Drive.
Block cloning allows the file system to copy a range of file bytes on behalf of an
application as a low-cost metadata operation, rather than performing expensive read
and write operations to the underlying physical data. This results in faster copy
completion, less I/O to the underlying storage, and improved storage capacity by
enabling multiple files to share the same logical clusters. Learn more about Block
cloning.
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. This will require also adding the WinSetupMon

filter, which is needed for the Windows Update process. (See Filters for common
scenarios. Many programs use these, so beware of potential side effects. We also
recommend using performance mode for Microsoft Defender for asynchronous
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. It is not necessary to enable BitLocker on the mounted VHD.

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" .

Can Dev Drive Performance Mode be applied to Antivirus

programs besides Microsoft Defender?
Dev Drive Performance Mode is specifically a Microsoft Defender Antivirus capability
related to Defender’s real-time protection. When using alternative Antivirus programs
with Dev Drive, Performance Mode will not be applied, but it is possible to adjust the
Allow List of security filters that are attached to the Dev Drive in order to find the right
balance between performance and security for your development work. You will need to
ensure that you understand the function of any attached filters when making changes to
the attached filter list. Find a list with descriptions in Filters for common scenarios.

How can I find a Dev Drive that I created and lost track
of?
When a dev drive is mounted but you forgot where its located, the following methods
can be used to find it:

Use Dev Drive Insights in the Windows Customization feature of Dev Home.

Use DiskPart and the "list vdisk" command to show the full path to the vhdx: 1)
Open a command line and enter diskpart , 2) Once DiskPart opens, enter list
vdisk .

Use Powershell and "Get-Disk | Select-Object FriendlyName,Location]": Open

PowerShell and enter Get-Disk | Select-Object FriendlyName,Location .

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 .
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 ([Link] ) 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 = ($[Link](':'))[1].TrimStart("\")

([[Link]]::OpenRemoteBaseKey([[Link]
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 = $($[Link]()) -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-$[Link]"
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)

Windows Package Manager
Article • 11/22/2024

Windows Package Manager is a comprehensive package manager solution that includes:

WinGet: The command line tool and client interface for the Windows Package
Manager service.
Submit packages to Windows Package Manager: The packaging services for
hosting and installing applications on Windows devices.
WinGet Configuration files: Create a set of instructions for Windows Package
Manager to consolidate the steps for manually setting up a device and onboarding
to a new project to a single command that is reliable and repeatable. WinGet
Configuration files utilize PowerShell Desired State Configuration (DSC) in
combination with YAML formatted instructions and WinGet packages to handle
your machine set up.

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.
Enterprise 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.

Find the latest Windows Package Manager announcements and version updates in the
Windows Command Line Blog .

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.
Use the WinGet tool to install and
manage applications
Article • 11/15/2024

WinGet is a command line tool enabling users to discover, install, upgrade, remove and
configure applications on Windows 10, Windows 11, and Windows Server 2025
computers. This tool is the client interface to the Windows Package Manager service.

Install WinGet
WinGet the Windows Package Manager is available on Windows 11, modern versions of
Windows 10, and Windows Server 2025 as a part of the App Installer. The App Installer
is a System Component delivered and updated by the Microsoft store on Windows
Desktop versions, and via Updates on Windows Server 2025.

７ Note

The WinGet command line tool is only supported on Windows 10 1709 (build
16299) or later at this time. WinGet will not be available until you have logged into
Windows as a user for the first time, triggering Microsoft Store to register the
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-Host "Installing WinGet PowerShell module from PSGallery..."
Install-PackageProvider -Name NuGet -Force | Out-Null
Install-Module -Name [Link] -Force -Repository PSGallery |
Out-Null
Write-Host "Using Repair-WinGetPackageManager cmdlet to bootstrap WinGet..."
Repair-WinGetPackageManager
Write-Host "Done."

To install the PowerShell module in machine scope, you can use the -Scope AllUsers
parameter with the Install-Module cmdlet. If you would like a preview version of
WinGet, you can add -IncludePrerelease parameter with the Repair-
WinGetPackageManager cmdlet. To see the available parameters for the Repair-
WinGetPackageManager cmdlet, you can run Get-Help Repair-WinGetPackageManager -
Full .

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 [Link] [Link]

[Link]

７ 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 [Link]
file. For more information, see [Link] . 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
[Link] . 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
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/[Link]>

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-

[Link]> . Running the command: winget configuration show

[Link] 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/[Link]> .
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 • 09/06/2024

The download command of the winget tool downloads the installer, dependencies, and
license file (when downloading a Microsoft Store Packaged app). 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.

The download command requires EntraID (formally Azure Active Directory)

authentication to download a Microsoft Store packaged app (*.msix, *.appx,
*.msixbundle, or *.appxbundle) and to download the Microsoft Store packaged app
license file. The EntraID account used for authentication to generate and retrieve a
Microsoft Store packaged app license file must be a member of one of the following
three Azure roles: Global Administrator, User Administrator, or License Administrator.

７ 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.

Usage
winget download [[-q] <query>] [<options>]
Download without license file
Downloading a package using WinGet, the package license file can be omitted by
appending to the command the --skip-license parameter. The exclusion of the
package license file will remove the authorization requirement for generating the offline
license file.

Windows Command Prompt

winget download [[--id] <package id>] [[--skip-license]] [<options>]

Download for a specific platform

Downloading a package using WinGet, by default will download the latest available
version of a package for each applicable use case (architecture, device platform, etc.).
Filtering the downloaded content for a specific device platform is done by appending to
the command the --platform parameter.

Windows Command Prompt

winget download [[--id] <package id>] [[--platform] <platform type> ]

[<options>]

ﾉ Expand table
 Platform Description

[Link] Supports being installed on Windows desktop experience

[Link] Supports being installed on all Microsoft operating systems

[Link] Supports being installed on Microsoft HoloLens devices

Download for a specific architecture

Downloading a package using WinGet, by default will download the latest available
version of a package for each applicable use case (architecture, device platform, etc.).
Filtering the downloaded content with a specific architecture is done by appending to
the command the --architecture parameter.

Windows Command Prompt

winget download [[--id] <package id>] [[--architecture] <Architecture>]

[<options>]

ﾉ Expand table

Architecture Description

x86 32-bit processor

x64 64-bit processor

arm 32-bit ARM processor

arm64 64-bit ARM processor

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 Directory where the installers are downloaded to.

-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).

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

--skip-dependencies Skips processing package dependencies and Windows features.

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

header.
 Option Description

--authentication-mode Specify authentication window preference (silent,

silentPreferred or interactive).

--authentication-account Specify the account to be used for authentication.

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

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

--skip-license,--skip-microsoft- Skips retrieving Microsoft Store package offline license.

store-package-license

--platform Select the target platform.

-?, --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.

--nowarn,--ignore-warnings Suppresses warning outputs.

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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

CMD

winget download --id [Link] --version 0.15.2

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

CMD

winget download --id [Link] --installer-type msix

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

CMD

winget download --id [Link] --scope machine --architecture x64

--download-directory <Path>

Related topics
Use the winget tool to install and manage applications
Submit packages to Windows Package Manager
export command (winget)
Article • 07/31/2024

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.

ﾉ Expand table

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.

ﾉ Expand table

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

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable- Disable interactive prompts.

interactivity

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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.

ﾉ Expand table
 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

６ 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
features command (winget)
Article • 07/31/2024

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 [<options>]

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.

Options
The following options are available.

ﾉ Expand table

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.

--nowarn,--ignore-warnings Suppresses warning outputs.

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

６ 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
hash command (winget)
Article • 07/31/2024

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:

ﾉ Expand table

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.

ﾉ Expand table

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, --verbose- Used to override the logging setting and create a verbose log.
logs

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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
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/31/2024

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.

ﾉ Expand table

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.
 ﾉ Expand table

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.

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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.

ﾉ Expand table

Entry Description

Sources The sources application manifests come from.

Packages The collection of packages to install.

 Entry Description

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 [Link] was already installed.

Therefore the import command skipped the installation.

６ 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
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 • 07/31/2024

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.
 ﾉ 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 install.

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

ﾉ Expand table

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.
Option Description

-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.

--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.

--allow-reboot Allows a reboot if applicable.

--skip-dependencies Skips processing package dependencies and Windows features.

--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

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

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

--authentication-mode Specify authentication window preference (silent, silentPreferred or

interactive).

--authentication-account Specify the account to be used for authentication.

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

-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.

 Option Description

--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

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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 [Link]

The following example installs an application by version and ID.

CMD

winget install --id [Link] --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 [Link] -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 [Link] -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>

ﾉ Expand table

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

６ 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
list command (winget)
Article • 07/31/2024

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.

ﾉ 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 installed package
you are searching for.

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

ﾉ Expand table

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.

 Option Description

--authentication- Specify authentication window preference (silent, silentPreferred or

mode interactive).

--authentication- Specify the account to be used for authentication.

account

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

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

-?, --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

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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

６ 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
pin command (winget)
Article • 07/31/2024

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.

ﾉ Expand table
 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.

--nowarn,--ignore-warnings Suppresses warning outputs.

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

Subcommands
The pin command supports the following subcommands.

ﾉ Expand table

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

ﾉ Expand table

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.

ﾉ Expand table

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.

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

-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.

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

--authentication- Specify authentication window preference (silent, silentPreferred or

mode interactive).

--authentication- Specify the account to be used for authentication.

account

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

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

--blocking Block from upgrading until the pin is removed, preventing override
 Option Description

arguments. Changes pin behavior to be blocking.

--installed Pin a specific installed version

-?, --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

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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 [Link] --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 [Link] --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

ﾉ Expand table

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.

ﾉ Expand table

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.

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

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

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

 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.

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

--authentication- Specify authentication window preference (silent, silentPreferred or

mode interactive).

--authentication- Specify the account to be used for authentication.

account

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

--installed Pin a specific installed version.

-?, --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

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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 [Link]

list
The list subcommand lists all current pins.

Usage:

Windows Command Prompt

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

Arguments

ﾉ Expand table

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.

ﾉ Expand table

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.

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

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

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

-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.

--authentication- Specify authentication window preference (silent, silentPreferred or

mode interactive).
 Option Description

--authentication- Specify the account to be used for authentication.

account

--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, --verbose- Used to override the logging setting and create a verbose log.
logs

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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 [Link]

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:

Windows Command Prompt

winget pin reset [<options>]

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

ﾉ Expand table

Option Description

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

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

-?, --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

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

Examples
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

６ 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
search command (winget)
Article • 07/31/2024

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.

ﾉ Expand table

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.
 ﾉ Expand table

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.

--authentication- Specify authentication window preference (silent, silentPreferred or

mode interactive).

--authentication- Specify the account to be used for authentication.

account

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

agreements

--versions Show available versions of the package.

-?, --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- Used to override the logging setting and create a verbose log.
logs

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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

６ 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
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
[Link]

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": "[Link]

// For documentation on these settings, see: [Link]

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 [Link] 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 [Link]
settings where you can see the experimental features available to you.
show command (winget)
Article • 07/31/2024

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.

ﾉ Expand table
 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.

ﾉ Expand table

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.

--authentication-mode Specify authentication window preference (silent, silentPreferred or

interactive).
 Option Description

--authentication-account Specify the account to be used for authentication.

--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, --verbose-logs Used to override the logging setting and create a verbose log.

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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

ﾉ Expand table

Value Description

Version Version of the application.

Publisher Publisher of the application.

Moniker AppMoniker of the application.

Description Description of the application.

Value Description

Homepage Homepage of the application.

License License of the application.

LicenseUrl The URL to the license file of the application.

Installer details

ﾉ Expand table

Value Description

Type The type of installer.

Download Url The Url of the installer.

SHA256 The Sha-256 of the installer.

Related topics
Use the winget tool to install and manage applications

６ 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
The winget source command
Article • 07/31/2024

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.

ﾉ Expand table

Argument Description

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

The following image shows help for the source command:

Options
The following options are available.

ﾉ Expand table

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.

--nowarn,--ignore-warnings Suppresses warning outputs.

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

Subcommands
The source command supports the following subcommands.

ﾉ Expand table
 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.

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> [-a] <arg> [[-t] <type>] [<options>]

Arguments

The following arguments are available.

ﾉ Expand table

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.
 ﾉ Expand table

Option Description

--trust-level Trust level of the source (none or trusted).

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

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

--explicit

-?, --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.

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

For example, winget source add --name Contoso [Link] adds

the Contoso repository at URL [Link] .

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.

ﾉ Expand table

Type Description

[Link] 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>] [<options>]

Aliases
The following aliases are available for this subcommand:

ls

Arguments

The following arguments are available.

ﾉ Expand table

Argument Description

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

Options
The following options are available.

ﾉ Expand table

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.

--nowarn,--ignore-warnings Suppresses warning outputs.

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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

Output

Name Arg
-----------------------------------------
winget [Link]

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 : [Link]
Arg : [Link]
Data : AppInstallerSQLiteIndex-int_g4ype1skzj3jy
Updated: 2020-4-14 [Link].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>] [<options>]

Aliases
The following aliases are available for this subcommand:

refresh

Arguments
The following arguments are available.

ﾉ Expand table

Argument Description

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

Options

The following options are available.

ﾉ Expand table

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.

--nowarn,--ignore-warnings Suppresses warning outputs.

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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> [<options>]

Aliases

The following aliases are available for this subcommand:

rm

Arguments
The following arguments are available.

ﾉ Expand table

Argument Description

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

Options

The following options are available.

ﾉ Expand table
 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.

--nowarn,--ignore-warnings Suppresses warning outputs.

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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 [[-n] <name>] [<options>]

Arguments
The following arguments are available.
 ﾉ Expand table

Argument Description

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

Options
The following options are available.

ﾉ Expand table

Option Description

--force Forces the reset of the sources.

-?, --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.

--nowarn,--ignore-warnings Suppresses warning outputs.

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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

Usage:

Windows Command Prompt

winget source export [[-n] <name>] [<options>]

Arguments

The following arguments are available.

 ﾉ Expand table

Argument Description

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

Options
The following options are available.

ﾉ Expand table

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.

--nowarn,--ignore-warnings Suppresses warning outputs.

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

Examples

Windows Command Prompt

winget source export winget

Returns the following output:

Output

{"Arg":"[Link]
8wekyb3d8bbwe","Identifier":"[Link].Source_8wekyb3d8bbwe","Name":"
winget","Type":"[Link]"}

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

６ 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
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: [Link] $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 = [[Link].Utf8Encoding]::new()
$Local:word = $[Link]('"', '""')
$Local:ast = $[Link]().Replace('"', '""')
winget complete --word="$Local:word" --commandline "$Local:ast"
--position $cursorPosition | ForEach-Object {
[[Link]]::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/31/2024

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.

ﾉ 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
uninstalling.

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

ﾉ Expand table

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.

--all,--all-versions Uninstall all versions.

Option Description

-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).

-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.

--authentication- Specify authentication window preference (silent, silentPreferred or

mode interactive).

--authentication- Specify the account to be used for authentication.

account

--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, --verbose- Used to override the logging setting and create a verbose log.
logs

--nowarn,--ignore- Suppresses warning outputs.

warnings

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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.

６ 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
upgrade command (winget)
Article • 07/31/2024

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, --manifest Must be followed by the path to the manifest (YAML) file. You can use the
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, --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.

--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, --architecture Select the architecture to install.

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

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

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

security-hash

--allow-reboot Allows a reboot if applicable.

--skip- Skips processing package dependencies and Windows features.

dependencies

--ignore-local- Ignore the malware scan performed as part of installing an archive type
archive-malware- package from local manifest.
scan

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

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

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

--authentication- Specify authentication window preference (silent, silentPreferred or

mode interactive).

--authentication- Specify the account to be used for authentication.

account

-r, --recurse, --all Upgrade all installed packages to the latest version if available.

-u, --unknown, -- Upgrade packages even if their current version cannot be determined.
include-
unknown
 Option Description

--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
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

--nowarn,-- Suppresses warning outputs.

ignore-warnings

--disable- Disable interactive prompts.

interactivity

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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 [Link]

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 [Link] 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 an 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 [Link]. 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.

６ 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
validate command (winget)
Article • 12/11/2024

The validate command of the winget tool validates a manifest for submitting software
to the Microsoft Community Package Manifest Repository on GitHub.

A few different tools are available to help you author a manifest, including Windows
Package Manager Manifest Creator, YamlCreate.ps1, and tools authored by the user
community. See Authoring a Manifest in the winget-pkgs repo on GitHub .

Usage
winget validate [--manifest] <manifest> [<options>]

Arguments
The following arguments are available.

ﾉ Expand table

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.

ﾉ Expand table

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.

--nowarn,--ignore-warnings Suppresses warning outputs.

Option Description

--disable-interactivity Disable interactive prompts.

--proxy Set a proxy to use for this execution.

--no-proxy Disable the use of proxy for this execution.

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 • 11/15/2024

If WinGet does not appear to be installed correctly, follow these steps from a PowerShell
command prompt:

PowerShell

Install-PackageProvider -Name NuGet -Force | Out-Null

Install-Module -Name [Link] -Force -Repository PSGallery |
Out-Null
Repair-WinGetPackageManager -Force -Latest

When WinGet commands are failing, 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 [Link] -a [Link]
--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.

403 Forbidden error

A 403 Forbidden error may occur when attempting to download a package using the
WinGet tool. This issue can arise if an Independent Software Vendor (ISV) opts not have
their product distributed by a package manager service like WinGet.

The server reponsible for initiating the download typically checks for a user agent string
included with the download request to identify the device or client (e.g., browser,
WinGet). If you can download the installer using your browser, but encounter issues with
WinGet, it is possible that the ISV has blocked the WinGet user agent string.

The user agent string for WinGet has the following format:

winget-cli WindowsPackageManager/{Client Version}

DesktopAppInstaller/[Link] {AppInstaller Version}

Example:

winget-cli WindowsPackageManager/1.9.25200
DesktopAppInstaller/[Link] v1.24.25200.0
WinGet Configuration
Article • 11/21/2024

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:
[Link] .

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 [Link] . For
Git-based projects the default configuration should be stored in a "configurations"
directory at: ./configurations/[Link] .

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 [Link] formatted
file:
 yml

# yaml-language-server: $schema=[Link]
properties:
assertions:
- resource: [Link]/OsVersion
directives:
description: Verify min OS version requirement
allowPrerelease: true
settings:
MinVersion: '10.0.22000'
resources:
- resource: [Link]/DeveloperMode
directives:
description: Enable Developer Mode
allowPrerelease: true
settings:
Ensure: Present
- resource: [Link]/WinGetPackage
id: vsPackage
directives:
description: Install Visual Studio 2022 Community
allowPrerelease: true
settings:
id: [Link]
source: winget
- resource: [Link]/VSComponents
dependsOn:
- vsPackage
directives:
description: Install required VS workloads from vsconfig file
allowPrerelease: true
settings:
productId: [Link]
channelId: [Link]
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=[Link]
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 [Link] . The most recent
schema number at the time of this example is 0.2 , so the schema was entered as:
# yaml-language-server: $schema=[Link] .
 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 [Link] 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 [Link]/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/22/2024

Learn how to contribute packages to Windows Package Manager that can be installed
with the WinGet command line client as an ISV business, publisher, or member of the
community.

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 selected formats.

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.
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: # [Link] 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 /
[Link]

YAML

PackageIdentifier: "[Link]"
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 ([Link]). 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 [Link] . 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 • 11/21/2024

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
[Link] 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 [Link]
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 [Link] 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 [Link] 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.

ﾉ Expand table

Label Details

Azure- The manifest has completed the test pass. It is waiting for approval. If no issues
Pipeline- are encountered during the test pass it will automatically be approved. If a test
Passed fails, it 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
Attention Windows 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
Completed request 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.

ﾉ Expand table

Label Details

Binary- The application included in this pull request failed to pass the Installers Scan
Validation-Error test. This test is designed to ensure that the application installs on all
environments without warnings. For more details on this error, see the Binary
validation error section below.

Error-Analysis- The Binary-Validation-Test test timed out. The pull request will get assigned
Timeout to a Windows Package Manager engineer to investigate.

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-Installer- The validation service was unable to download the installer. This may be
Availability related to Azure IP ranges being blocked, or the installer URL may be
incorrect. Check 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
Installer- the evaluation of an MSIX package.
Validation-Error

Manifest-Path- The manifest files must be put into a specific folder structure. This label
Error indicates 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
Validation-Error the manifest and re-submit. For details on the manifest format and schema,
see 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-Validation- The URLs Validation Test could not locate the URL and responded with a HTTP
Error error status code (403 or 404), or the URL reputation test failed. You can
identify 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-Error this problem, install your application, then run a Microsoft Defender full scan.
If 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-Error Validation of the Windows Package Manager failed during manual approval.
Look at the accompanying comment for next steps.

Validation- During installation testing, the test was unable to locate the primary
Executable-Error application. Make sure the application installs correctly on all platforms. If your
application 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
Failed updating 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
Installation- the accompanying comment for next steps.
Error

Validation- This package could not be validated due to a merge conflict. Please address
Merge-Conflict the merge conflict and resubmit your pull request.

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.

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.
 Label Details

Validation- During installation, the test timed out. This most likely is due to the
Unattended- application not installing silently. It could also be due to some other error
Failed being encountered 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-Error uninstall. Look at the accompanying comment for more details.

Validation- The package has a dependency on the C++ runtime that could not be
VCRuntime- resolved. 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.

ﾉ Expand table

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.

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.

ﾉ Expand table

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-Policy An error occurred during the validation of the manifest.

Internal-Error-Manifest An error occurred during the validation of the manifest.

Internal-Error-NoArchitectures An error occurred because the test could not determine

the architecture of 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 • 11/21/2024

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
[Link] 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 [Link]
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 [Link] 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 [Link] 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.

ﾉ Expand table

Label Details

Azure- The manifest has completed the test pass. It is waiting for approval. If no issues
Pipeline- are encountered during the test pass it will automatically be approved. If a test
Passed fails, it 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
Attention Windows 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
Completed request 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.

ﾉ Expand table

Label Details

Binary- The application included in this pull request failed to pass the Installers Scan
Validation-Error test. This test is designed to ensure that the application installs on all
environments without warnings. For more details on this error, see the Binary
validation error section below.

Error-Analysis- The Binary-Validation-Test test timed out. The pull request will get assigned
Timeout to a Windows Package Manager engineer to investigate.

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-Installer- The validation service was unable to download the installer. This may be
Availability related to Azure IP ranges being blocked, or the installer URL may be
incorrect. Check 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
Installer- the evaluation of an MSIX package.
Validation-Error

Manifest-Path- The manifest files must be put into a specific folder structure. This label
Error indicates 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
Validation-Error the manifest and re-submit. For details on the manifest format and schema,
see 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-Validation- The URLs Validation Test could not locate the URL and responded with a HTTP
Error error status code (403 or 404), or the URL reputation test failed. You can
identify 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-Error this problem, install your application, then run a Microsoft Defender full scan.
If 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-Error Validation of the Windows Package Manager failed during manual approval.
Look at the accompanying comment for next steps.

Validation- During installation testing, the test was unable to locate the primary
Executable-Error application. Make sure the application installs correctly on all platforms. If your
application 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
Failed updating 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
Installation- the accompanying comment for next steps.
Error

Validation- This package could not be validated due to a merge conflict. Please address
Merge-Conflict the merge conflict and resubmit your pull request.

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.

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.
 Label Details

Validation- During installation, the test timed out. This most likely is due to the
Unattended- application not installing silently. It could also be due to some other error
Failed being encountered 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-Error uninstall. Look at the accompanying comment for more details.

Validation- The package has a dependency on the C++ runtime that could not be
VCRuntime- resolved. 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.

ﾉ Expand table

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.

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.

ﾉ Expand table

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-Policy An error occurred during the validation of the manifest.

Internal-Error-Manifest An error occurred during the validation of the manifest.

Internal-Error-NoArchitectures An error occurred because the test could not determine

the architecture of 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 • 11/21/2024

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
[Link] 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 [Link]
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 [Link] 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 [Link] 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.

ﾉ Expand table

Label Details

Azure- The manifest has completed the test pass. It is waiting for approval. If no issues
Pipeline- are encountered during the test pass it will automatically be approved. If a test
Passed fails, it 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
Attention Windows 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
Completed request 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.

ﾉ Expand table

Label Details

Binary- The application included in this pull request failed to pass the Installers Scan
Validation-Error test. This test is designed to ensure that the application installs on all
environments without warnings. For more details on this error, see the Binary
validation error section below.

Error-Analysis- The Binary-Validation-Test test timed out. The pull request will get assigned
Timeout to a Windows Package Manager engineer to investigate.

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-Installer- The validation service was unable to download the installer. This may be
Availability related to Azure IP ranges being blocked, or the installer URL may be
incorrect. Check 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
Installer- the evaluation of an MSIX package.
Validation-Error

Manifest-Path- The manifest files must be put into a specific folder structure. This label
Error indicates 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
Validation-Error the manifest and re-submit. For details on the manifest format and schema,
see 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-Validation- The URLs Validation Test could not locate the URL and responded with a HTTP
Error error status code (403 or 404), or the URL reputation test failed. You can
identify 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-Error this problem, install your application, then run a Microsoft Defender full scan.
If 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-Error Validation of the Windows Package Manager failed during manual approval.
Look at the accompanying comment for next steps.

Validation- During installation testing, the test was unable to locate the primary
Executable-Error application. Make sure the application installs correctly on all platforms. If your
application 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
Failed updating 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
Installation- the accompanying comment for next steps.
Error

Validation- This package could not be validated due to a merge conflict. Please address
Merge-Conflict the merge conflict and resubmit your pull request.

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.

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.
 Label Details

Validation- During installation, the test timed out. This most likely is due to the
Unattended- application not installing silently. It could also be due to some other error
Failed being encountered 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-Error uninstall. Look at the accompanying comment for more details.

Validation- The package has a dependency on the C++ runtime that could not be
VCRuntime- resolved. 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.

ﾉ Expand table

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.

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.

ﾉ Expand table

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-Policy An error occurred during the validation of the manifest.

Internal-Error-Manifest An error occurred during the validation of the manifest.

Internal-Error-NoArchitectures An error occurred because the test could not determine

the architecture of 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 a 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 an 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

６ 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 PowerToys: Utilities to
customize Windows
Article • 11/19/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:

Advanced Paste

Advanced Paste is a tool that enables you to paste the text from your clipboard into any
format needed. It can be enhanced with an AI-powered option that is 100% opt-in and
requires an OpenAI key.

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, and the picker automatically copies the color to
your clipboard in a specified 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.

New+
New+ enables you to create files and folders from a personalized set of templates in File
Explorer.

Peek

Peek allows you to preview file content without the need to open multiple applications
or interrupt your workflow. Select a 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's open source and modular, supporting
additional plugins.

Quick Accent
Quick Accent is an alternative way to type accented characters. It's useful when a
keyboard doesn't support a 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 tool 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 it by pressing and holding ⊞ 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
PowerToys is currently 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. He aslo shares some tips, information about how to contribute,
and more.
[Link]
Windows-10/player?format=ny

Known issues
You can 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
Installing PowerToys
Article • 11/19/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.##.#-[Link] or PowerToysSetup-0.##.#-[Link] 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's as simple as running the
following command from the command line / PowerShell:

PowerShell

winget install --id [Link] --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 some common commands you may want to use:

ﾉ 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 that
the PowerToys installer has been downloaded to the Windows desktop.

PowerShell

cd $Env:WIX\"bin"

# [Link] -x OUTPUT_FOLDER INSTALLER_PATH

 .\[Link] -x ${Env:\USERPROFILE}"\Desktop\extractedPath"
${Env:\USERPROFILE}"\Desktop\[Link]"

Fixes for uninstalling 0.51 and earlier builds issues

If you have an issue with the MSI being inaccessible, you can download the installer that
corresponds with the installed version via the PowerToys releases page and 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
If there are problems while uninstalling a version, there are cleanup scripts available:

<[Link]/microsoft/PowerToys/tree/main/tools/CleanUp_tool>
<[Link]/microsoft/PowerToys/tree/main/tools/CleanUp_tool_powershell_script>

Community-driven install tools

These community-driven alternative install methods aren't officially supported, and the
PowerToys team doesn't 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 using Scoop, 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 for each of the available utilities.

Updates
PowerToys uses an automatic update checker that checks for new versions when the app
is running. If enabled, a toast notification will appear when an update is available. You
can also check for updates manually from the PowerToys Settings.
Related content
Microsoft PowerToys: Utilities to customize Windows

General settings for PowerToys

PowerToys on GitHub
General settings for PowerToys
Article • 11/19/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 also indicate whether 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.
PowerToys running with administrator
permissions
Article • 11/19/2024

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's elevated
as well.

These are the two scenarios where PowerToys will not work:

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 don't need to run with elevated permission.
However, a common scenario 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 isn't 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.
Desired State Configuration
Article • 04/09/2024

Since version 0.80, the PowerToys installer has been released on GitHub with
[Link] 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
[Link] 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\[Link] .

For the machine-wide install scope, it's found in

%ProgramFiles%\WindowsPowerShell\Modules\[Link] .

Usage
You can invoke the resource directly using the following Powershell syntax:

ps

Invoke-DscResource -Name PowerToysConfigure -Method Set -ModuleName

[Link] -Property @{ Awake = @{ Enabled = $false; Mode =
"TIMED"; IntervalMinutes = "10" } }

However, creating a [Link] file that contains the required settings in a

simpler format is more convenient. Here's an example:

YAML
 properties:
resources:
- resource: [Link]/WinGetPackage
id: installPowerToys
directives:
description: Install PowerToys
allowPrerelease: true
settings:
id: [Link]
source: winget

- resource: [Link]/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 .\[Link]

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
[Link] .

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 current
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
[Link].. (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 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 • 07/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 [Link] file to your Policy Definition template folder. (Example:
C:\Windows\PolicyDefinitions)
2. Copy the [Link] 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 [Link] file to the PolicyDefinition folder. (Example:
%systemroot%\sysvol\domain\policies\PolicyDefinitions)
3. Copy the [Link] 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: ConfigureAllUtilityGlobalEnabledState
GP name: Configure global utility enabled state
GP path: Administrative Templates/Microsoft PowerToys
GP scope: Computer and user
ADMX file name: [Link]

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/ConfigureAllUtil
ityGlobalEnabledState

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

Advanced Paste Advanced Paste: ConfigureEnabledUtilityAdvancedPaste

Configure enabled
state

Always On Top Always On Top: ConfigureEnabledUtilityAlwaysOnTop

Configure enabled
state
Utility ADMX GP name ADMX GP unique name /
Registry value name /
Intune PolicyID

Awake Awake: Configure ConfigureEnabledUtilityAwake

enabled state

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
Utility ADMX GP name ADMX GP unique name /
Registry value name /
Intune PolicyID

state

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
Utility ADMX GP name ADMX GP unique name /
Registry value name /
Intune PolicyID

enabled state

Mouse Without Mouse Without ConfigureEnabledUtilityMouseWithoutBorders

Borders Borders: Configure
enabled state

New+ New+: Configure ConfigureEnabledUtilityNewPlus

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

Workspaces Workspaces: Configure ConfigureEnabledUtilityWorkspaces

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: [Link]

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/>

General settings

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/General settings
GP scope: Computer and user
ADMX file name: [Link]

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~GeneralSettings/

AllowExperimentation
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: [Link]

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: [Link]

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: [Link]

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: [Link]

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: [Link]

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/>

Advanced Paste

Allow using online AI models

Supported on PowerToys 0.81.1 or later.

This policy allows you to disable Advanced Paste online AI models.

If you enable or don't configure this policy, the user takes control over the enabled state
of the Enable paste with AI Advanced Paste setting.
If you disable this policy, the user won't be able to enable Enable paste with AI
Advanced Paste setting and use Advanced Paste AI prompt nor set up the Open AI key
in PowerToys Settings.

７ Note

Changes require a restart of Advanced Paste.

Group Policy (ADMX) information

GP unique name: AllowPowerToysAdvancedPasteOnlineAIModels

GP name: Allow using online AI models
GP path: Administrative Templates/Microsoft PowerToys/Advanced Paste
GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys
Name: AllowPowerToysAdvancedPasteOnlineAIModels
Type: DWORD
Example value: 0x00000000

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~AdvancedPaste/Al
lowPowerToysAdvancedPasteOnlineAIModels

Example value: <disabled/>

Mouse Without Borders

Clipboard sharing enabled

Supported on PowerToys 0.83.0 or later.

This policy configures if the user can share the clipboard between machines.

If you enable or don't configure this policy, the user takes control over the clipboard
sharing setting.
If you disable this policy, the user won't be able to enable the clipboard sharing setting.

Group Policy (ADMX) information

GP unique name: MwbClipboardSharingEnabled

GP name: Clipboard sharing enabled
GP path: Administrative Templates/Microsoft PowerToys/MouseWithoutBorders
GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys
Name: MwbClipboardSharingEnabled
Type: DWORD
Example value: 0x00000000

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~MouseWithoutBord
ers/MwbClipboardSharingEnabled

Example value: <disabled/>

Connect only in same subnet

Supported on PowerToys 0.83.0 or later.

This policy configures if connections are only allowed in the same subnet.

If you enable this policy, the setting is enabled and only connections in the same subnet
are allowed.

If you disable this policy, the setting is disabled and all connections are allowed.

If you don't configure this policy, the user takes control over the setting and can enable
or disable it.

Group Policy (ADMX) information

GP unique name: MwbSameSubnetOnly

GP name: Connect only in same subnet
 GP path: Administrative Templates/Microsoft PowerToys/MouseWithoutBorders
GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys
Name: MwbSameSubnetOnly
Type: DWORD
Example value: 0x00000001

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~MouseWithoutBord
ers/MwbSameSubnetOnly

Example value: <enabled/>

Disable user defined IP Address mapping rules

Supported on PowerToys 0.83.0 or later.

This policy configures if the user can define IP Address mapping rules.

If you enable this policy, the setting is disabled and the user can't define rules or use
existing ones.

If you disable or don't configure this policy, the user takes control over the setting.

Note: Enabling this policy does not prevent policy defined mapping rules from working.

Group Policy (ADMX) information

GP unique name: MwbDisableUserDefinedIpMappingRules

GP name: Disable user defined IP Address mapping rules
GP path: Administrative Templates/Microsoft PowerToys/MouseWithoutBorders
GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys
 Name: MwbDisableUserDefinedIpMappingRules
Type: DWORD
Example value: 0x00000001

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~MouseWithoutBord

ers/MwbDisableUserDefinedIpMappingRules

Example value: <enabled/>

Disallow blocking screensaver on other machines

Supported on PowerToys 0.83.0 or later.

This policy configures if the user is allowed to disable the screensaver on the remote
machines.

If you enable this policy, the user won't be able to enable the "block screensaver"
screensaver setting and the screensaver is not blocked.

If you disable or don't configure this policy, the user takes control over the setting and
can block the screensaver.

Group Policy (ADMX) information

GP unique name: MwbDisallowBlockingScreensaver

GP name: Disallow blocking screensaver on other machines
GP path: Administrative Templates/Microsoft PowerToys/MouseWithoutBorders
GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys
Name: MwbDisallowBlockingScreensaver
Type: DWORD
Example value: 0x00000001

Intune information
 OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~MouseWithoutBord

ers/MwbDisallowBlockingScreensaver

Example value: <enabled/>

File transfer enabled

Supported on PowerToys 0.83.0 or later.

This policy configures if the user can transfer files between machines.

If you enable or don't configure this policy, the user takes control over the file sharing
setting.

If you disable this policy, the user won't be able to enable the file sharing Settings.

Note: The file sharing feature depends on the clipboard sharing feature. Disabling
clipboard sharing automatically disables file sharing too.

Group Policy (ADMX) information

GP unique name: MwbFileTransferEnabled

GP name: File transfer enabled
GP path: Administrative Templates/Microsoft PowerToys/MouseWithoutBorders
GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys
Name: MwbFileTransferEnabled
Type: DWORD
Example value: 0x00000000

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~MouseWithoutBord

ers/MwbFileTransferEnabled
Example value: <disabled/>
Original user interface is available
Supported on PowerToys 0.83.0 or later.

This policy configures if the user can use the old Mouse Without Borders user interface.

If you enable or don't configure this policy, the user takes control over the setting and
can enable or disable the old user interface.

If you disable this policy, the user won't be able to enable the old user interface.

Group Policy (ADMX) information

GP unique name: MwbUseOriginalUserInterface

GP name: Original user interface is available
GP path: Administrative Templates/Microsoft PowerToys/MouseWithoutBorders
GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys
Name: MwbUseOriginalUserInterface
Type: DWORD
Example value: 0x00000000

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~MouseWithoutBord

ers/MwbUseOriginalUserInterface

Example value: <disabled/>

Validate remote machine IP Address

Supported on PowerToys 0.83.0 or later.

This policy configures if reverse DNS lookup is used to validate the remote machine IP
Address.

If you enable this policy, the setting is enabled and the IP Address is validated.

If you disable this policy, the setting is disabled and the IP Address is not validated.
If you don't configure this policy, the user takes control over the setting and can enable
or disable it.

Group Policy (ADMX) information

GP unique name: MwbValidateRemoteIp

GP name: Validate remote machine IP Address
GP path: Administrative Templates/Microsoft PowerToys/MouseWithoutBorders
GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys
Name: MwbValidateRemoteIp
Type: DWORD
Example value: 0x00000001

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~MouseWithoutBord

ers/MwbValidateRemoteIp

Example value: <enabled/>

Predefined IP Address mapping rules

Supported on PowerToys 0.83.0 or later.

This policy allows you to define IP Address mapping rules.

If you enable this policy, you can define IP Address mapping rules that the user can't
change or disable. Please enter one mapping per line in the format: "hostname IP"

If you disable or don't configure this policy, no predefined rules are applied.

Group Policy (ADMX) information

GP unique name: MwbPolicyDefinedIpMappingRules

GP name: Predefined IP Address mapping rules
GP path: Administrative Templates/Microsoft PowerToys/MouseWithoutBorders
 GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys

Name: MwbPolicyDefinedIpMappingRules

Type: MULTI_SZ

Example value:

Host1 [Link]
Host2 [Link]
Host3 [Link]

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~MouseWithoutBord

ers/MwbPolicyDefinedIpMappingRules

Example value:

<enabled/>
<data id="MwbPolicyDefinedIpMappingsList" value="Host1
[Link]&#xF000Host2 [Link]&#xF000Host3 [Link]"/>

７ Note

Syntax for the value property from the data element: <Hostname> <IP
Address>&#xF000;<Hostname 2> <IP Address 2>&#xF000;<Hostname 3> <IP
Address 3>

New+
Hide template filename extension
Supported on PowerToys 0.85.0 or later.

This policy configures if the template filenames are shown with extension or not.

If you enable this policy, the setting is enabled and the extension is hidden.

If you disable this policy, the setting is disabled and the extension is shown.

If you don't configure this policy, the user takes control over the setting and can enable
or disable it.

Group Policy (ADMX) information

GP unique name: NewPlusHideTemplateFilenameExtension

GP name: Hide template filename extension
GP path: Administrative Templates/Microsoft PowerToys/New+
GP scope: Computer and user
ADMX file name: [Link]

Registry information

Path: Software\Policies\PowerToys
Name: NewPlusHideTemplateFilenameExtension
Type: DWORD
Example value: 0x00000000

Intune information

OMA-URI:
./Device/Vendor/MSFT/Policy/Config/PowerToys~Policy~PowerToys~NewPlus/NewPlusH

ideTemplateFilenameExtension

Example value: <disabled/>

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: [Link]

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 [Link]
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: [Link]

Registry information

Path: Software\Policies\PowerToys\PowerLauncherIndividualPluginEnabledList

Name: The plugin ID from the [Link] 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>
Advanced Paste
Article • 12/16/2024

PowerToys Advanced Paste is a tool that enables you to paste the content from your
clipboard into any format needed. It can paste as plain text, markdown, JSON, .txt file,
.html file, or .png file directly with the UX or with a direct keystroke invoke. It can also
extract and paste the text directly from an image in your clipboard. These actions are
executed entirely on your local machine. Additionally, the tool has an AI-powered
option that is 100% opt-in and requires entering an OpenAI key in settings.

Getting started

Enabling
To start using Advanced Paste, enable it in the PowerToys Settings.

Activating
Open the Advanced Paste window with the activation shortcut (default: Win + Shift + V

). See the Settings section for more information on customizing the activation shortcut
and additional shortcut actions.

Settings
From the Settings menu, the following options can be configured:

ﾉ Expand table

Setting Description

Enable Paste with AI Enables the AI-powered paste feature. An OpenAI API key is required
(requires an account on [Link] ). See Paste text with AI
for more information.

Enable advanced AI Enables the Advanced AI feature which allows Semantic Kernel to be
used to define a chain of actions to be performed when using "Paste
with AI". See Paste with Advanced AI for more information.

This setting is off and disabled when Enable Paste with AI is disabled.
When enabling Enable Paste with AI, Enable advanced AI is also enabled
by default, allowing users immediate access to the feature.
 Setting Description

Custom format Enable to preview the output of the custom format before pasting.
preview

Clipboard history Enable to automatically save clipboard history.

Open Advanced Paste The customizable keyboard command to open the Advanced Paste
shortcut window.

Automatically close Determines whether the Advanced Paste window will close after focus is
the Advanced Paste lost from the window.
window after it loses
focus

Custom Actions When using Paste with AI, save the prompts you frequently use and give
them descriptive names, so you can easily select them from the
Advanced Paste window without having to type them out. You can also
assign each action a keyboard command, so you can execute them
without opening the Advanced Paste window.

Paste as plain text The customizable keyboard command to paste as plain text without
directly shortcut opening the Advanced Paste window.

Paste as Markdown The customizable keyboard command to paste as Markdown without

directly shortcut opening the Advanced Paste window.

Paste as JSON directly The customizable keyboard command to paste as JSON without opening
shortcut the Advanced Paste window.

Additional actions: Turn on/off the Image to text paste action and configure the
Image to Text customizable keyboard command.

Additional actions: Turn on/off the set of Paste as File actions which include Paste as .txt file,
Paste as file Paste as .png file, Paste as .html file. Optionally configure the
customizable keyboard command for each of these actions.

） Important

It's possible to set Ctrl + V as an activation shortcut. This is not recommended, as

overriding this shortcut may have unintended consequences.

Advanced text paste

Advanced Paste includes several text-based paste options. These options are available in
the Advanced Paste window, which can be opened using the activation shortcut. You
can also use the customizable keyboard commands to directly invoke a paste action
with quick keys.

Paste as Plain Text

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.

７ Note

Paste as Plain Text is a feature that runs locally and doesn't use AI.
Paste as JSON
Paste as JSON enables you to paste text stored in your clipboard, updating any text-
formatting to JSON, using a quick key shortcut. Any formatting included with the
clipboard text will be replaced with a JSON formatted version of the text.

Sample input:

XML

<note>
<to>Mr. Smith</to>
<from>Ms. Nguyen</from>
<body>Do you like PowerToys?</body>
</note>

JSON output:

JSON

{
"note": {
"to": "Mr. Smith",
"from": "Ms. Nguyen",
"body": "Do you like PowerToys?"
}
}

７ Note

Paste as JSON is a feature that runs locally and doesn't use AI.

Paste as Markdown
Paste as Markdown enables you to paste text stored in your clipboard, updating any
text-formatting to markdown, using a quick key shortcut. Any formatting included with
the clipboard text will be replaced with a markdown formatted version of the text.

Sample input:

HTML

<b>Paste</b> <i>as</i> <a

href="[Link]
Markdown output:

Markdown

**Paste** *as* [Markdown]([Link]

７ Note

Paste as Markdown is a feature that runs locally and doesn't use AI.

Paste as .txt file

Paste as .txt file enables you to paste text stored in your clipboard as a .txt file with an
auto-generated file name. You can optionally set a quick key shortcut in settings.

Sample input:

text

Hello World!

If pasting files is accepted within the application that you are using (e.g. File Explorer),
then the paste as .txt file action will take the input text and paste a .txt file.

７ Note

Paste as .txt file is a feature that runs locally and doesn't use AI.

Paste as .html file

Paste as .html file enables you to paste html data stored in your clipboard as a .html file
with an auto-generated file name. This is especially useful for saving a part of a
webpage from a browser - including links, formatted text and images. You can
optionally set a quick key shortcut in settings.

If pasting files is accepted within the application that you are using (e.g. File Explorer),
then the paste as .html file action will take the input data and paste a .html file.

７ Note
 Paste as .html file is a feature that runs locally and doesn't use AI.

Paste text with AI

When you paste text with AI, the text is analyzed and formatted based on the context of
the text and the prompt provided to the OpenAI call. This feature requires that an
OpenAI API key be provided in the PowerToys settings, and that you have available
credits in your account.

７ Note

If you use this feature and see an error API key quota exceeded , that means you do
not have credits in your OpenAI account and would need to purchase them.

Some examples of how this feature can be used include:

Summarize text: Take long text from the clipboard and ask the AI to summarize it.
Translate text: Take the text from the clipboard in one language and ask the AI to
translate it to another language.
Generate code: Take a description of a function from the clipboard and ask the AI
to generate the code for it.
Transform text: Take text from the clipboard and ask the AI to rewrite it in a
specific style, such as a professional email or a casual message.
Stylize text: Take text from the clipboard and ask the AI to rewrite it in the style of
a well-known author, book, or speaker.

You could ask the AI to paste the text as if it were written by Mark Twain or Shakespeare,
for example, or to summarize a long case study. The possibilities are endless.

Sample input:

The new Advanced Paste feature in PowerToys is now available. You can use it to
save time and improve your writing.

AI output when prompting to "Format the text as if it were written by Mark Twain":

Say, have you heard the news? The newfangled Advanced Paste feature in
PowerToys is finally here! It's a nifty tool that's sure to save you time and spruce up
your writing. If you're in the market for a bit of writing wizardry, this here Advanced
Paste just might be the ticket for ya.
 ７ Note

As with any AI tool, the quality of the output is dependent on the quality of the
input. The more context you provide, the better the AI will be able to understand
and respond to your request. Be sure to carefully review the output before using it.
Please see OpenAI's privacy and terms pages for more info on AI usage in this
feature.

Paste with Advanced AI

This feature uses Semantic Kernel to allow you to define a chain of actions to be
performed when using "Paste with AI". Using this feature you can:

Work with non-text input such as images.

Produce non-text output like files.
Chain multiple actions together and execute them in sequence. For example,
Image to text --> Text to JSON text --> JSON text to .txt file.
Produce meaningful AI-generated error messages.

For these example commands, assume there is an image in the clipboard that contains
some text that you would like to save to a text file in another language. You can phrase
multiple steps explicitly:

Convert this image to text using OCR, translate the text to French, and then
save the text as a .txt file.

Or you can phrase the steps to be more implicit:

Translate to French and save as a .txt file.

Advanced image paste

Advanced Paste includes several image-based paste options. These options are available
in the Advanced Paste window, which can be opened using the activation shortcut. You
can optionally set a quick key shortcut in settings.
Paste Image to text
Paste image to text enables you to extract the text from an image in your clipboard and
quickly paste the extracted text, using a quick key shortcut.

７ Note

Paste as Image to text is a feature that runs locally using local OCR.

Paste as .png file

Paste as .png file enables you to quickly paste an image format, like a bitmap, to a .png
file. You can optionally create a quick key shortcut to invoke this paste action.

７ Note

Paste as .png file is a feature that runs locally and doesn't use AI.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Always On Top utility
Article • 11/19/2024

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.

Unpin a window
To unpin a window pinned by Always On Top, you can either use the activation shortcut
again or close the window.

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.
 Setting Description

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.

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 [Link] and
Notepad++.exe from being pinned. To only prevent a specific application, add
[Link] to the excluded list.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
PowerToys Awake utility
Article • 11/19/2024

PowerToys Awake is a tool for Windows designed to keep a computer awake without
having to manage its power and 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 ( [Link] in the PowerToys installation folder).

７ 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. Once PowerToys Awake exits, the threads are terminated and the
computer will resume its standard power plan behavior.

Settings
In the PowerToys Settings, start PowerToys Awake by toggling Enable Awake on. Once
enabled, the application will manage the power and screen state of the computer.
PowerToys Awake supports a variety of modes that can be used to control computer
and screen power behaviors:

ﾉ Expand table

Setting Description

Keep using the The computer power state is unaffected. PowerToys Awake runs in the
selected power plan background but does not request any custom power behaviors.

Keep awake The computer stays awake indefinitely until you explicitly put the
indefinitely machine to sleep or close/disable the application.

Keep awake for a time Keep machine awake for a predefined limited time. After the time period
interval elapses, PowerToys Awake returns to the disable state.

Keep awake until Keep machine awake until a defined date and time is hit.
expiration

７ Note

Changing the hours or minutes while the computer is kept awake for a time interval
will reset the timer. Timer starts from last input.

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 even if the computer
stays awake. If you need the displays to be available, use the Keep screen on switch,
which will keep displays active.

This feature only works when PowerToys Awake is enabled and has one of the custom
power states selected. It also does not prevent any user-initiated actions, such as
manually putting the computer to sleep or hibernating it.

System tray
To manage the execution of the tool from the system tray, right-click on the PowerToys
Awake icon.

PowerToys Awake tray icon represents the currently selected mode:

ﾉ Expand table

State Icon Description

Disabled PowerToys Awake is running but does not hold any power states.
(Passive) Your operating system's power plan is in effect.
 State Icon Description

Timed You set PowerToys Awake to keep your computer awake for a pre-
(Interval) defined time interval (for example, 30 minutes).

Expirable PowerToys Awake will be keeping the defined power request until a
date and time that you've set through PowerToys settings or in the
configuration file.

Indefinite PowerToys Awake will continue to keep your computer awake until
you exit the application.

The tray icon tooltip will also provide a hint about the currently active PowerToys Awake
mode.

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
[Link] from the terminal:

ﾉ Expand table

Argument Description

--use-pt- Use the PowerToys configuration file to manage the settings. This assumes that
config there is a [Link] file for PowerToys Awake, generated by PowerToys, that
contains all required runtime information. This includes the operating mode
(indefinite, timed, expirable, or disabled), whether screens should be kept on, and
the values for a temporary keep-awake.
When this argument is used, all other arguments are ignored. PowerToys Awake
will look for changes in the [Link] file to update its state.

--display- Keep displays on or off while the machine is kept awake. Expected values are true
on or false .

--time- Duration, in seconds, during which PowerToys Awake keeps the computer awake.
limit Can be used in combination with --display-on .

--expire- Expiration date and/or time when PowerToys Awake will turn off and resume the
at standard 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, PowerToys Awake terminates as well.
 Argument Description

--use- Attaches the execution of Awake to a parent process. When the parent process
parent-pid terminates, PowerToys Awake terminates as well.

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:

[Link] --time-limit 36000

[Link] --time-limit=36000

When setting the value for the --expire-at parameter, the following formats will be
accepted:

[Link] --expire-at=[Link] will expire at 5PM of the current day,

based on the computer clock.

[Link] --expire-at="4/13/2023 [Link]" will expire at 5PM on April

13, 2023, based on the computer clock.

Custom settings
The [Link] configuration file is located in
%HomePath%\AppData\Local\Microsoft\PowerToys\Awake\ .

Keep awake temporarily options in the system tray can be adjusted by modifying the
"customTrayTimes" property, a dictionary consisting of key-value pairs that contain the

name of the shortcut and its duration (in seconds) to stay awake.

For example, the following [Link] file contains custom tray time shortcut
definitions:

JSON

{
"properties":
{
"keepDisplayOn": true,
"mode": 1,
"intervalHours": 2,
"intervalMinutes": 0,
"expirationDateTime": "2024-07-29T[Link]-07:00",
 "customTrayTimes":
{
"8 hours": 28800,
"12 hours": 43200
}
},
"name": "Awake",
"version": "1.0"
}

For the mode property, the following values can be used:

ﾉ Expand table

Value Mode

0 Passive (disabled)

1 Indefinite

2 Timed (interval)

3 Expirable at date/time

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Color Picker utility
Article • 11/19/2024

A system-wide color picking utility for Windows to pick colors from any screen and copy
it to the clipboard in a configurable format.

Getting started

Enabling Color Picker

You can enable the 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 an 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. You can 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 Select what happens when you activate Color Picker. Read more about this
behavior setting in Activating Color Picker.

Default color The color format that Color Picker uses when copying colors to the clipboard.
format

Show color Displays 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 in which 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 you prefer. For example, the default
color format that's displayed upon 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 aren't
currently supported.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Command Not Found utility
Article • 11/19/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 [Link] 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, the following
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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Crop And Lock
Article • 11/19/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 window isn't responding well to being cropped with the "Reparent" mode.

Known issues
Crop And Lock currently has the following 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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Environment Variables
Article • 11/19/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. The Applied variables list shows the current state of the
environment, respecting the order of evaluation of environment variables (Profile > User
> System). The 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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
FancyZones utility
Article • 07/16/2024

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\[Link] . 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 [Link] and
Notepad++.exe ; to match only [Link] add the .exe
extension)

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see 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
File Explorer add-ons utility
Article • 07/16/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 isn't possible to change the background color of the preview pane, so if you're
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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see 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
File Locksmith utility
Article • 11/19/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.

To open File Locksmith to see which processes are using one or more file(s), right-click
on the selected file(s), select Show more options to expand the list of menu options,
then select Unlock with File Locksmith.

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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Hosts File Editor utility
Article • 11/19/2024

Windows includes a local "Hosts" file that contains domain names and matching IP
addresses. This file acts 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 isn't there, your internet service provider (ISP) 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 allow 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 [Link] 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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Image Resizer utility
Article • 11/19/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 allows resized pictures to 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, or 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.
Doesn't crop the image.
Stretch: Fills the entire specified size with the image. Stretches the image
disproportionally as needed. Doesn't 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 can't 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 can't be saved in its
original format. Specify the format the fallback encoder will use: PNG, JPEG, TIFF, BMP,
GIF, or WMPhoto settings. This isn't a file type conversion tool. It 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 [Link] 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 [Link] 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\[Link]

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 the time of the resizing action.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Keyboard Manager utility
Article • 11/19/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 a key or shortcut to an 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 the 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'll 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 can't 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's 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.

 Option Meaning

Elevation Specify the elevation level to start the app. The options include Normal, Elevated, and
Different User.

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 from tasklist

Microsoft Edge [Link]

OneNote [Link]

Outlook [Link]
 Application Process name from tasklist

Teams [Link]

Adobe Photoshop [Link]

File Explorer [Link]

Spotify Music [Link]

Google Chrome [Link]

Excel [Link]

Word [Link]

Powerpoint [Link]

７ Note

If you use tasklist from the Command Prompt to get the list of processes, the
process name will be listed in the Image Name column. The process names in Get-
Process will not include the .exe file extensions. These process names do not

match the process names in Windows Task Manager window.

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't 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 aren't 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 aren't 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 to
which it corresponds. 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 won't 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 re-enable Keyboard Manager.

Known Issues
Keyboard Manager shouldn't 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 .

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Mouse utilities
Article • 12/13/2024

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 [Link] and Notepad++.exe ; to match only
[Link] 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 The customizable keyboard command to activate the mouse jump.

shortcut

Thumbnail Size Constrains the thumbnail image to a maximum size. The default size is
1600x1200 pixels.

Appearance Expand this section to adjust the popup appearance by customizing the colors,
borders, spacing, and more.

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)

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Mouse Without Borders
Article • 09/10/2024

Mouse Without Borders enables you to control up to four 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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
New+
Article • 10/11/2024

PowerToys New+ enables you to create files and folders from a personalized set of
templates, directly from the File Explorer context menu.

Getting started

How to enable New+

To start using New+, enable New+ in the PowerToys settings.

How to create a new object using New+

To create a new item within a folder, right-click on the folder to bring up the context
menu. From there, click on the "New+" option and then select the template you were
looking for.

How to add or customize a new template to New+

To create a new template, start by right-clicking on the folder. This will open a context
menu where you can select the 'New+' option. From there, choose 'Open templates' to
access the "Templates" folder. In this folder, you have the freedom to add, edit, or
rename objects as per your needs. It’s important to note that the objects you add here
will be displayed on the ‘New+’ menu in a sorted order, with folders always appearing
first. This provides the ability to find and select your templates.

Template objects in the "Templates" folder can be files, folders, or shortcuts. The
templates can be of any type, such as text files, Word documents or templates, Excel
spreadsheets or templates, or even shortcuts to applications.

Settings

Templates

Templates location
After the enablement toggle, the New+ Templates location setting is likely the most
interesting one. By default, the template location is in your local app data folder,
specifically at %localappdata%\Microsoft\PowerToys\NewPlus\Templates . However, these
templates will not roam with you across devices. If you want a common set of templates
across devices, a popular option is to change the template location to a folder that is
synced with a cloud drive, such as OneDrive. This way, you can access your templates
from any device.

Display options

Hide template filename extensions

The option enables you to toggle the display of filename extensions. When this option is
toggled off, a file named "[Link]" will be displayed with its extension, appearing as
"[Link]". However, when this option is toggled on (the default), the template will
be displayed without its extension, appearing simply as "filename".

Hide template filename starting digits, spaces and dots

The option enables you to toggle the display of starting digits, spaces and dots. When
this option is toggled off (the default), a file named "1. filename" will be displayed as is.
However, when this option is toggled on, the template will be displayed as "filename".
This is useful when using digits, spaces, and dots at the beginning of filenames to
control the display order of templates.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Peek utility
Article • 11/19/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

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
PowerRename utility
Article • 11/19/2024

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 the 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 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'll 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 the 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: [Link] :

Search for: power

Rename with: super

The value of the renamed file would result in:

Match all occurrences cleared: [Link]

Match all occurrences selected: [Link]

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: [Link] → [Link] .

Apply to: Extension only

Only the file extension is modified by the operation. For example: [Link] →
[Link] .

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:

[Link]
[Link]
[Link]

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

Random string values

If selected, you can use the following patterns as part of the Replace with text:
 ﾉ Expand table

Variable pattern Explanation

${rstringalnum=X} Random string with uppercase letters, lowercase letters and 0-9 digits,
customized length.

${rstringalpha=X} Random string with uppercase letters and lowercase letters, customized
length.

${rstringdigit=X} Random string with 0-9 digits, customized length.

${ruuidv4} Random UUID according to v4 specification.

By default, random string values created are mixed case. You can adjust the generating
behavior with the general text formatting options that PowerRename provides.

If you wish to create UUID values with braces, you can add { and } to the Replace with
input in combination with the ruuidv4 pattern accordingly: {${ruuidv4}} .

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 tooltip 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.

 Variable Explanation
pattern

$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:

[Link] , created on 11/02/2020 (november second)

[Link] , 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:

[Link]

[Link]

Regular expressions
For most use cases, a simple search and replace is sufficient. However, there may be
occasions in which complicated renaming tasks require more control. Regular
Expressions can help in this scenario.
Regular Expressions define a search pattern for text. They can be used to search, edit,
and manipulate text. For a given string, the pattern defined by the regular expression
may match once, several times, or not at all. PowerRename uses the ECMAScript
grammar, which is common amongst modern programming languages.

To enable regular expressions, select Use Regular Expressions. Note that you'll 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"

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_$[Link] Prepends "foo_" to the existing file name for

PNG files

(.*).png $1_foo.png Appends "_foo" to the existing file name for

PNG files

(.*) $[Link] Appends ".txt" extension to existing file

(^\w+\.$)\|(^\w+$) $[Link] 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 some useful examples/cheatsheets available 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 isn't 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.
Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
PowerToys Run utility
Article • 11/19/2024

PowerToys Run is a quick launcher for power users that contains additional features
without sacrificing performance. It's open source and modular, supporting additional
plugins.

To use PowerToys Run, select Alt + Space and start typing! (Note that the keyboard
shortcut can be changed in the settings window.)

） Important

For this utility to work, PowerToys must be running in the background and Run
must be enabled.

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 The 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 result,
before selecting top item in 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).
 Setting Description

Preferred monitor position If multiple displays are in use, PowerToys Run can be opened
on:
• 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 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 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 '[Link]'

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 [Link] 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.

// [Link] 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 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:\[Link] C:\[Link]

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 supported by

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
include 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
Operation Operator Description
Syntax

Subtraction a-b

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( [Link] ) 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 )
 Operation Operator Description
Syntax

Arc Sine arcsin( x )

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 [Link] ,
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 [Link] 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

The following GUID versions are supported:

v1 - Time based
v3 - Namespace and name based, using MD5
v4 - Random value
v5 - Namespace and name based, using SHA1
v7 - Time-ordered random value

７ 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 [Link] using the DNS
[Link] namespace.
 Command Result

# uuidv3 ns:DNS The namespace parameter can be any valid GUID, and the name
[Link] parameter can be any string.

# uuid7 Generate a random version 7 GUID with the first 48-bit corresponding
# guidv7 to the current timestamp, providing a well-defined order of
subsequently generated values.

 Tip

The guid and uuid keywords are interchangeable and the v is optional. I.e. guid5
and guidv5 are the same.

Hashing
The following hashing algorithms are supported:

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 [Link] Test query

 ７ Note

The entire 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 [Link]

Escaped data string

Usage for escaping a data string:

# esc:data C:\Program Files\PowerToys\[Link]

Usage for unescaping a data string:

# uesc:data C%3A%5CProgram%20Files%5CPowerToys%[Link]

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

>* 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 UWP apps don't know their process until they are searched in non-
minimized state.

２ Warning

If you kill the process of a 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 configured to open each window in a
separate process, you'll 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 aren't set to cover all drives, you'll 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

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Quick Accent utility
Article • 11/19/2024

Quick Accent is an alternative way to type accented characters. It's 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 character sets 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
Māori
Norwegian
Pinyin
Polish
Portuguese
Romanian
Slovak
Slovenian
Spanish
Serbian
Serbian Cyrillic
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 sets.

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 [Link] and Notepad++.exe ;
to match only [Link] add the .exe extension).

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Registry Preview
Article • 11/19/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

There is currently a 10MB file limit for opening Windows Registry files with Registry
Preview. The tool will display 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 of the window, there is a visual tree representation of the registry keys
listed in the file. This visual tree will be updated each time file content changes in 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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Screen ruler utility
Article • 12/26/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 + Ctrl + Shift + M to activate and select which tool you want to use to
measure. 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. The measuring line can effectively 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.

Extra units of Choose an alternate unit of measure to display in addition to pixels.

measurement Available values are pixels, inches, centimeters, and millimeters.

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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
Windows key shortcut guide
Article • 07/31/2024

This guide displays common keyboard shortcuts that use the Windows key.

Get started
To open the shortcut guide, hold down the ⊞ Windows key for the time as set in the
PowerToys Settings (900ms by default). 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 default

Background Opacity of the Shortcut Guide overlay

opacity

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
[Link] and Notepad++.exe ; to match only [Link] add the .exe
extension).
Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see 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
Text Extractor utility
Article • 07/16/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'll 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

[[Link], [Link], ContentType =

WindowsRuntime]

[[Link]]::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 '[Link]*'

}

An example output:

PowerShell

Name : [Link]~~~el-GR~[Link]
State : NotPresent

Name : [Link]~~~en-GB~[Link]
State : NotPresent

Name : [Link]~~~en-US~[Link]
State : Installed

Name : [Link]~~~es-ES~[Link]
 State : NotPresent

Name : [Link]~~~es-MX~[Link]
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

'[Link]*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

'[Link]*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.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see 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
Video Conference Mute
Article • 07/12/2024

７ 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 [Link] in the same directory

to enable verbose logging mode in the driver.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see 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
Workspaces utility
Article • 12/16/2024

PowerToys Workspaces is a desktop manager utility for launching a set of applications to

custom positions and configurations with a single click. This gets you into your ideal
desktop state for any project or activity faster. You can capture your desktop state as a
new workspace using the editor, add arguments to apps to configure their state on
launch, and pin the workspace as a desktop shortcut for quick-launching. Launching the
workspace will launch all apps to their assigned positions.

Enabling
To start using Workspaces, enable it in the PowerToys Settings.

Creating a new workspace

Open the editor using by selecting "Launch editor" from PowerToys Workspaces settings
or by using the shortcut ⊞ Win + Ctrl + ` .

Click "+ Create workspace" to invoke the Capture experience - in this view, the desktop
is fully functional and you are able to open, close, and reposition apps to get your apps
into the desired layout. Once you have arranged the apps how you would like, select
"Capture".
After capturing, you will enter the editor where you can name the workspace, adjust
window sizes, add command line interface (CLI) arguments, remove apps, and create a
desktop shortcut before finally saving the workspace.
Launching a workspace
Launch a workspace by either selecting "Launch" from the list of workspaces in the
editor, or by using a desktop shortcut if you chose to create one when saving the
workspace originally. Shortcuts can also be pinned to the taskbar for convenient
launching.

While the workspace launches, PowerToys will display a dialog box presenting the status
of each app. Each app will have one of the following statuses:

ﾉ Expand table

Symbol Status

The app has successfully launched and repositioned.

The app is in the process of launching and moving to the correct position.

The app has failed to launch.

The dialog box will dismiss itself once all apps have properly launched and been
arranged in their desired positions. You can also dismiss the dialog yourself at any time,
or use it to cancel the launch.

Editing a workspace
Start by launching the editor and selecting the workspace you would like to edit. Once
in the edit view for that layout, you can remove apps, modify the window positions
manually via each app's dropdown menu, or select "Launch & Edit" to launch the layout
and re-enter the same Capture experience as when it was first created.

７ Note

Capturing the adjusted workspace will perform a clean re-capture, and all previous
CLI arguments and settings will be removed. The re-capture can be reverted to
return to the original workspace if necessary.

Adding CLI arguments to applications

To launch apps in a desired state, CLI arguments can be added to each app in their
respective dropdown menus. These arguments are specific to the app itself and are
called alongside the app when launched. In the below example, Visual Studio Code (VS
Code) is launched to the file provided at the path and Terminal is launched to the
"Ubuntu" profile.

You can find more information on VS Code and Terminal CLI arguments can be found
below:
 VS Code CLI Docs
Terminal CLI Docs

 Tip

Each app will have its own set of command line arguments that can be used to
modify the launch behavior, but many apps use similar patterns. For example, try
passing a comma-separated list of URLs to Edge and other browsers to launch the
browser with those tabs open, or pass a filepath to an Office application, text editor
or IDE to launch directly to that file.

Launching apps as admin

To launch apps as admin, select the "Launch as Admin" box in the respective app's
dropdown menu. On launch, a User Account Control (UAC) dialog will be shown for each
app that has been set to launch as admin.

） Important

There is a known issue where apps that launch as admin are unable to be
repositioned to the desired layout. The team is actively working on a fix for an
upcoming release.

Opening new windows vs. repositioning

existing windows
Different apps may behave differently on launch if there is already an existing instance
of the application open on the desktop - some apps will reposition the existing instance,
whereas others may launch a new instance by default. If the "Move existing windows"
option is enabled for the workspace, any existing apps are moved to the desired
position in the workspace and the remaining apps are launched as usual. For tailoring to
user preference, the recommendation is to handle launch behavior via available CLI
arguments.

For example, VS Code will launch a new window by default, but should a user prefer to
move the existing window, the --reuse-window CLI argument can be added to VS Code's
CLI arguments.
 ７ Note

Some apps are "single-instance" applications, meaning that there may only be one
active instance of the app open at a time. One example of this is the Windows
Settings app. These apps, if already active, will be repositioned by default, and new
instances cannot be launched.

Frequently Asked Questions

The following are some common questions and answers about PowerToys Workspaces:

Why do app windows launch and then jump to the positions I saved them in?

PowerToys cannot tell an app to launch to a specific position. What we can do is

launch an app first, and then give an instruction to move and resize it to a certain
position. However, this results in the user visibly seeing the process on-screen. To
help with this limitation, we added the dialog box during launch, which displays
the launch status of each app.

My windows were snapped when I saved my workspace, but when I launch the
workspace from a clean state they are not snapped. Why is this?

PowerToys uses publicly available APIs and the FancyZones engine under the hood
for positioning apps. Unfortunately, this does not include snapping capabilities.

How can I pin a workspace to the taskbar?

You can create a desktop shortcut for your workspace first, and then pin it to the
taskbar. Pinning a workspace to the taskbar directly is not currently supported.

Settings
ﾉ Expand table

Setting Description

Activation To change the default hotkey, click on the control and enter the desired key
shortcut combination.

Install PowerToys
This utility is part of the Microsoft PowerToys utilities for power users. It provides a set of
useful utilities to tune and streamline your Windows experience for greater productivity.
To install PowerToys, see Installing PowerToys.
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 [Link] 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

[Link]

７ 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 [Link]

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 • 11/21/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
The Sudo for Windows command is available in Windows 11, version 24H2 or higher.
(Check for Windows updates).

７ 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 > System > 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 [Link] and the
elevated [Link] 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 gsudo by Gerardo Grignoli which has a number of additional features and
configuration options or check out other solutions from the community.
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
[Link], [Link], [Link], [Link], [Link], or Gatsby.

Choose a JavaScript framework to install and

set up your dev environment

[Link] overview
Learn about what you can do with [Link] and how to set up a [Link] 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

[Link] overview
Learn about what you can do with [Link] and how to set up a [Link] development
environment.
Install on Windows
Install on WSL
Try a beginner-level tutorial

Install [Link] on WSL

[Link] is a framework for creating server-rendered JavaScript apps based on [Link],
[Link], Webpack and [Link]. Learn how to install it on the Windows Subsystem for
Linux.

Install [Link] on WSL

[Link] is a framework for creating server-rendered JavaScript apps based on [Link],
[Link], Webpack and [Link]. Learn how to install it on the Windows Subsystem for
Linux.

Install Gatsby on WSL

Gatsby is a static site generator framework based on [Link]. Learn how to install it on
the Windows Subsystem for Linux.
What is NodeJS?
Article • 03/01/2024

[Link] 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 [Link] work on Windows?

Yes. Windows supports two different environments for developing apps with [Link]:

Install a [Link] development environment on Windows

Install a [Link] development environment on Windows Subsystem for Linux

What can you do with NodeJS?

[Link] 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 [Link].

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 [Link] 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 [Link] 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 [Link] or, in our case, a
[Link] version manager.
Hardware programming: While not quite as popular as web apps, [Link] is
growing in popularity for IoT uses, such as collecting data from sensors, beacons,
transmitters, motors, or anything that generates large amounts of data. [Link]
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 [Link] learning path
Install [Link] on Windows Subsystem
for Linux (WSL2)
Article • 12/12/2024

For those who prefer using [Link] in a Linux environment, this guide will help you to
install [Link] on the Windows Subsystem for Linux (WSL 2 is the recommended
version).

Consider the following when deciding where to install and whether to develop with
[Link] in a native Windows versus a Linux (WSL 2) environment:

Skill level: If you are new to developing with [Link] and want to get up and
running quickly so that you can learn, install [Link] on Windows. Installing and
using [Link] on Windows will provide a less complex environment for beginners
than using WSL.
Command line client tool: If you prefer PowerShell, use [Link] on Windows. If
you prefer Bash, use [Link] on Linux (WSL 2).
Production server: If you plan to deploy your [Link] app on Windows Server, use
[Link] on Windows. If you plan to deploy on a Linux Server, use [Link] on Linux
(WSL 2). WSL allows you to install your preferred Linux distribution (with Ubuntu as
the default), ensuring consistency between your development environment (where
you write code) and your production environment (the server where your code is
deployed).
Performance speed and system call compatibility: There is continuous debate and
development on Linux vs Windows performance, but the key when using a
Windows machine is to keep your development project files in the same file
system where you have installed [Link]. If you install [Link] on the Windows file
system, keep your files on a Windows drive (for example, C:/). If you install [Link]
on a Linux distribution (like Ubuntu), keep your project files in the Linux file system
directory associated with the distribution that you are using. (Enter [Link] .
from your WSL distribution command line to browse the directory using Windows
File Explorer.)
Docker containers: If you want to use Docker containers to develop your project
on Windows, we recommend that you Install Docker Desktop on Windows . To
use Docker in a Linux workspace, see set up Docker Desktop for Windows with
WSL 2 to avoid having to maintain both Linux and Windows build scripts.

Install Windows Subsystem for Linux

See the WSL install documentation if you plan to use a Linux development environment
with [Link]. These steps will include choosing a Linux distribution (Ubuntu is the
default) and the version of Windows Subsystem for Linux (WSL 2 is the default and
recommended version). You can install multiple Linux distributions if you wish.

Once you have installed WSL 2 and a Linux distribution, open the Linux distribution (it
can be found in your Windows Terminal list or 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 .

Windows Terminal
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 nvm, [Link], and npm

Besides choosing whether to install on Windows or WSL, there are additional choices to
make when installing [Link]. We recommend using a version manager as versions
change very quickly. You will likely need to switch between multiple versions of [Link]
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
[Link]. We will walk through the steps to install nvm and then use it to install [Link]
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 [Link] 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- [Link]

sh/nvm/master/[Link] | 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 [Link]. In a later step, you'll
learn how to switch between active versions of [Link] with an nvm command.

Install the current stable LTS release of [Link] (recommended for production
applications): nvm install --lts
Install the current release of [Link] (for testing latest [Link] 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 [Link] 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 [Link] 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 [Link] available, use
the command: nvm ls-remote ).

If you are using NVM to install [Link] 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 [Link] 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
[Link] 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 [Link] development out of the box, there
are some helpful extensions to consider installing available in the [Link] Extension
Pack . Install them all or pick and choose which seem the most useful to you.

To install the [Link] 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 [Link] 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
[Link], you'll need to develop and test the client side. This extension is a DAP-
based JavaScript debugger. It debugs [Link], 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 [Link] project on WSL, see the article Get started using Git on
Windows Subsystem for Linux in the WSL documentation.
Install [Link] on Windows
Article • 12/12/2024

This guide will help you to install [Link] in a Windows development environment.

For those who prefer using [Link] in a Linux environment, see Install [Link] on
Windows Subsystem for Linux (WSL2).

Consider the following when deciding where to install and whether to develop with
[Link] in a native Windows versus a Linux (WSL 2) environment:

Skill level: If you are new to developing with [Link] and want to get up and
running quickly so that you can learn, install [Link] on Windows. Installing and
using [Link] on Windows will provide a less complex environment for beginners
than using WSL.
Command line client tool: If you prefer PowerShell, use [Link] on Windows. If
you prefer Bash, use [Link] on Linux (WSL 2).
Production server: If you plan to deploy your [Link] app on Windows Server, use
[Link] on Windows. If you plan to deploy on a Linux Server, use [Link] on Linux
(WSL 2). WSL allows you to install your preferred Linux distribution (with Ubuntu as
the default), ensuring consistency between your development environment (where
you write code) and your production environment (the server where your code is
deployed).
Performance speed and system call compatibility: There is continuous debate and
development on Linux vs Windows performance, but the key when using a
Windows machine is to keep your development project files in the same file
system where you have installed [Link]. If you install [Link] on the Windows file
system, keep your files on a Windows drive (for example, C:/). If you install [Link]
on a Linux distribution (like Ubuntu), keep your project files in the Linux file system
directory associated with the distribution that you are using. (Enter [Link] .
from your WSL distribution command line to browse the directory using Windows
File Explorer.)
Docker containers: If you want to use Docker containers to develop your project
on Windows, we recommend that you Install Docker Desktop on Windows . To
use Docker in a Linux workspace, see set up Docker Desktop for Windows with
WSL 2 to avoid having to maintain both Linux and Windows build scripts.

Install nvm-windows, [Link], and npm

Besides choosing whether to install on Windows or WSL, there are additional choices to
make when installing [Link]. We recommend using a version manager as versions
change very quickly. You will likely need to switch between multiple [Link] 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
[Link], but is only available for Mac/Linux and not supported on Windows. Instead, we
recommend installing nvm-windows and then using it to install [Link] 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 [Link] 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 [Link] 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 [Link] 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 nvm-windows 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 [Link] file for the most recent release.

3. Once downloaded, open the zip file, then open the [Link] 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 [Link] will
be installed.

5. Once the installation is complete. Open PowerShell (recommend opening with

elevated Admin permissions) and try using nvm-windows to list which versions of
Node are currently installed (should be none at this point): nvm ls

6. Install the current release of [Link] (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 [Link] (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 [Link] 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 [Link] 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 [Link].

Alternative version managers

While NVM for Windows (nvm-windows) 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, 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 [Link] on Windows, see
the Volta Docs .

Install Visual Studio Code

We recommend you install Visual Studio Code for developing with [Link] on
Windows. For help, see [Link] 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 [Link] development environment:

WebStorm
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 [Link] .

[Link] on Windows Server

If you are in the (somewhat rare) situation of needing to host a [Link] 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 [Link] apps.
Tutorial: [Link] for Beginners
Article • 02/09/2022

If you're brand new to using [Link], this guide will help you to get started with some
basics.

Try using [Link] in Visual Studio Code

Create your first [Link] web app using Express
Try using a [Link] module

Prerequisites
Installing on [Link] 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 "[Link]" with a variable named "msg" inside: echo
var msg > [Link]

3. Open the directory and your [Link] 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 "[Link]" file:

JavaScript

var msg = 'Hello World';

[Link](msg);

5. To run your "[Link]" file with [Link]. 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 [Link] . You should see the output: "Hello World".
 ７ Note

Notice that when you type console in your '[Link]' 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 [Link] 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 [Link]:

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 [Link] 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,

[Link] and [Link] , 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 .
[Link] . 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.
[Link] . 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 [Link] 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 [Link]
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
[Link] 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 [Link] 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 '[Link]' 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 [Link] module

[Link] 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

[Link] String validation

imagemin, Minification
UglifyJS2

spritesmith Sprite sheet generation

winston Logging

[Link] 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 [Link] CLI. You'll see the > prompt letting you
know you're using [Link] 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: [Link]()

3. To check your CPU's architecture, enter: [Link]()

4. To view the CPUs available on your system, enter: [Link]()

5. Leave the [Link] CLI by entering .exit or by selecting Ctrl+C twice.

 Tip

You can use the [Link] 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 =
[Link] === "win32"; ).
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 [Link] backend, we
recommend installing [Link] on WSL. (Though [Link] now also offers static file
serving ).

Native desktop apps: React Native for Desktop + 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 [Link] framework on WSL
Install the Gatsby framework on WSL
Install React Native for Desktop 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 environment 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 [Link].

For Windows development, follow the instructions to install [Link] on WSL or

install [Link] 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 [Link] 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 [Link] 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.
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 Desktop (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 [Link] 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
[Link] . 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 [Link] 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 [Link] backend, we recommend installing
[Link], 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 [Link]
Install Gatsby
Install React Native for Desktop
Install NodeJS on Windows
Install NodeJS on WSL
Try the tutorial: Using React in Visual Studio Code
Try the React learning path
Install React directly on Windows
Article • 11/25/2024

This guide will walk through installing React directly on Windows 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 Desktop (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 [Link] 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 [Link] backend, we recommend installing
[Link], 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 [Link]
Install Gatsby
Install React Native for Desktop
Install NodeJS on Windows
Install NodeJS on WSL
Try the tutorial: Using React in Visual Studio Code
Try the React learning path
Get started build a desktop app with
React Native for Desktop
Article • 11/08/2024

React Native for Desktop 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 Desktop can be found on the System
Requirements page. Ensure Developer Mode is turned ON in Windows Settings App.

Install React Native for Desktop

You can create a Windows desktop app using React Native for Desktop 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 react-native@[Link].X init <projectName> --version [Link].X

3. Switch to the project directory and run the following command to install the React
Native for Desktop 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 & [Link] development
support.

Open the solution file in the application folder in Visual Studio (e.g.,
AwesomeProject/windows/[Link] 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 [Link] 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/[Link] 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 Desktop docs
React Native docs
React docs
Install NodeJS on Windows
Try the React learning path
Get started developing for Android
using React Native
Article • 11/22/2024

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 and set the ANDROID_HOME environment
variable. Follow the instructions at Set Up Your Environment - React Native . Be
sure to set the Development OS selection to "Windows" and the Target OS
selection to Android.

3. Set the JAVA_HOME environment variable. The Gradle tool used to build Android
apps requires a specific version requirement for the Java SDK. To find the
supported version, in Android Studio, go to Settings->Build, Execution,
Deployment->Build Tools->Gradle. Write down the path selected in the Gradle
JDK drop-down. Set the JAVA_HOME environment variable to this path using the
following steps:

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.
Set the Variable name to JAVA_HOME and the value to the path that you
retrieved from Android Studio.
 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 react-native@[Link].X init <projectName> --version [Link].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
[Link] . 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={[Link]}>
Edit <Text style={[Link]}>[Link]</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'.
Get started with [Link] on Windows
Article • 03/18/2024

A guide to help you install the [Link] web framework and get up and running on
Windows.

[Link] is a JavaScript framework tailored for building React-based web applications,

offering support for both static and server-side rendered web applications. Built with
best practices in mind, [Link] enables you to create "universal" web apps in a consistent
manner, requiring minimal configuration. These "universal" server-rendered web apps,
also referred to as “isomorphic”, share code between the client and server. [Link]
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 [Link]
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 [Link] 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
[Link] . 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 [Link]
To install [Link], 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 [Link] 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 [Link] project in VS Code. This will
allow you to look at the [Link] 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 [Link] is installed:

npm run dev to start [Link] in development mode.

npm run build to build the application for production usage.

npm start to start a [Link] 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 [Link] 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: [Link]
✔ Ready

Select this localhost link to open your new [Link] app in a web browser.

7. Open the app/[Link] file in your VS Code editor. Find Get started by editing..
and replace everything inside the <p> tag with This is my new [Link] 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 [Link] 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
( [Link] ) file will be created for you to save debugging setup details. To learn more,
see VS Code Debugging .
To learn more about [Link], see the [Link] docs .
Get started with [Link] on Windows
Article • 03/18/2024

A guide to help you install the [Link] web framework and get up and running on
Windows.

[Link] is a static site generator framework based on [Link], as opposed to being

server-rendered like [Link]. A static site generator generates static HTML on build time.
It doesn’t require a server. [Link] 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 [Link] 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 [Link]
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 [Link] 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
[Link] . 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 [Link]
To create a [Link] 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 [Link] 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 [Link] 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. [Link] .
 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:
[Link] ." 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/[Link] 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 [Link] , 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
( [Link] ) 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 [Link] docs .

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 [Link] .
 3. Stop running your React app (Ctrl+c) and open it's code files in VS Code by
entering: code .

4. Find the src/[Link] file and find the header section that reads:

JavaScript

<p>Edit <code>src/[Link]</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
[Link] in your browser.

Application file structure

The initial file structure looks like

markdown

hello-world
├── node_modules
├── [Link]
├── [Link]
├── [Link]
├── [Link]
├── public
│ └── [Link]
├── src
│ ├── [Link]
│ ├── [Link]
│ ├── assets
│ │ └── [Link]
│ ├── [Link]
│ └── [Link]
└── [Link]

For starters, these are the important files and folders you need to know.

[Link] 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 [Link] file should now look like this:

JavaScript
 import "./[Link]";

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 [Link] file should now look like this:

JavaScript
 import { useState } from "react";
import "./[Link]";

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 "./[Link]";

function App() {
const [posts, setPosts] = useState([]);

useEffect(() => {
const url = "[Link]
fetch(url)
.then((response) => [Link]())
.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": "[Link]
"thumbnailUrl": "[Link]
},
{
"albumId": 1,
"id": 2,
"title": "reprehenderit est deserunt velit ipsam",
"url": "[Link]
"thumbnailUrl": "[Link]
}
]

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 [Link] key value + [Link] 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>
{[Link]((post) => (
<article key={[Link]}>
<h2>ID #{[Link]} {[Link]}</h2>
<img src={[Link]} />
</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.
What is [Link]?
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 [Link].

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 [Link] backend, with help from [Link]

Vue tools
[Link] 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 [Link] development with out-of-the-box
support for Babel, PostCSS, TypeScript, ESLint, etc.
[Link]: A framework to make server-side rendered [Link] 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
[Link].
VueX : State management system for Vue apps.

Additional resources
Vue docs
[Link] overview
Install [Link] on WSL
Install [Link] on Windows
Install [Link]
Take your first steps with [Link] learning path
Try a Vue tutorial with VS Code
Install [Link] on Windows Subsystem for
Linux
Article • 03/08/2024

A guide to help you set up a [Link] development environment on Windows by installing

the [Link] web framework on Windows Subsystem for Linux (WSL). Learn more on the
[Link] 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 [Link].

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 [Link] 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 [Link].

） 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
[Link] . 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 [Link]
To install [Link] 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 [Link] 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 [Link] using a CDN, rather than NPM, see the [Link] 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
[Link] overview
Install [Link] on Windows
Install [Link]
Microsoft Learn online course: Take your first steps with [Link]
Try a Vue tutorial with VS Code
Install [Link] directly on Windows
Article • 03/08/2024

A guide to help you set up a [Link] development environment on Windows. Learn more
on the [Link] 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 [Link].

Prerequisites
Install [Link] on Windows: This includes a version manager, package manager,
and Visual Studio Code. The Node Package Manager (npm) is used to install [Link].

Install [Link]
To install [Link]:

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 [Link] 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 [Link] using a CDN, rather than NPM, see the [Link] 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
[Link] overview
Install [Link] on WSL
Install [Link]
Take your first steps with [Link] learning path
Try a Vue tutorial with VS Code
Get started with [Link] on Windows
Article • 11/01/2023

A guide to help you install the [Link] web framework and get up and running on
Windows.

[Link] is a framework for creating server-rendered JavaScript apps based on [Link],

[Link], Webpack and [Link]. It was inspired by [Link]. It is basically a project
boilerplate for Vue. Just like [Link], 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 [Link]
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 [Link] 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
[Link] . 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 [Link]
To install [Link], 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 [Link] 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 [Link] installer will now ask you the following questions:

Project Name: my-nuxtjs-app

Project description: Description of my [Link] 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 [Link] site.
Choose [Link] 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, [Link] 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 [Link] docs point out
some of the differences -- SSR requiring a [Link] server running to server-
render your app and SPA for static hosting.
Choose development tools: [Link] (recommended for VS Code so
Intellisense code completion works)
5. Once your project is created, cd my-nuxtjs-app to enter your [Link] 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 [Link] 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 [Link] 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 [Link] to open your new
[Link] app.

8. Open the pages/[Link] file in your VS Code editor. Find the page title <v-card-
title class="headline">Welcome to the Vuetify + [Link] template</v-card-
 title> and change it to <v-card-title class="headline">This is my new [Link]
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 [Link] 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 [Link] 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 [Link] 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
( [Link] ) file will be created for you to save debugging setup details. To learn more,
see VS Code Debugging .

To learn more about [Link], see the [Link] guide .

Tutorial: [Link] for Beginners
Article • 03/01/2024

If you're brand new to using [Link], this guide will help you to get started with some
basics.

Try the [Link] HelloWorld code sandbox

Try using [Link] in Visual Studio Code

Prerequisites
You must first install [Link] 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 [Link] App" on [Link] 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
[Link] file in VS Code. Try changing "Welcome to your [Link] 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.

[Link] docs

Vue comparison with other frameworks like React or Angular

[Link] overview
Take your first steps with [Link] learning path
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 • 10/01/2024

The following is a step-by-step guide for beginners interested in learning Python using
Windows.

Set up your development environment

There are multiple ways to install Python on Windows:

Install using Microsoft Store : Installing Python 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. We especially recommend installing Python on Windows via the Microsoft
Store if you are a beginner or if you are in an educational environment or part of a
business organization that may restrict permissions or administrative access on
your machine. You will need to determine which version of Python you need. You
can reference the what versions of Python are currently supported at Status of
Python versions | Python Developer's Guide . We recommend either using a
modern, supported version, or matching the version of the whatever Python
project that you hope to contribute to.

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 [Link] 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:

[Link] .

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: [Link]() . Now convert

your string variable to lower-case letters: [Link]() .

6. Count how many times the letter "l" is used in your string variable:
[Link]("l") .

7. Search for a specific character in your string variable, let's find the exclamation
point, with: [Link]("!") . 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: [Link]("!", "?") .

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/[Link], 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 [Link]

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 "[Link]". Open
the folder in VS Code:

PowerShell
 mkdir bounce
cd bounce
new-item [Link]
code .

2. Using VS Code, enter the following Python code (or copy and paste it):

Python

import sys, pygame

[Link]()

size = width, height = 640, 480

dx = 1
dy = 1
x= 163
y = 120
black = (0,0,0)
white = (255,255,255)

screen = [Link].set_mode(size)

while 1:

for event in [Link]():

if [Link] == [Link]: [Link]()

x += dx
y += dy

if x < 0 or x > width:

dx = -dx

if y < 0 or y > height:

dy = -dy

[Link](black)

[Link](screen, white, (x,y), 8)

[Link]()

3. Save it as: [Link] .

4. From the PowerShell terminal, run it by entering: python [Link] .

Try adjusting some of the numbers to see what effect they have on your bouncing ball.

Read more about writing games with pygame at [Link] .

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.

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/20/2024

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 [Link] 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 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 terminal window in VS Code

VS Code uses the 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 may need to install VS Code extensions for your WSL installation. Some 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 ([Link]) by Microsoft extension and select the Install
in WSL: [distribution name] button.

4. Once the extension is finished installing, you will see a WSL: [distribution name] -
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 current directory is the HelloWorld python
project folder.

3. Create a python file by entering: touch [Link] . 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 [Link] 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 [Link] 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 [Link]
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 [Link] 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 [Link]

9. Open your [Link] file in VS Code's File Explorer ( Ctrl+Shift+E , then select your
[Link] 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 [Link], add code to import Flask and create an instance of the Flask object:

Python

from flask import Flask

app = Flask(__name__)
11. Also in [Link], add a function that returns content, in this case a simple string. Use
Flask's [Link] decorator to map the URL route "/" to that function:

Python

@[Link]("/")
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 [Link] 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 [Link]
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 [Link] (Press CTRL+C to quit)

14. Visual Studio will launch a notification stating "Your application now running on
port 5000 is available." Click the Open in Browser button. Or, you can Ctrl+Click
the [Link] 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

[Link] - - [19/Jun/2019 [Link] "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 [Link], such as [Link], 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 [Link]. 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:

[Link] : The Django command-line administrative utility for the project.

You run administrative commands for the project using python [Link]
<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.
[Link] : 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.
[Link] : an entry point for ASGI-compatible web servers to serve your

project. You typically leave this file as-is as it provides the hooks for
production web servers.
[Link] : contains settings for Django project, which you modify in the
course of developing a web app.
[Link] : 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 [Link] 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 - [Link]
Django version 2.2.2, using settings 'web_project.settings'
Starting development server at [Link]
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 [Link] 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 [Link] runserver 5000 .

10. Visual Studio will launch a notification stating "Your application now running on
port 8000 is available." Click the Open in Browser button. Or Ctrl+click the
[Link] 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 [Link] resides):

Bash

python3 [Link] 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 [Link] (that contains the
functions that define pages in your web app) and [Link] (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 [Link] (app configuration), [Link] (for creating
an administrative interface), and [Link] (for tests), which are not covered here.

13. Modify hello/[Link] to match the following code, which creates a single view
for the app's home page:
 Python

from [Link] import HttpResponse

def home(request):
return HttpResponse("Hello, Django!")

14. Create a file, hello/[Link] , with the contents below. The [Link] 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 [Link] function
that you just added to hello/[Link] :

Python

from [Link] import path

from hello import views

urlpatterns = [
path("", [Link], name="home"),
]

15. The web_project folder also contains a [Link] file, which is where URL routing is
actually handled. Open web_project/[Link] 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/[Link] using [Link] , which keeps the app's routes
contained within the app. This separation is helpful when a project contains
multiple apps.

Python

from [Link] import admin

from [Link] import include, path

urlpatterns = [
path("", include("[Link]")),
]

16. Save all modified files.

17. In the VS Code Terminal, run the development server with python3 [Link]
runserver and open a browser to [Link] 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 new features and improvements in 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 [Link] 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:

[Link] .

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 ([Link]) 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 palette. 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\[Link], food\fruits\[Link],
food\fruits\[Link], food\fruits\apples\[Link],
food\fruits\oranges\[Link], food\vegetables\[Link]

5. Create a new python file in your python-scripts directory:

PowerShell

mkdir src
new-item src\[Link]

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 [Link] 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 [Link] file and then select
save:

Python
 import os

root = [Link]('..', 'food')

for directory, subdir_list, file_list in [Link](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 .\[Link]

You should see output that looks like this:

PowerShell

Directory: ..\food
Subdirectory: fruits
Subdirectory: vegetables

Directory: ..\food\fruits
Subdirectory: apples
Subdirectory: oranges
File: [Link]
File: [Link]
File: [Link]

Directory: ..\food\fruits\apples
File: [Link]

Directory: ..\food\fruits\oranges
File: [Link]

Directory: ..\food\vegetables
File: [Link]
 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-
[Link] > [Link]

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 [Link]

2. Open the [Link] file, paste the following code into the file, and save
it:

７ Note

[Link] 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 = [Link]('..', 'food')

for directory, subdir_list, file_list in [Link](root):
for name in file_list:
source_name = [Link](directory, name)
timestamp = [Link](source_name)
 modified_date =
str([Link](timestamp)).replace(':', '.')
target_name = [Link](directory,
f'{modified_date}_{name}')

print(f'Renaming: {source_name} to: {target_name}')

[Link](source_name, target_name)

3. Test your [Link] script by running it: python3 [Link]

and then running your [Link] script again: python3 list-
[Link]

4. You should see output that looks like this:

PowerShell

Renaming: ..\food\fruits\[Link] to: ..\food\fruits\2019-07-18

12.24.46.385185_banana.txt
Renaming: ..\food\fruits\[Link] to: ..\food\fruits\2019-07-18
12.24.46.391170_blueberry.txt
Renaming: ..\food\fruits\[Link] to: ..\food\fruits\2019-07-18
12.24.46.389174_strawberry.txt
Renaming: ..\food\fruits\apples\[Link] to:
..\food\fruits\apples\2019-07-18 12.24.46.395160_honeycrisp.txt
Renaming: ..\food\fruits\oranges\[Link] to:
..\food\fruits\oranges\2019-07-18 12.24.46.398151_mandarin.txt
Renaming: ..\food\vegetables\[Link] to: ..\food\vegetables\2019-07-
18 12.24.46.402496_carrot.txt

PS C:\src\python-scripting\src> python3 .\[Link]

..\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 [Link] > food-directory-
[Link]

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('<[Link]
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 [Link] , 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 [Link]?
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 [Link] 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 [Link] launcher will only work

if you are using a version of Python installed from [Link] . 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 [Link] 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 [Link] 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\[Link]"

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 [Link]
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 [Link] 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.
Overview of Android development on
Windows
Article • 11/21/2024

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

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 [Link], extended from mobile to desktop
scenarios, with UI controls rebuilt for performance and extensibility.
Migrate [Link] 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 • 11/22/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 [Link] . We are grateful for the support of our developer
community and remain committed to listening to feedback as we evolve
experiences.

Amazon Appstore on Windows 11 discontinuation notice .

Windows Subsystem for Android™️repository on GitHub
Apps from the Amazon Appstore
Accessibility for mobile apps on Windows

Set up your development environment

To test your Android app in the Windows desktop environment, a bit of set up will be
required.

Prerequisites
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 [Link]: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 [Link]

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

[Link] Microsoft Corporation

[Link] Subsystem for Android(TM)

[Link].SDK_INT 33

[Link] 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 [Link].LAUNCH_URI and add a string extra to the
intent named [Link].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("[Link].LAUNCH_URI");

[Link]("[Link].EXTRA_URI", "ms-calculator:");

try {
startActivity(intent);
} catch (ActivityNotFoundException e) {
// Not running in Windows Subsystem for Android&trade;️(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 .
Release Notes for Windows Subsystem
for Android™️
Article • 11/21/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 .

For the latest information on Windows Subsystem for Android™️, see the WSA GitHub
repository Discussions .

For the latest information on Windows Subsystem for Android™️, see the WSA GitHub
repository Discussions .

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
Get started with native Android
development on Windows
Article • 11/21/2024

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 [Link] (for 64-bit machines) or [Link] (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 latest 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 > [Link] > 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 > [Link]

The manifest file describing the fundamental characteristics of the app and each of its
components.

Gradle Scripts > [Link]

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 [Link] 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, [Link] , 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, [Link] , 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 2 Microsoft Design System: Fluent UI for Android

Fluent 2 Microsoft Design System: Android Overview

Sketch toolkit
Android font
Android User Interface Guidelines
Guidelines for Android app icons
Get started developing for Android
using React Native
Article • 11/22/2024

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 and set the ANDROID_HOME environment
variable. Follow the instructions at Set Up Your Environment - React Native . Be
sure to set the Development OS selection to "Windows" and the Target OS
selection to Android.

3. Set the JAVA_HOME environment variable. The Gradle tool used to build Android
apps requires a specific version requirement for the Java SDK. To find the
supported version, in Android Studio, go to Settings->Build, Execution,
Deployment->Build Tools->Gradle. Write down the path selected in the Gradle
JDK drop-down. Set the JAVA_HOME environment variable to this path using the
following steps:

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.
Set the Variable name to JAVA_HOME and the value to the path that you
retrieved from Android Studio.
 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 react-native@[Link].X init <projectName> --version [Link].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
[Link] . 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={[Link]}>
Edit <Text style={[Link]}>[Link]</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'.
Get started developing a PWA or Hybrid
web app for Android
Article • 11/22/2024

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:
 [Link] 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/[Link] 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]]
([Link] ).

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.
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.
 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# Fundamentals What's new

VIDEO TRAINING TRAINING

Learn C# video C# learning Foundational
series paths C# Certification
-…

Learn to program
Major concepts and features of the C# language

Get started 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

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 Language reference Language 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

[Link] Core tutorials Windows Presentation Dapr for .NET developers
Foundation (.NET 5+)
What is [Link] Core? Cloud native .NET apps
Windows Forms (.NET 5+)
[Link] Core in Visual Studio Serverless apps with Azure
.NET Multi-platform App UI
[Link] 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
[Link] 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 [Link] Core API

API reference documentation reference reference
for .NET API reference documentation API reference documentation
for .NET Framework for [Link] Core

[Link] API reference .NET Package-provided

API reference documentation API reference
for [Link] Reference documentation for
package-provided .NET APIs

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# 9

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 [Link] 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 [Link] projects, [Link] 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, [Link], and [Link] 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

[Link]

Kubernetes and Container Orchestration

Explainer Video
[Link]

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 [Link] 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

[Link] 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
environment.

 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 [Link] 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.

[Link] ( [Link] ) 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
[Link]
Set up your dev environment on Windows for Rust
Set up your dev environment on
Windows for Rust
Article • 12/13/2024

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 ( [Link] ), 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 ( [Link] ), 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 > [Link] 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

// [Link]
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 [Link] 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 "[Link] has been detected in this workspace. Would you like to
generate launch configurations for its targets?". Click Yes. Then close the
[Link] 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

[Link]

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
[Link] (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 [Link] .

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 ( [Link] ), 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 [Link] file at the
root of the project. A [Link] 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

# [Link]
...

[[Link]]
version = "0.43.0"
features = [
"Foundation_Collections",
 "Web_Syndication",
]

5. Then, open the rss_reader project's src/[Link] source code file. There you'll find
the Cargo default "Hello, world!" code. Add the following use statement to the
beginning of [Link] :

Rust

// src\[Link]
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\[Link]
...

fn main() -> Result<()> {

let uri = Uri::CreateUri(h!("[Link]

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\[Link]
...

fn main() -> windows::core::Result<()> {

let uri = Uri::CreateUri(h!("[Link]
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\[Link]
...

fn main() -> windows::core::Result<()> {

let uri = Uri::CreateUri(h!("[Link]
let client = SyndicationClient::new()?;
let feed = [Link](&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\[Link]
...

fn main() -> windows::core::Result<()> {

let uri = Uri::CreateUri(h!("[Link]
let client = SyndicationClient::new()?;

[Link](
h!("User-Agent"),
h!("Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64;
Trident/6.0)"),
)?;

let feed = [Link](&uri)?.get()?;

for item in [Link]()? {

println!("{}", [Link]()?.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 [Link] , and add the Windows dependencies for this
project:
 Rust

# message_box\[Link]
...

[[Link]]
version = "0.43.0"
features = [
"Win32_Foundation",
"Win32_UI_WindowsAndMessaging",
]

4. Now open the project's src/[Link] 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\[Link]
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 ｂ [Link] Core and Angular ｂ Python
ｇ Open code from a repo web app ｂ JavaScript
ｅ Get AI assistance with ｂ [Link] Core and React ｂ F#
GitHub Copilot web app

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.

Git, GitHub, and Azure DevOps 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

[Link] Core .NET Fundamentals
Azure cloud Windows app development
Python .NET desktop development with WPF
[Link] .NET development with Windows Forms
Office/Sharepoint development .NET Framework
Containers MAUI (.NET Multi-platform App UI) development
Windows development with C++

Game development Other toolsets

Unity Visual Studio extension development
Unreal Engine Linux development with C++

Blogs - @VisualStudio on X - 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 TRAINING

Get started for Azure developers Build skills with Microsoft Learn
for Azure

ARCHITECTURE OVERVIEW
Design your app using the Azure Achieve organizational goals
Architecture Center with the Cloud Adoption
Framework

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

(AKS)
 Fast NoSQL database with Process events with serverless Simplify the deployment,
open APIs for any scale code 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 in Azure Microsoft Entra ID

The best virtual desktop (Preview) Synchronize on-premises
experience, delivered on Azure Simplify operations and directories and enable single
management from cloud to sign-on
edge with an AI companion

Virtual Machines
Provision virtual machines for
Ubuntu, Red Hat, Windows,
and more

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

Commercial marketplace Azure Native ISV Services

An online marketplace of Integrated partner solutions
applications and services from that you can use in Azure to
independent software vendor enhance your cloud
(ISV) partners. infrastructure.
 .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 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 9 ｐ .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 [Link] 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
[Link] Core tutorials .NET Multi-platform App UI (.NET MAUI)
What is [Link] Core? [Link]
[Link] Core in Visual Studio [Link]
[Link] MVC apps in Windows containers [Link]
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 AI and machine learning

Azure for .NET developers AI for .NET developers
.NET Aspire Build a chat app
Migrate on-premises .NET web apps or services Understand prompt engineering
Azure services for .NET developers Implement RAG using vector search
Azure SDK for .NET Get started with the .NET enterprise chat sample
 Deploying Azure Resources with F# Build custom AI solutions with [Link]
Azure Cognitive Services
Azure machine learning
F# for Machine Leaning

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

[Link] Core API reference [Link] API reference

API reference documentation for [Link] Core API reference documentation for [Link]

.NET Package-provided API reference C# language reference

Reference documentation for package-provided C# language reference and specification
.NET APIs

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.