Compartilhar via


Use command-line parameters to install, update, and manage Visual Studio

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

When you install Visual Studio programmatically or from a command prompt, you can use various command-line parameters to control or customize the installation to perform the following actions:

  • Start the installation on the client with certain options and behaviors preselected.
  • Automate the installation or update process.
  • Create or maintain a network layout of the product files for installing or updating client machines.

The command-line options described below can either be used with the setup bootstrapper, which is the small (~1 MB) file (for example, vs_enterprise.exe) that initiates the download process, or with the installer. All of the commands and parameters listed below are designed to work with the bootstrappers unless it's explicitly specified to be installer only. Note that client machines may only have the installer available for programmatic execution if Visual Studio was installed via a layout.

It is also possible to use the Administrator Update package, which is available to download from the Microsoft Update Catalog, to programatically update your network layout. More information how to do this can be found in the Update or modify your layout documentation.

To get the bootstrapper for Visual Studio 2017 version 15.9, download one of the following bootstrapper files below:

Edition Bootstrapper
Visual Studio Enterprise 2017 version 15.9 vs_enterprise.exe
Visual Studio Professional 2017 version 15.9 vs_professional.exe
Visual Studio Build Tools 2017 version 15.9 vs_buildtools.exe

Tip

If you previously downloaded a bootstrapper file and want to verify what version it is, here's how. In Windows, open File Explorer, right-click the bootstrapper file, choose Properties, choose the Details tab, and then view the Product version number. To match that number to a release of Visual Studio, refer to the Visual Studio build numbers and release dates page.

The Visual Studio Installer can be found here: C:\Program Files (x86)\Microsoft Visual Studio\Installer\setup.exe. Note that you can't initiate the installer programmatically from same directory that the installer resides in.

Install, Update, Modify, Repair, Uninstall, and Export commands and command-line parameters

When invoking the Visual Studio bootstrapper or the installer programmatically to install the product or to maintain a layout, the first parameter is the command (the verb) that describes the operation to perform. The subsequent optional command line parameters, which are all prefixed by two dashes (--), further define how that operation is supposed to happen. All Visual Studio command-line parameters are case-insensitive, and additional examples can be found on the Command-line parameter examples page.

Syntax example: vs_enterprise.exe [command] <optional parameters>...

Command Description
(blank) The default command both installs the product, and it is used for all layout maintenance operations.
modify Modifies an installed product.
update Updates an installed product.
repair Repairs an installed product.
uninstall Uninstalls an installed product.
export Exports installation selection to an installation configuration file. Note: Can only be used with vs_installer.exe or setup.exe.

Important

When specifying multiple distinct workloads or components or languages, you must repeat the --add or --remove command-line switch for each item.

