Quickstart: Install SQL Server and create a database on Windows Subsystem for Linux (WSL 2)

Article
12/23/2024

Applies to: SQL Server - Linux

Windows Subsystem for Linux (WSL) is a feature in Windows that allows you to run a Linux environment directly on your Windows machine, without the need for a virtual machine or dual booting. WSL provides a seamless and productive experience for developers who want to use both Windows and Linux simultaneously. For more information, see What is the Windows Subsystem for Linux?

SQL Server on WSL is for development use only

SQL Server on WSL 2 is intended for development purposes only, and is not supported for production workloads. We recommend running SQL Server in WSL environments on one of the Supported platforms as documented, for the version of SQL Server you intend to run.

For any support related issues, you can obtain support from Microsoft.

Get started with SQL Server on WSL 2

There are two ways to get started with SQL Server on WSL 2:

Install SQL Server as a systemd service, which can be managed using systemctl commands. Make sure that you enable systemd on WSL. For more information, see How to enable systemd.
Deploy SQL Server containers in WSL. For this option, you need to install a Linux container engine in WSL, such as Docker or Podman, and then deploy SQL Server containers.

Prerequisites

Install WSL 2. Ensure you're running Windows 10 version 2004 or a later version (Build 19041 and higher), or Windows 11. To install WSL, open a PowerShell or Windows command prompt in administrator mode, and run the following command:

wsl --install

For detailed instructions, see How to install Linux on Windows with WSL. For information on setting up the WSL environment for development, see Set up a WSL development environment.

Install SQL Server in WSL

This section describes the steps to set up a Linux distribution in WSL, and how to install SQL Server in that Linux distribution.

Choose Linux distribution

You can list all the valid distributions that can be installed in WSL using the following command:

wsl -l -o

The output looks similar to the following example.

The following is a list of valid distributions that can be installed.
Install using 'wsl.exe --install <Distro>'.

NAME                            FRIENDLY NAME
Ubuntu                          Ubuntu
Debian                          Debian GNU/Linux
kali-linux                      Kali Linux Rolling
Ubuntu-18.04                    Ubuntu 18.04 LTS
Ubuntu-20.04                    Ubuntu 20.04 LTS
Ubuntu-22.04                    Ubuntu 22.04 LTS
Ubuntu-24.04                    Ubuntu 24.04 LTS
OracleLinux_7_9                 Oracle Linux 7.9
OracleLinux_8_7                 Oracle Linux 8.7
OracleLinux_9_1                 Oracle Linux 9.1
openSUSE-Leap-15.6              openSUSE Leap 15.6
SUSE-Linux-Enterprise-15-SP5    SUSE Linux Enterprise 15 SP5
SUSE-Linux-Enterprise-15-SP6    SUSE Linux Enterprise 15 SP6
openSUSE-Tumbleweed             openSUSE Tumbleweed

For this quickstart, install Ubuntu 22.04, and then install SQL Server 2022 into that distribution.

To install Ubuntu 22.04, run the following command. Make a note of the UNIX user account and password. In this example, use wsluser as the username.

wsl --install -d Ubuntu-22.04

You should see output similar to the following example. At the end, it should show that you're logged into the Ubuntu 22.04 bash shell.

Installing: Ubuntu 22.04 LTS
Ubuntu 22.04 LTS has been installed.
Launching Ubuntu 22.04 LTS...
Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: wsluser
New password:
Retype new password:
passwd: password updated successfully
Installation successful!
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

