Skip to content

Commit 5a4c9f3

Browse files
denelonmattwojo
denelon
and
mattwojo
authored
Update Settings (MicrosoftDocs#5552)
* Update Settings * Editorial updates --------- Co-authored-by: Matt Wojciakowski <[email protected]>
1 parent e81eb98 commit 5a4c9f3

File tree

1 file changed

+140
-82
lines changed

1 file changed

+140
-82
lines changed

‎hub/package-manager/winget/settings.md

Lines changed: 140 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,15 @@
11
---
22
title: settings command
33
description: Provides customizations for the Windows Package Manager.
4-
ms.date: 08/02/2022
4+
ms.date: 07/08/2025
55
ms.topic: article
6-
ms.localizationpriority: medium
76
---
87

98
# settings command (winget)
109

11-
The **settings** command of the [winget](./index.md) 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.
10+
The **settings** command of [WinGet](./index.md) allows you to customize your Windows Package Manager client experience. You can change defaults and try out experimental features that are available in your client.
1211

13-
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](https://code.visualstudio.com/).
12+
The **settings** command will launch your default JSON editor. Windows by default will launch Notepad as an option. We recommend using a tool like [Visual Studio code](https://code.visualstudio.com/).
1413

1514
>[!NOTE]
1615
>You can easily install Visual Studio Code by typing `winget install Microsoft.VisualStudioCode`
@@ -21,49 +20,68 @@ The following aliases are available for this command:
2120

2221
- config
2322

23+
## Sub-commands
24+
25+
The following sub-commands are available.
26+
27+
| Sub-Command | Description |
28+
|-------------|-------------|
29+
| **export** | Exports settings. |
30+
| **set** | Sets the value of an administrator setting. |
31+
| **reset** | Resets an administrator setting to its default value. |
32+
33+
## Options
34+
The following options are available:
35+
36+
| Argument | Description |
37+
|-------------|-------------|
38+
| **--enable** | Enables the specified administrator setting. |
39+
| **--disable** | Disables the specified administrator setting. |
40+
| **-?,--help** | Shows help about the selected command. |
41+
| **--wait** | Prompts the user to press any key before exiting. |
42+
| **--logs,--open-logs** | Opens the default logs location. |
43+
| **--verbose,--verbose-logs** | Enables verbose logging for winget. |
44+
| **--nowarn,--ignore-warnings** | Suppresses warning outputs. |
45+
| **--disable-interactivity** | Disables interactive prompts. |
46+
| **--proxy** | Sets a proxy to use for this execution. |
47+
| **--no-proxy** | Disables the use of proxy for this execution. |
48+
2449
## Use the winget settings command
2550

2651
Launch your default JSON editing tool: `winget settings`
2752

28-
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](https://aka.ms/winget-settings) where you can discover the latest experimental features and settings.
53+
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 [WinGet CLI Settings](https://aka.ms/winget-settings) link, where you can discover the latest experimental features and settings.
2954

30-
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.
55+
The code snippet below shows an example of what your settings file might look like with visual output modifications and experimental features enabled.
3156

3257
```json
3358
{
3459
"$schema": "https://aka.ms/winget-settings.schema.json",
3560

36-
// For documentation on these settings, see: https://aka.ms/winget-settings
37-
"experimentalFeatures": {
38-
"dependencies": true,
39-
"directMSI": false,
40-
"zipInstall": false,
41-
},
4261
"visual": {
62+
"enableSixels": true,
4363
"progressBar": "rainbow"
4464
},
45-
"source": {
46-
"autoUpdateIntervalInMinutes": 5
47-
},
65+
"experimentalFeatures": {
66+
"experimentalARG": true,
67+
"experimentalCMD": true
68+
}
4869
}
4970
```
5071

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

53-
> [!NOTE]
54-
> Experimental features are only available in preview builds. Instructions for obtaining a preview build can be found in the [GitHub repository](https://github.com/microsoft/winget-cli).
55-
5674
## Updating settings
5775

58-
The following settings are available for the 1.0 release of the Windows Package Manager.
76+
The following settings are available for the 1.11 release of the Windows Package Manager.
5977

6078
### source settings
6179

6280
The `source` settings involve configuration to the WinGet source.
6381

6482
```json
6583
"source": {
66-
"autoUpdateIntervalInMinutes": 3
84+
"autoUpdateIntervalInMinutes": 60
6785
},
6886
```
6987

@@ -72,7 +90,7 @@ The `source` settings involve configuration to the WinGet source.
7290
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.
7391

7492
- Disable: 0
75-
- Default: 5
93+
- Default: 15
7694

7795
To manually update the source use `winget source update`.
7896

@@ -82,7 +100,8 @@ The `visual` settings involve visual elements that are displayed by WinGet
82100

83101
```json
84102
"visual": {
85-
"progressBar": "accent"
103+
"enableSixels": true,
104+
"progressBar": "rainbow"
86105
},
87106
```
88107

@@ -91,58 +110,52 @@ The `visual` settings involve visual elements that are displayed by WinGet
91110
Color of the progress bar that WinGet displays when not specified by arguments.
92111

93112
- accent (default)
94-
- retro
95113
- rainbow
114+
- retro
115+
- sixel
116+
- disabled
96117

97-
### installBehavior settings
118+
#### anonymizeDisplayedPaths
98119

99-
The `installBehavior` settings affect the default behavior of installing and upgrading (where applicable) packages.
120+
Replaces some known folder paths with their respective environment variables.
100121

101-
### disableInstallNotes
102-
The `disableInstallNotes` behavior affects whether installation notes are shown after a successful install. Defaults to `false` if value is not set or is invalid.
122+
#### enableSizels
103123

104-
```json
105-
"installBehavior": {
106-
"disableInstallNotes": true
107-
},
108-
```
124+
Enables output of sixel images in certain contexts.
109125

110-
### portablePackageUserRoot setting
126+
### logging settings
111127

112-
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.
128+
The `logging` settings control the level of detail in log files. `--verbose-logs` will override this setting and always creates a verbose log.
113129

114-
> Note: This setting value must be an absolute path.
115130

116131
```json
117-
"installBehavior": {
118-
"portablePackageUserRoot": "C:/Users/FooBar/Packages"
119-
},
132+
"logging": {
133+
"level": "verbose"
134+
}
120135
```
121136

122-
### portablePackageMachineRoot setting
123-
124-
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.
137+
#### level
125138

126-
> Note: This setting value must be an absolute path.
139+
The following logging levels are available. Defaults to `info` if the value is not set or is invalid.
127140

128-
```json
129-
"installBehavior": {
130-
"portablePackageMachineRoot": "C:/Program Files/Packages/Portable"
131-
},
132-
```
141+
- verbose
142+
- info
143+
- warning
144+
- error
145+
- critical
133146

134147
### preferences and requirements settings
135148

136149
Some of the settings are duplicated under `preferences` and `requirements`.
137150

138-
- 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.
151+
- The `preferences` setting controls 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.
139152
- 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.
140153

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

143156
#### scope
144157

145-
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](./troubleshooting.md#scope-for-specific-user-vs-machine-wide).
158+
The `scope` behavior controls 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](./troubleshooting.md#scope-for-specific-user-vs-machine-wide).
146159

147160
```json
148161
"installBehavior": {
@@ -154,7 +167,7 @@ The `scope` behavior affects the choice between installing a package for the cur
154167

155168
#### locale
156169

157-
The `locale` behavior affects the choice of installer based on installer locale. The matching parameter is `--locale`, and uses bcp47 language tag.
170+
The `locale` behavior controls the choice of installer based on installer locale. The matching parameter is `--locale`, and uses bcp47 language tag.
158171

159172
```json
160173
"installBehavior": {
@@ -166,7 +179,7 @@ The `locale` behavior affects the choice of installer based on installer locale.
166179

167180
#### architectures
168181

169-
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.
182+
The `architectures` behavior controls what architectures will be selected when installing a package. The matching parameter is `--architecture`. Only architectures compatible with your system can be selected.
170183

171184
```json
172185
"installBehavior": {
@@ -178,7 +191,7 @@ The `architectures` behavior affects what architectures will be selected when in
178191

179192
#### installerTypes
180193

181-
The `installerTypes` behavior affects what installer types will be selected when installing a package. The matching parameter is `--installer-type`.
194+
The `installerTypes` behavior controls what installer types will be selected when installing a package. The matching parameter is `--installer-type`.
182195

183196
```json
184197
"installBehavior": {
@@ -188,39 +201,97 @@ The `installerTypes` behavior affects what installer types will be selected when
188201
},
189202
```
190203

191-
### uninstallBehavior
204+
### installBehavior settings
205+
206+
The `installBehavior` settings control the default behavior of installing and upgrading (where applicable) packages.
207+
208+
#### disableInstallNotes
209+
210+
The `disableInstallNotes` setting determines whether installation notes are shown after a successful install. Defaults to `false` if value is not set or is invalid.
211+
212+
```json
213+
"installBehavior": {
214+
"disableInstallNotes": true
215+
},
216+
```
217+
218+
#### portablePackageUserRoot setting
219+
220+
The `portablePackageUserRoot` setting defines the default root directory for installing packages under the `User` scope. This applies only to packages with the `portable` installer type. Defaults to `%LOCALAPPDATA%/Microsoft/WinGet/Packages/` if value is not set or is invalid.
221+
222+
This setting value must be an absolute path.
223+
224+
```json
225+
"installBehavior": {
226+
"portablePackageUserRoot": "C:/Users/FooBar/Packages"
227+
},
228+
```
229+
230+
#### portablePackageMachineRoot setting
231+
232+
The `portablePackageMachineRoot` setting defines the default root directory for installing packages under the `Machine` scope. This applies only to packages with the `portable` installer type. Defaults to `%PROGRAMFILES%/WinGet/Packages/` if the value is not set or is invalid.
233+
234+
This setting value must be an absolute path.
235+
236+
```json
237+
"installBehavior": {
238+
"portablePackageMachineRoot": "C:/Program Files/Packages/Portable"
239+
},
240+
```
241+
242+
#### defaultInstallRoot
243+
244+
The `defaultInstallRoot` setting specifies the default install location for packages that require an explicit install path, if the install location is not specified.
245+
246+
#### maxResumes
247+
248+
The `maxResumes` setting specifies the maximum number of resume attempts allowed for a single resume ID. This prevents continuous reboots if an installation requiring a reboot is not properly detected.
192249

193-
The `uninstallBehavior` settings affect the default behavior of uninstalling (where applicable) packages.
250+
#### archiveExtractionMethod
251+
252+
The `archiveExtractionMethod` setting controls how the installer extracts archives. Supported values are `shellApi` and `tar`.
253+
254+
- `shellApi` uses the Windows Shell API to extract archives.
255+
256+
- `tar` uses the tar command to extract archives.
257+
258+
### UninstallBehavior
259+
260+
The `uninstallBehavior` setting controls whether the default uninstall process removes all files and directories relevant to this package. Only applies to the portable `installerType`.
194261

195262
#### purgePortablePackage
196263

197-
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.
264+
The `purgePortablePackage` setting controls 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.
198265

199266
```json
200267
"uninstallBehavior": {
201268
"purgePortablePackage": true
202269
},
203270
```
204271

272+
### ConfigureBehavior
273+
274+
The `ConfigureBehavior` setting specifies the default root directory where PowerShell modules are installed to when applying a configuration.
275+
205276
### downloadBehavior
206277

207-
The `downloadBehavior` settings affect the default behavior of downloading packages.
278+
The `downloadBehavior` settings control the default directory where installers are downloaded to.
208279

209280
#### defaultDownloadDirectory
210281

211-
The `defaultDownloadDirectory` setting affects the default directory where packages are downloaded to. Defaults to `%USERPROFILE%/Downloads` if value is not set or is invalid.
282+
The `defaultDownloadDirectory` setting controls the default directory where packages are downloaded to. Defaults to `%USERPROFILE%/Downloads` if value is not set or is invalid.
212283

213-
> Note: This setting value must be an absolute path.
284+
This setting value must be an absolute path.
214285

215286
```json
216287
"downloadBehavior": {
217288
"defaultDownloadDirectory": "C:/Users/FooBar/Downloads"
218289
},
219290
```
220291

221-
### telemetry settings
292+
### Telemetry settings
222293

223-
The `telemetry` settings control whether winget writes ETW events that may be sent to Microsoft on a default installation of Windows.
294+
The `telemetry` settings control whether WinGet writes ETW events that may be sent to Microsoft on a default installation of Windows.
224295

225296
See [details on telemetry](https://github.com/microsoft/winget-cli/blob/master/README.md#datatelemetry), and our [primary privacy statement](https://github.com/microsoft/winget-cli/blob/master/PRIVACY.md).
226297

@@ -234,43 +305,30 @@ See [details on telemetry](https://github.com/microsoft/winget-cli/blob/master/R
234305

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

237-
### network settings
308+
### Network settings
238309

239-
The `network` settings influence how winget uses the network to retrieve packages and metadata.
310+
The `network` settings influence how WinGet uses the network to retrieve packages and metadata.
240311

241312
#### downloader
242313

243-
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.
314+
The `downloader` setting controls which code is used when downloading packages. The default is `do`, which may be managed by Group Policy.
244315

245316
`wininet` uses the [WinINet](/windows/win32/wininet/about-wininet) APIs, while `do` uses the [Delivery Optimization](https://support.microsoft.com/windows/delivery-optimization-in-windows-10-0656e53c-15f2-90de-a87a-a2172c94cf6d) service.
246317

247318
```json
248319
"network": {
249-
"downloader": "do"
320+
"downloader": "wininet"
250321
}
251322
```
252323

253-
### logging settings
254-
255-
The `logging` settings control the level of detail in log files. `--verbose-logs` will override this setting and always creates a verbose log.
256-
257-
258-
```json
259-
"logging": {
260-
"level": "verbose"
261-
}
262-
```
324+
#### doProgressTimeoutInSeconds
263325

264-
#### level
326+
The `doProgressTimeoutInSeconds` specifies the number of seconds to wait without progress before fallback.
265327

266-
The following logging levels are available. Defaults to `info` if the value is not set or is invalid.
328+
### Interactivity
267329

268-
- verbose
269-
- info
270-
- warning
271-
- error
272-
- critical
330+
The `Interactivity` setting controls whether interactive prompts are shown by the Windows Package Manager client.
273331

274-
## Enabling experimental features
332+
### Enabling experimental features
275333

276334
To discover which experimental features are available, go to [https://aka.ms/winget-settings](https://aka.ms/winget-settings) where you can see the experimental features available to you.

0 commit comments

Comments
 (0)