Parameters Description
--installPath <dir> For the default install command, this parameter is Optional and describes where the instance will be installed on the client machine. For other commands like update or modify, this parameter is Required and denotes the installation directory for the instance to act upon.
--add <one or more workload or component IDs> Optional: During an install or modify command, this repeatable parameter specifies one or more workload or component IDs to add. The required components of the artifact are installed, but not the recommended or optional components. You can control additional components globally using --includeRecommended and/or --includeOptional parameters. To include multiple workloads or components, repeat the --add command (for example, --add Workload1 --add Workload2). For finer-grained control, you can append ;includeRecommended or ;includeOptional to the ID (for example, --add Workload1;includeRecommended or --add Workload2;includeRecommended;includeOptional). For more information, see the Workload and component IDs page.
--remove <one or more workload or component IDs> Optional: During a modify command, this repeatable parameter specifies one or more workload or component IDs to remove. It complements and behaves similarly to the --add parameter.
--addProductLang <language-locale> Optional: During an install or modify command, this repeatable parameter specifies the UI language packs that should be installed with the product. If not present, the installation uses the language pack that corresponds to the machine locale. For more information, see the List of language locales section on this page.
--removeProductLang <language-locale> Optional: During an install or modify command, this repeatable parameter determines the UI language packs that should be removed from the product. It complements and behaves similarly to the --addProductLang parameter.
--in <path> Optional: The URI or path to a response file, which can contain configuration settings.
--all Optional: During an install or modify command, this parameter causes all workloads and components for the product to be installed.
--allWorkloads Optional: During an install or modify command, this parameter installs all workloads and components, but no recommended or optional components.
--includeRecommended Optional: During an install or modify command, this parameter includes the recommended components for any workloads that are installed, but not the optional components. The workloads are specified either with --allWorkloads or --add.
--includeOptional Optional: During an install or modify command, this parameter includes the optional components for any workloads that are installed, but not the recommended components. The workloads are specified either with --allWorkloads or --add.
--quiet, -q Optional: Used with any command, this parameter prevents any user interface from being displayed while the command is being executed.
--passive, -p Optional: This parameter causes the user interface to be displayed in a non-interactive manner. This parameter is mutually exclusive from (and in fact overrides) the --quiet parameter.
--norestart Optional: This parameter must be paired with either the --passive or --quiet parameters. During an install, update, or modify command, adding the --norestart parameter will delay any necessary reboot.
--force Optional: This parameter forces Visual Studio to close even if any Visual Studio process is in use.
--installWhileDownloading Optional: During an install, update, or modify command, this parameter allows Visual Studio to both download and install the product in parallel. It's the default experience.
--downloadThenInstall Optional: During an install, update, or modify command, this parameter forces Visual Studio to download all files before installing them. It is mutually exclusive from the --installWhileDownloading parameter.
--channelURI Optional: During an update command, you can pass in a new channelURI to change the update settings location. Recommend to pair with --installPath parameter so that it's very explicit which instance of Visual Studio you're configuring. See syntax examples of --channelURI
--nickname <name> Optional: During an install command, this parameter defines the nickname to assign to an installed product. The nickname can't be longer than 10 characters.
--productKey Optional: During an install command, this parameter defines the product key to use for an installed product. It's composed of 25 alphanumeric characters in the format xxxxxxxxxxxxxxxxxxxxxxxxx.
--help, --?, -h, -? Displays an offline version of this page.
--config <path> Optional: During an install or modify operation, this determines the workloads and components to add based on a previously saved installation configuration file. This operation is additive and it won't remove any workload or component if they aren't present in the file. Also, items that don't apply to the product won't be added. During an export operation, this determines the location to save the installation configuration file.

Layout command and command-line parameters

All layout management operations are run using the bootstrapper exe and they assume that the command is the default Install (blank), regardless of if you're creating or updating a layout. So, all layout management operations should start with the initial required --layout parameter. The table below describes the other parameters you can use to create or update a layout using the command line.

Layout parameters Description
--layout <dir> Specifies a directory to create or update an offline install cache. For more information, see Create a network-based installation of Visual Studio.
--lang <one or more language-locales> Optional: Used with --layout to prepare an offline install cache with resource packages with the specified language(s). For more information, see the List of language locales section on this page.
--add <one or more workload or component IDs> Optional: One or more workload or component IDs to add. The required components of the artifact are installed, but not the recommended or optional components. You can control additional components globally using --includeRecommended and/or --includeOptional. For finer-grained control, you can append ;includeRecommended or ;includeOptional to the ID (for example, --add Workload1;includeRecommended or --add Workload2;includeOptional). For more information, see the Workload and component IDs page.
Note: If --add is used, only the specified workloads and components and their dependencies are downloaded. If --add isn't specified, all workloads and components are downloaded to the layout.
--includeRecommended Optional: Includes the recommended components for any workloads that are installed, but not the optional components. The workloads are specified either with --allWorkloads or --add.
--includeOptional Optional: Includes the recommended and optional components for any workloads being included in the layout. The workloads are specified with --add.
--keepLayoutVersion Optional: Apply changes to the layout without updating the product version that's included in the layout.
--useLatestInstaller Optional: If present, the latest version of the Visual Studio Installer will be included in your layout, even if it belongs to a newer version of the product. This can be useful if you want to take advantage of new features or bug fixes that are available in the latest installer. For more information, refer to Configure the layout to always use the latest installer documentation.
--verify Optional: Verify the contents of a layout. Any corrupt or missing files are listed.
--fix Optional: Verify the contents of a layout. If any files are corrupt or missing, they're redownloaded. Internet access is required to fix a layout.
--clean <one or more paths to catalogs> Optional: Removes old versions of components from a layout that has been updated to a newer version.
Advanced layout parameters Description
--channelId <id> Optional: The ID of the channel for the instance to be installed. This is required for the install command, and ignored for other commands if --installPath is specified.
--channelUri <uri> Optional: The URI of the channel manifest. This value governs the source location of updates and the initial value is configured in the layout's response.json file. Refer to syntax examples of --channelURI for possible values. If updates aren't wanted, --channelUri can point to a non-existent file (for example, --channelUri C:\doesntExist.chman). This can be used for the install command; it's ignored for other commands.
--installChannelUri <uri> Optional: The URI of the channel manifest to use for the installation. The URI specified by --channelUri (which must be specified when --installChannelUri is specified) is used to detect updates. This can be used for the install command; it's ignored for other commands.
--installCatalogUri <uri> Optional: The URI of the catalog manifest to use for the installation. If specified, the channel manager attempts to download the catalog manifest from this URI before using the URI in the install channel manifest. This parameter is used to support offline install, where the layout cache will be created with the product catalog already downloaded. This can be used for the install command; it's ignored for other commands.
--productId <id> Optional: The ID of the product for the instance that will be installed. This is pre-populated in normal installation conditions. The productID is something like "Microsoft.VisualStudio.Product.Enterprise".
--wait Optional: The process will wait until the install is completed before returning an exit code. This is useful when automating installations where one needs to wait for the install to finish to handle the return code from that install.
--locale <language-locale> Optional: Change the display language of the user interface for the installer itself. Setting will be persisted. For more information, see the List of language locales section on this page.
--cache Optional: If present, packages will be kept after being installed for subsequent repairs. This overrides the global policy setting to be used for subsequent installs, repairs, or modifications. The default policy is to cache packages. This is ignored for the uninstall command. Read how to disable or move the package cache for more information.
--nocache Optional: If present, packages will be deleted after being installed or repaired. They'll be downloaded again only if needed and deleted again after use. This overrides the global policy setting to be used for subsequent installs, repairs, or modifications. The default policy is to cache packages. This is ignored for the uninstall command. Read how to disable or move the package cache for more information.
--noUpdateInstaller Optional: If present, prevents the installer from updating itself when quiet is specified. The installer will fail the command and return a non-zero exit code if noUpdateInstaller is specified with quiet when an installer update is required.
--noWeb Optional: If present, Visual Studio setup uses the files in your layout directory to install Visual Studio. If a user tries to install components that aren't in the layout, setup fails. For more information, see Deploying from a network installation.

