| Author | Reitse Eskens (@2meterDBA), Kirill Kravtsov (@nvarscar) |
| Availability | Windows, Linux, macOS |
Want to see the source code for this command? Check out Install-DbaInstance on GitHub.
Want to see the Bill Of Health for this command? Check out Install-DbaInstance.
Automates SQL Server instance installation across local and remote computers with customizable configuration.
Orchestrates unattended SQL Server installations by generating configuration files and executing setup.exe remotely or locally. Automates the tedious process of creating proper configuration.ini files, handling service accounts, and managing installation prerequisites like pending reboots and authentication protocols.
The function dynamically builds installation configurations based on your parameters, automatically configures optimal settings like tempdb file counts based on CPU cores (SQL 2016+), and handles authentication scenarios including CredSSP for network installations. It can install multiple instances in parallel and manages the complete installation lifecycle from prerequisite checks to post-installation TCP port configuration.
Key automation features include:
Advanced configuration capabilities:
Authentication and credential management:
Installation media requirements:
Remote execution considerations:
Note that the downloaded installation media must be extracted and available to the server where the installation runs.
NOTE: If no ProductID (PID) is found in the configuration files/parameters, Evaluation version is going to be installed.
When using CredSSP authentication, this function will try to configure CredSSP authentication for PowerShell Remoting sessions.
If this is not desired (e.g.: CredSSP authentication is managed externally, or is already configured appropriately,)
it can be disabled by setting the dbatools configuration option 'commands.initialize-credssp.bypass' value to $true.
To be able to configure CredSSP, the command needs to be run in an elevated PowerShell session.
Install-DbaInstance
[[-SqlInstance] <DbaInstanceParameter[]>]
[-Version] <String>
[[-InstanceName] <String>]
[[-SaCredential] <PSCredential>]
[[-Credential] <PSCredential>]
[[-Authentication] <String>]
[[-ConfigurationFile] <Object>]
[[-Configuration] <Hashtable>]
[[-Path] <String[]>]
[[-Feature] <String[]>]
[[-AuthenticationMode] <String>]
[[-InstancePath] <String>]
[[-DataPath] <String>]
[[-LogPath] <String>]
[[-TempPath] <String>]
[[-BackupPath] <String>]
[[-UpdateSourcePath] <String>]
[[-AdminAccount] <String[]>]
[[-Port] <Int32>]
[[-Throttle] <Int32>]
[[-ProductID] <String>]
[[-AsCollation] <String>]
[[-SqlCollation] <String>]
[[-EngineCredential] <PSCredential>]
[[-AgentCredential] <PSCredential>]
[[-ASCredential] <PSCredential>]
[[-ISCredential] <PSCredential>]
[[-RSCredential] <PSCredential>]
[[-FTCredential] <PSCredential>]
[[-PBEngineCredential] <PSCredential>]
[[-SaveConfiguration] <String>]
[-PerformVolumeMaintenanceTasks]
[-Restart]
[-NoPendingRenameCheck]
[-EnableException]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
PS C:\> Install-DbaInstance -Version 2017 -Feature All
Install a default SQL Server instance and run the installation enabling all features with default settings. Automatically generates configuration.ini
PS C:\> Install-DbaInstance -SqlInstance sql2017\sqlexpress, server01 -Version 2017 -Feature Default
Install a named SQL Server instance named sqlexpress on sql2017, and a default instance on server01. Automatically generates configuration.ini.
Default features will be installed.
PS C:\> Install-DbaInstance -Version 2008R2 -SqlInstance sql2017 -ConfigurationFile C:\temp\configuration.ini
Install a default named SQL Server instance on the remote machine, sql2017 and use the local configuration.ini
PS C:\> Install-DbaInstance -Version 2017 -InstancePath G:\SQLServer -UpdateSourcePath '\\my\updates'
Run the installation locally with default settings apart from the application volume, this will be redirected to G:\SQLServer.
The installation procedure would search for SQL Server updates in \my\updates and slipstream them into the installation.
PS C:\> $svcAcc = Get-Credential MyDomain\SvcSqlServer
PS C:\> Install-DbaInstance -Version 2016 -InstancePath D:\Root -DataPath E: -LogPath L: -PerformVolumeMaintenanceTasks -EngineCredential $svcAcc
Install SQL Server 2016 instance into D:\Root drive, set default data folder as E: and default logs folder as L:.
Perform volume maintenance tasks permission is granted. MyDomain\SvcSqlServer is used as a service account for SqlServer.
PS C:\> $svcAcc = [PSCredential]::new("MyDomain\SvcSqlServer$", [SecureString]::new())
PS C:\> Install-DbaInstance -Version 2016 -InstancePath D:\Root -DataPath E: -LogPath L: -PerformVolumeMaintenanceTasks -EngineCredential $svcAcc
The same as the last example except MyDomain\SvcSqlServer is now a Managed Service Account (MSA).
PS C:\> $config = @{
>> AGTSVCSTARTUPTYPE = "Manual"
>> BROWSERSVCSTARTUPTYPE = "Manual"
>> FILESTREAMLEVEL = 1
>> }
PS C:\> Install-DbaInstance -SqlInstance localhost\v2017:1337 -Version 2017 -SqlCollation Latin1_General_CI_AS -Configuration $config
Run the installation locally with default settings overriding the value of specific configuration items.
Instance name will be defined as 'v2017'; TCP port will be changed to 1337 after installation.
Specifies the SQL Server version to install using the year-based identifier.
Valid values are 2008, 2008R2, 2012, 2014, 2016, 2017, 2019, and 2022.
This parameter determines which setup.exe file to locate in the installation media and configures version-specific features like tempdb file optimization (SQL 2016+).
| Alias | |
| Required | True |
| Pipeline | false |
| Default Value | |
| Accepted Values | 2008,2008R2,2012,2014,2016,2017,2019,2022 |
The target computer and, optionally, a new instance name and a port number.
Use one of the following generic formats:
Server1
Server2\Instance1
Server1\Alpha:1533, Server2\Omega:1566
"ServerName\NewInstanceName,1534"
You can also define instance name and port using -InstanceName and -Port parameters.
| Alias | ComputerName |
| Required | False |
| Pipeline | false |
| Default Value | $env:COMPUTERNAME |
Specifies the name for the new SQL Server instance, overriding any instance name in the SqlInstance parameter.
Use 'MSSQLSERVER' for the default instance or a custom name for named instances.
Named instances enable multiple SQL Server installations on the same server and affect service names, registry keys, and connection strings.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the password for the sa account when AuthenticationMode is set to Mixed.
If not provided with Mixed mode, a random 128-character password is automatically generated and returned in the output.
Only required when you want to set a specific sa password instead of using the auto-generated one.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Windows Credential with permission to log on to the remote server.
Must be specified for any remote connection if SQL Server installation media is located on a network folder.
Authentication will default to CredSSP if -Credential is used.
For CredSSP see also additional information in DESCRIPTION.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the PowerShell remoting authentication protocol for connecting to remote servers during installation.
Defaults to CredSSP when -Credential is provided to handle network share access and avoid double-hop authentication issues.
Use 'Kerberos' in domain environments where CredSSP is restricted, or 'Basic' for workgroup scenarios.
When installing from network shares, CredSSP is typically required to pass credentials through to the file server.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | @('Credssp', 'Default')[$null -eq $Credential] |
| Accepted Values | Default,Basic,Negotiate,NegotiateWithImplicitCredential,Credssp,Digest,Kerberos |
Path to an existing SQL Server Configuration.ini file to use for the installation.
Use this when you have a pre-configured setup file from a previous installation or when you need specific settings not covered by the function parameters.
The function will read and apply all settings from this file, overriding any conflicting parameters.
| Alias | FilePath |
| Required | False |
| Pipeline | true (ByValue) |
| Default Value |
A hashtable containing SQL Server setup configuration parameters that override function defaults.
Use this for advanced scenarios like setting custom startup types, enabling specific features, or configuring failover cluster instances.
Each key-value pair becomes a parameter in the Configuration.ini file, allowing full control over the installation process.
When ACTION is specified, only minimal defaults are set, requiring you to provide all necessary configuration items for that specific installation type.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the directory containing extracted SQL Server installation media, which will be scanned recursively for the appropriate setup.exe.
Can be a local path or network share accessible from target servers during remote installations.
The path must contain the extracted ISO contents or downloaded installer files, not the ISO file itself.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | (Get-DbatoolsConfigValue -Name 'Path.SQLServerSetup') |
Specifies which SQL Server components to install, either as individual features or using predefined templates.
'Default' installs Engine, Replication, FullText, and Tools for typical database server setups.
'All' installs every available feature for the specified version.
Choose specific features like 'Engine', 'AnalysisServices', 'ReportingServices', or 'IntegrationServices' for targeted installations based on your requirements.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | Default |
| Accepted Values | Default,All,Engine,Tools,Replication,FullText,DataQuality,PolyBase,MachineLearning,AnalysisServices,ReportingServices,ReportingForSharepoint,SharepointAddin,IntegrationServices,MasterDataServices,PythonPackages,RPackages,BackwardsCompatibility,Connectivity,ReplayController,ReplayClient,SDK,BIDS,SSMS |
Specifies the SQL Server authentication mode: Windows (Windows Authentication only) or Mixed (Windows and SQL Authentication).
Windows mode is more secure and recommended for domain environments, while Mixed mode is required for applications that need SQL logins.
When using Mixed mode, ensure you provide a strong SaCredential or allow the function to generate a secure random password.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | Windows |
| Accepted Values | Windows,Mixed |
Specifies the root directory where SQL Server instance files will be installed, including program files, system databases, and logs.
Defaults to the standard program files location unless you need to install on a different drive for capacity or performance reasons.
This path becomes the base for all instance-specific directories unless individual paths are specified.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the default directory for user database data files (.mdf and .ndf).
Used as the default location when creating new databases if no explicit path is provided in CREATE DATABASE statements.
Consider placing this on high-performance storage separate from logs for optimal I/O performance.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the default directory for user database transaction log files (.ldf).
Used as the default location for transaction logs when creating new databases.
Best practice is to place logs on separate storage from data files to optimize write performance and enable better backup strategies.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the directory for tempdb database files, which handle temporary objects and internal SQL Server operations.
Consider placing tempdb on fast storage (SSD) separate from user databases since it's heavily used for sorts, joins, and temporary tables.
For SQL 2016+, the function automatically configures multiple tempdb data files based on CPU core count.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the default directory for database backup files when no explicit path is provided in BACKUP commands.
This location should have sufficient space for your backup retention strategy and be accessible to your backup software.
Consider network accessibility if you plan to backup to shared storage or use backup software that requires UNC paths.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the directory containing SQL Server updates (service packs, cumulative updates) to apply during installation.
Enables slipstream installation to avoid separate patching steps after the base installation completes.
The path should contain the update executable files compatible with the SQL Server version being installed.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies one or more Windows accounts to grant sysadmin privileges on the new SQL Server instance.
Defaults to the current user or the account specified in the Credential parameter.
Use domain\username format for domain accounts or computername\username for local accounts.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the TCP port number for SQL Server after installation, overriding the default port 1433.
The function configures the port post-installation since SQL Server setup doesn't directly support custom ports.
Use non-standard ports for security through obscurity or when running multiple instances that need distinct ports.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | 0 |
Specifies the maximum number of concurrent SQL Server installations when targeting multiple servers.
Controls resource usage and network bandwidth by limiting parallel operations.
Consider your network capacity, installation media server performance, and available system resources when adjusting from the default of 50.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | 50 |
Specifies the product license key (PID) to install a licensed edition of SQL Server instead of Evaluation edition.
Required only when the installation media doesn't include an embedded license key.
Without a valid ProductID, the installation defaults to a time-limited Evaluation edition that expires after 180 days.
| Alias | PID |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the collation for Analysis Services, determining sort order and character comparison rules for SSAS databases.
Defaults to Latin1_General_CI_AS if not specified.
Choose a collation that matches your data locale and case sensitivity requirements for dimensional and tabular models.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the server-level collation for the Database Engine, affecting sort order, case sensitivity, and accent sensitivity for all databases.
Defaults to the Windows locale setting if not specified.
Choose carefully as changing server collation after installation requires rebuilding system databases and can affect application compatibility.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the Windows account to run the SQL Server Database Engine service.
Use domain service accounts for network access, Managed Service Accounts (MSAs) for automated password management, or local accounts for standalone servers.
The account needs specific Windows privileges like 'Log on as a service' and permissions to the installation directories.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the Windows account to run the SQL Server Agent service, which manages scheduled jobs, alerts, and replication.
Typically uses the same account as the Database Engine for simplicity, but can be separate for security isolation.
Requires permissions to execute job steps, access network resources for backup jobs, and interact with other SQL Server instances for replication.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the Windows account to run the Analysis Services (SSAS) service for OLAP cubes and tabular models.
The account needs permissions to data sources, file system access for processing, and network connectivity for distributed queries.
Consider using a dedicated service account when SSAS requires different security contexts than the Database Engine.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the Windows account to run the Integration Services (SSIS) service for ETL package execution and management.
The account needs permissions to source and destination systems, file shares for package storage, and SQL Server databases for logging and configuration.
Use a service account with broad permissions since SSIS packages often access multiple systems and data sources.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the Windows account to run the Reporting Services (SSRS) service for report generation and delivery.
The account needs permissions to the report server database, data sources used in reports, and network resources for email delivery.
Consider network connectivity requirements when reports access remote data sources or when using email subscriptions.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the Windows account to run the Full-Text Filter Daemon service for indexing and searching text content in databases.
The account needs permissions to database files and temporary directories used during full-text indexing operations.
Usually runs under a low-privilege account since it only processes text extraction and indexing without requiring broad system access.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies the Windows account to run the PolyBase Engine service for distributed queries against Hadoop, Azure Blob Storage, and other external data sources.
The account needs network access to external systems and permissions to temporary directories for data processing.
Required when installing PolyBase features for big data integration and external table functionality.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Specifies a path to save the generated Configuration.ini file for future reference or reuse.
Without this parameter, the configuration file is created in a temporary location and not preserved after installation.
Useful for documenting installation settings, troubleshooting, or replicating installations across multiple servers.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value |
Grants the SQL Server service account 'Perform volume maintenance tasks' privilege to enable instant file initialization.
Allows SQL Server to skip zero-initialization of data files, significantly reducing the time for database creation, restore operations, and auto-growth events.
Only affects data files; transaction log files are always zero-initialized for transaction integrity.
| Alias | InstantFileInitialization,IFI |
| Required | False |
| Pipeline | false |
| Default Value | False |
Automatically restarts target computers when required by Windows updates, pending file operations, or installation prerequisites.
Use this during maintenance windows when automatic restarts are acceptable.
Without this parameter, installations will fail if pending restarts are detected, requiring manual intervention.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Skips the check for pending file rename operations when validating reboot requirements.
Use this when you know pending renames won't affect the SQL Server installation or when working with systems that show false positives for pending renames.
Generally safer to allow the default validation unless you have specific reasons to bypass this safety check.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | (Get-DbatoolsConfigValue -Name 'OS.PendingRename' -Fallback $false) |
By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.
| Alias | |
| Required | False |
| Pipeline | false |
| Default Value | False |
Shows what would happen if the command were to run. No actions are actually performed.
| Alias | wi |
| Required | False |
| Pipeline | false |
| Default Value |
Prompts you for confirmation before executing any changing operations within the command.
| Alias | cf |
| Required | False |
| Pipeline | false |
| Default Value |