Welcome to Ubuntu 22.04.5 LTS (GNU/Linux 5.15.167.4-microsoft-standard-WSL2 x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/pro

 System information as of Tue Dec  3 00:32:14 IST 2024

  System load:  0.33                Processes:             32
  Usage of /:   0.1% of 1006.85GB   Users logged in:       0
  Memory usage: 2%                  IPv4 address for eth0: 10.18.123.249
  Swap usage:   0%

This message is shown once a day. To disable it please create the
/home/wsluser/.hushlogin file.

Install SQL Server

Once you're logged into the Ubuntu 22.04 bash shell, you can follow the steps outlined in Quickstart: Install SQL Server and create a database on Ubuntu to install SQL Server 2022.

You should install the SQL Server command-line tools as well.

Get IP address

To identify the IP address to connect to using SQL Server Management Studio (SSMS), run the ifconfig command as follows:

ifconfig

You should see output similar to the following example.

eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet 10.19.50.241  netmask 255.255.240.0  broadcast 10.19.63.255
        inet6 fe80::215:5dff:fe76:c05d  prefixlen 64  scopeid 0x20<link>
        ether 00:15:5d:76:c0:5d  txqueuelen 1000  (Ethernet)
        RX packets 2146  bytes 1452448 (1.4 MB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 1905  bytes 345288 (345.2 KB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

lo: flags=73<UP,LOOPBACK,RUNNING>  mtu 65536
        inet 127.0.0.1  netmask 255.0.0.0
        inet6 ::1  prefixlen 128  scopeid 0x10<host>
        loop  txqueuelen 1000  (Local Loopback)
        RX packets 2039  bytes 4144340 (4.1 MB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 2039  bytes 4144340 (4.1 MB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

Deploy SQL Server containers in WSL

To deploy containers in WSL, you first need to install a Linux container engine, such as Docker. For more information, see Get started with Docker remote containers on WSL. Once you have the Docker engine installed, deploy the SQL Server container image as follows.

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<password>" \
-e "MSSQL_PID=Developer" -e "MSSQL_AGENT_ENABLED=true" \
-p 14333:1433 --name sqlcontainerwsl --hostname sqlcontainerwsl \
-d mcr.microsoft.com/mssql/server:2022-latest

Note

Your password should follow the SQL Server default password policy. By default, the password must be at least eight characters long and contain characters from three of the following four sets: uppercase letters, lowercase letters, base-10 digits, and symbols. Passwords can be up to 128 characters long. Use passwords that are as long and complex as possible.

Add persistent storage with WSL for SQL Server containers

You can create data volumes as described in Mount a host directory as data volume.

For example, run the following command to set up a volume called sql_volume located at /var/opt/mssql/.

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<password>" \
-e "MSSQL_PID=Developer" -e "MSSQL_AGENT_ENABLED=true" \
-p 14333:1433 --name sqlcontainerwsl --hostname sqlcontainerwsl \
-v sql_volume:/var/opt/mssql/ \
-d mcr.microsoft.com/mssql/server:2022-latest

Even if you run the wsl --terminate command, the data isn't lost. When you start up WSL again and run the docker run command to deploy using the sql_volume volume, it still has all the data intact.

If you want to delete the persisted volume, make sure that the container using the volume is stopped and removed, and run the following command.

docker volume rm sql_volume

Remarks

You should be able to configure most of the features supported for SQL Server on Linux for development purposes, except the business continuity features that are dependent on clustering stacks. These features, such as Pacemaker or HPE Serviceguard, aren't supported on WSL.

For a full list of unsupported features for SQL Server on Linux, see Editions and supported features of SQL Server 2022 on Linux.

Connect locally

The following steps use sqlcmd to locally connect to your new SQL Server instance.

Caution

Run sqlcmd with parameters for your SQL Server name (-S), the user name (-U), and the password (-P). In this tutorial, you connect locally, so the server name is localhost. The user name is sa and the password is the one you provided for the sa account during setup.
```
sqlcmd -S localhost -U sa -P '<password>'
```
Note

Newer versions of sqlcmd are secure by default. For more information about connection encryption, see sqlcmd utility for Windows, and Connecting with sqlcmd for Linux and macOS. If the connection doesn't succeed, you can add the -No option to sqlcmd to specify that encryption is optional, not mandatory.

You can omit the password on the command line to be prompted to enter it.

If you later decide to connect remotely, specify the machine name or IP address for the -S parameter, and make sure port 1433 is open on your firewall.
If successful, you should get to a sqlcmd command prompt: 1>.
If you get a connection failure, first attempt to diagnose the problem from the error message. Then review the connection troubleshooting recommendations.

Create and query data

The following sections walk you through using sqlcmd to create a new database, add data, and run a simple query.

For more information about writing Transact-SQL statements and queries, see Tutorial: Write Transact-SQL statements.

Create a new database

The following steps create a new database named TestDB.

From the sqlcmd command prompt, paste the following Transact-SQL command to create a test database:
```
CREATE DATABASE TestDB;
```
On the next line, write a query to return the name of all of the databases on your server:
```
SELECT Name
FROM sys.databases;
```
The previous two commands aren't executed immediately. You must type GO on a new line to execute the previous commands:
```
GO
```

Insert data

Next create a new table, dbo.Inventory, and insert two new rows.

From the sqlcmd command prompt, switch context to the new TestDB database:
```
USE TestDB;
```

Create new table named dbo.Inventory:

CREATE TABLE dbo.Inventory
(
    id INT,
    name NVARCHAR (50),
    quantity INT,
    PRIMARY KEY (id)
);

Insert data into the new table:

INSERT INTO dbo.Inventory
VALUES (1, 'banana', 150);

INSERT INTO dbo.Inventory
VALUES (2, 'orange', 154);

Type GO to execute the previous commands:
```
GO
```

Select data

Now, run a query to return data from the dbo.Inventory table.

From the sqlcmd command prompt, enter a query that returns rows from the dbo.Inventory table where the quantity is greater than 152:
```
SELECT *
FROM dbo.Inventory
WHERE quantity > 152;
```
Execute the command:
```
GO
```

Exit the sqlcmd command prompt

To end your sqlcmd session, type QUIT:

QUIT

Performance best practices

After installing SQL Server on Linux, review the best practices for configuring Linux and SQL Server to improve performance for production scenarios. For more information, see Performance best practices and configuration guidelines for SQL Server on Linux.

Cross-platform data tools

In addition to sqlcmd, you can use the following cross-platform tools to manage SQL Server:

Tool	Description
Azure Data Studio	A cross-platform GUI database management utility.
Visual Studio Code	A cross-platform GUI code editor that run Transact-SQL statements with the mssql extension.
PowerShell Core	A cross-platform automation and configuration tool based on cmdlets.
mssql-cli	A cross-platform command-line interface for running Transact-SQL commands.

Connect from Windows

SQL Server tools on Windows connect to SQL Server instances on Linux in the same way they would connect to any remote SQL Server instance.

If you have a Windows machine that can connect to your Linux machine, try the same steps in this topic from a Windows command-prompt running sqlcmd. You must use the target Linux machine name or IP address rather than localhost, and make sure that TCP port 1433 is open on the SQL Server machine. If you have any problems connecting from Windows, see connection troubleshooting recommendations.

For other tools that run on Windows but connect to SQL Server on Linux, see:

Other deployment scenarios

For other installation scenarios, see the following resources:

Upgrade: Learn how to upgrade an existing installation of SQL Server on Linux
Uninstall: Uninstall SQL Server on Linux
Unattended install: Learn how to script the installation without prompts
Offline install: Learn how to manually download the packages for offline installation

For answers to frequently asked questions, see the SQL Server on Linux FAQ.

Migrate a SQL Server database from Windows to Linux using backup and restore

Contribute to SQL documentation

Did you know that you can edit SQL content yourself? If you do so, not only do you help improve our documentation, but you also get credited as a contributor to the page.

For more information, see How to contribute to SQL Server documentation

Share via

Quickstart: Install SQL Server and create a database on Windows Subsystem for Linux (WSL 2)

SQL Server on WSL is for development use only

Get started with SQL Server on WSL 2

Prerequisites

Install SQL Server in WSL

Choose Linux distribution

Install SQL Server

Get IP address

Deploy SQL Server containers in WSL

Add persistent storage with WSL for SQL Server containers

Remarks

Connect locally

Create and query data

Create a new database

Insert data

Select data

Exit the sqlcmd command prompt

Performance best practices

Cross-platform data tools

Connect from Windows

Other deployment scenarios

Contribute to SQL documentation

Feedback

Additional resources

Share via

Quickstart: Install SQL Server and create a database on Windows Subsystem for Linux (WSL 2)

SQL Server on WSL is for development use only

Get started with SQL Server on WSL 2

Prerequisites

Install SQL Server in WSL

Choose Linux distribution

Install SQL Server

Get IP address

Deploy SQL Server containers in WSL

Add persistent storage with WSL for SQL Server containers

Remarks

Connect locally

Create and query data

Create a new database

Insert data

Select data

Exit the sqlcmd command prompt

Performance best practices

Cross-platform data tools

Connect from Windows

Other deployment scenarios

Related content

Contribute to SQL documentation

Feedback

Additional resources