Important: This switch doesn't stop Visual Studio setup from checking for updates. For more information, see Control updates to network-based Visual Studio deployments.
--path <name>=<path> Optional: Used to specify custom install paths for the installation. Supported path names are shared, cache, and install.
--path cache=<path> Optional: Uses the location you specify to download installation files. This location can only be set the first time that Visual Studio is installed. Example: --path cache="C:\VS\cache"
--path shared=<path> Optional: Contains shared files for side-by-side Visual Studio installations. Some tools and SDKs install to a location on this drive, while some others might override this setting and install to another drive. Example: --path shared="C:\VS\shared"

Important: This can be set only once and on the first time that Visual Studio is installed.
--path install=<path> Optional: Equivalent to –-installPath. Specifically, --installPath "C:\VS" and --path install="C:\VS" are equivalent. Only one of these commands can be used at a time.

Configure source location of updates command and command-line parameters

You can programmatically configure the source location of updates for a given instance of Visual Studio by using either the installer or the bootstrapper on the client machine, and passing in the desired update channel.

modifySettings parameters Description
--installPath <dir> Recommended to use to specify which instance of Visual Studio to act upon.
--newChannelUri Required: The URI of the channel manifest. This value specifies where the next source location of updates will be. Refer to syntax examples of --channelURI for possible values. If updates aren't wanted, --channelUri can point to a non-existent file (for example, --channelUri C:\doesntExist.chman).
--channelUri The URI of the old channel manifest. Can be used if the --installPath is not known. Must be used in conjunction with productID to identify the right instance to act upon.
--productId <id> Must be used if --channelUri is specified and is used to identify the right instance to act upon. The productID is something like "Microsoft.VisualStudio.Product.Enterprise".
--quiet, -q Optional: This parameter prevents any user interface from being displayed while the command is being executed.

Syntax examples:

C:\>"C:\Program Files (x86)\Microsoft Visual Studio\Installer\setup.exe" modifySettings --installPath "C:\Program Files\Microsoft\Visual Studio\2022\Enterprise" --newChannelURI https://aka.ms/vs/17/release.LTSC.17.0/channel

C:\>"C:\Program Files\Microsoft\Visual Studio\2022\Enterprise\vs_enterprise.exe" modifySettings --channelURI https://aka.ms/vs/17/release.LTSC.17.0/channel --productID Microsoft.VisualStudio.Product.Enterprise --newChannelURI \\layoutserver\share\path\channelmanifest.json --quiet

Administrator Update command and command-line parameters

You can download an Administrator Update from the Microsoft Update Catalog and use it to update either your client installation or your layout.

If you're updating a layout to a particular version of Visual Studio, just download the Administrator Update to the computer that's hosting the layout, open up a command prompt on that computer and run a command like this: visualstudioupdate-17.0.0to17.1.5.exe layout --layoutPath c:\VSLayout

On the client, if you download the Administrator Update into your installation directory on your client machine, you can just double-click on the file to apply the update. You can also open a command window and pass some of the parameters below to change the default behavior.

If you are deploying the administrator update through Microsoft Endpoint Manager (SCCM), you can modify the package to adjust the behavior by using the parameters below. You can also control the parameters via a configuration file on the client machine. For more information, refer to Methods for configuring an administrator update

Note that all Administrator Update parameters are default run in the "update" context unless the layout verb is specified.

Administrator update parameters Description
--installerUpdateArgs [optional parameters] This parameter functions as a "pass-through array" of specific parameters that are relevant to administrator update scenarios. Optional parameters that are enabled for this purpose are:

--quiet: This is the default experience for administrator updates and is listed here for completeness.
--passive: This parameter overrides the --quiet parameter. It causes the UI to appear in a non-interactive manner.
--norestart: This parameter must be used in conjunction with either --quiet or --passive and it causes any necessary reboots to be delayed.
--noWeb: This parameter prevents Visual Studio from checking on the internet for updates to the product.
--force: This parameter forces Visual Studio to close, even if Visual Studio is in use. Use this parameter with caution, as it may cause loss of work. This parameter must be used in user context.
--installWhileDownloading: This parameter allows Visual Studio to both download and install the product in parallel. It's the default experience for administrator updates and is listed here for completeness.
--downloadThenInstall: This parameter forces Visual Studio to download all files before installing them. It is mutually exclusive from the --installWhileDownloading parameter.
--checkPendingReboot The update will be aborted if there is a pending reboot on the machine, regardless of which application may have caused it. The default is to not check for pending reboots.

Syntax example: visualstudioupdate-16.9.0to16.9.4.exe --installerUpdateArgs=--force,--noWeb --checkPendingReboot

List of workload IDs and component IDs

For a list of workload and component IDs sorted by Visual Studio product, see the Visual Studio workload and component IDs page.

List of language locales

Language-locale Language
Cs-cz Czech
De-de German
En-us English
Es-es Spanish
Fr-fr French
It-it Italian
Ja-jp Japanese
Ko-kr Korean
Pl-pl Polish
Pt-br Portuguese - Brazil
Ru-ru Russian
Tr-tr Turkish
Zh-cn Chinese - Simplified
Zh-tw Chinese - Traditional

Error codes

Depending on the result of the operation, the %ERRORLEVEL% environment variable is set to one of the following values:

Value Result
0 Operation completed successfully
740 Elevation required
1001 Visual Studio installer process is running
1003 Visual Studio is in use
1602 Operation was canceled
1618 Another installation running
1641 Operation completed successfully, and reboot was initiated
3010 Operation completed successfully, but install requires reboot before it can be used
5003 Bootstrapper failed to download installer
5004 Operation was canceled
5005 Bootstrapper command-line parse error
5007 Operation was blocked - the computer does not meet the requirements
8001 Arm machine check failure
8002 Background download precheck failure
8003 Out of support selectable failure
8004 Target directory failure
8005 Verifying source payloads failure
8006 Visual Studio processes running
-1073720687 Connectivity failure
-1073741510 Microsoft Visual Studio Installer was terminated (by the user or external process)
Other
(for example:
-1, 1, 1603)
Failure condition occurred - check the logs for more information

Each operation generates several log files in the %TEMP% directory that indicate the progress of the installation. Sort the folder by date and look for files that begin with dd_bootstrapper, dd_client, and dd_setup for the bootstrapper, the installer app, and the setup engine, respectively.

Support or troubleshooting

Sometimes, things can go wrong. If your Visual Studio installation fails, see Troubleshoot Visual Studio installation and upgrade issues for step-by-step guidance.

Here are a few more support options:

  • We also offer an installation chat (English only) support option for installation-related issues.
  • Report product issues to us via the Report a Problem tool that appears both in the Visual Studio Installer and in the Visual Studio IDE. If you're an IT Administrator and don't have Visual Studio installed, you can submit IT Admin feedback here.
  • Suggest a feature, track product issues, and find answers in the Visual Studio Developer Community.

See also