SQL Server in Docker: Run MSSQL on Linux, Windows & Intel Macs

The official SQL Server Docker image

Microsoft distributes SQL Server for Docker from the Microsoft Container Registry as mcr.microsoft.com/mssql/server. On Docker Hub the same image appears as microsoft/mssql-server ("Microsoft SQL Server - Ubuntu based images"), which is the page people find when they search for SQL Server on Docker Hub. The images run SQL Server on Linux; SQL Server in Windows containers is not supported for production, and Microsoft's container articles do not cover it.

Containers are a convenient way to get an MSSQL instance on a laptop or in CI: nothing is installed on the host apart from Docker, and removing the container removes SQL Server. The image needs at least 2 GB of RAM and 2 GB of disk, so give Docker Desktop enough memory on Windows and macOS.

Choosing the edition with MSSQL_PID

The same image runs every edition; the MSSQL_PID environment variable selects it, and the default is Developer. For SQL Server 2025 the free values are EnterpriseDeveloper, StandardDeveloper, Express and Evaluation (180 days). Standard and EnterpriseCore are paid: by passing ACCEPT_EULA=Y with a paid edition you state that you hold a licence for it. Developer editions are for development and test only; Express may run in production (see the related SQL Server Express guide).

Run SQL Server with docker run

Microsoft's quickstart pulls the image and starts a container named sql1. Replace <your-password> with a strong password: by default it must be at least eight characters and include three of uppercase letters, lowercase letters, digits and symbols. If the password does not meet the policy, the container cannot set up SQL Server and stops. SA_PASSWORD is deprecated; use MSSQL_SA_PASSWORD.

On Windows, Microsoft notes that PowerShell needs double quotes around the -e values rather than single quotes, otherwise the container may exit straight after starting.

docker pull mcr.microsoft.com/mssql/server:2025-latest
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<your-password>" \
   -p 1433:1433 --name sql1 --hostname sql1 \
   -d \
   mcr.microsoft.com/mssql/server:2025-latest

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<your-password>" -e "MSSQL_PID=Express" -p 1433:1433 --name sql1 --hostname sql1 -d mcr.microsoft.com/mssql/server:2025-latest

docker ps -a
docker exec -t sql1 cat /var/opt/mssql/log/errorlog | grep connection

MSSQL in Docker on Mac (Apple silicon), Windows and Linux

Linux. Microsoft lists Docker Engine 1.8 or later on any supported Linux distribution and the overlay2 storage driver. Run the commands with sudo, or add your user to the docker group.

Windows. Use Docker Desktop with Linux containers. Docker Desktop is free for personal use, education and small businesses, and needs a paid subscription in larger organisations. Microsoft also supports SQL Server on Windows Subsystem for Linux for development only, as a non-container alternative.

Mac with Apple silicon (M-series). Microsoft states that SQL Server container images are supported only on Linux hosts with Intel and AMD x86-64 CPUs, and that emulation or translation environments such as Rosetta 2 are not supported. A container may still start under emulation, but you are then outside Microsoft's support policy and should not rely on it for anything important. Microsoft's Docker Hub page also lists a known issue that mounting a volume does not work on Docker for macOS. Supported alternatives for an Apple silicon Mac are a SQL Server instance on an x86-64 machine or virtual machine you connect to, or a cloud database such as the Azure SQL Database free offer. On Intel Macs the image is supported as on any x86-64 host.

Persist SQL Server data with Docker volumes

Data survives docker stop and docker start, but docker rm deletes everything in the container, including SQL Server and your databases. Microsoft documents two fixes: mount a host directory, or use a named volume. Docker describes volumes as the preferred way to persist container data, managed by Docker and independent of the host's directory layout. A named volume also persists after the container is removed, and a new container started with the same volume uses the same databases, which is how Microsoft documents upgrading to a newer image.

Two consequences to know: when you start a container on an existing volume, SQL Server ignores MSSQL_SA_PASSWORD and keeps the sa password stored in that data. And if you take backups with BACKUP DATABASE, copy the files out of the container (docker cp), or they are lost when the container is removed.

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<your-password>" \
   -p 1433:1433 --name sql1 \
   -v sqlvolume:/var/opt/mssql \
   -d mcr.microsoft.com/mssql/server:2025-latest
docker volume ls

SQL Server with Docker Compose (compose.yaml)

Compose keeps the same settings in a file so the whole team starts an identical instance with docker compose up -d. The file below uses only the image name, environment variables, port mapping and volume path from Microsoft's documentation, in the current Compose format without the obsolete version: key. Keep the real password out of version control: the file reads it from a MSSQL_SA_PASSWORD variable in your environment.

services:
  mssql:
    image: mcr.microsoft.com/mssql/server:2025-latest
    container_name: sql1
    hostname: sql1
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}"
      MSSQL_PID: "Developer"
    ports:
      - "1433:1433"
    volumes:
      - sqlvolume:/var/opt/mssql

volumes:
  sqlvolume:

Connect with sqlcmd, VS Code, SSMS or DBeaver

sqlcmd inside the container. Recent images include the mssql-tools18 package, so sqlcmd is at /opt/mssql-tools18/bin/sqlcmd. These tools are secure by default and expect an encrypted connection; Microsoft says to add -No (encryption optional) if the connection does not succeed.

From the host. Any SQL Server client connects to the host address and the mapped port: localhost,1433 (use a comma before the port), SQL Server Authentication, user sa. In SSMS tick Trust Server Certificate for the container's self-signed certificate. In DBeaver or other JDBC tools, use host localhost, port 1433 and the same login.

VS Code. The MSSQL extension can create a local SQL Server container for you: it checks that Docker is running, pulls the image, creates the container and a connection profile. Microsoft lists its limits: Linux containers only, no Podman, and no backup and restore, script initialisation or Docker Compose in the wizard.

go-sqlcmd. The newer standalone sqlcmd can create a container in one command, sqlcmd create mssql --accept-eula. Microsoft notes it always creates a Developer edition container because it does not support MSSQL_PID.

docker exec -it sql1 /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -No
sqlcmd -S localhost,1433 -U sa -No

CREATE DATABASE TestDB;
SELECT name FROM sys.databases;
GO

Troubleshooting SQL Server containers

• "bind: address already in use". Port 1433 is taken, often by a SQL Server installed on the host or a second container. Map another host port, for example -p 1400:1433, and connect to localhost,1400.
• The container exits immediately. Run docker logs sql1. The usual causes are a password that fails the policy, too little memory for Docker, or single quotes in Windows PowerShell.
• "permission denied" on the Docker socket (Linux). Add your user to the docker group with usermod -aG docker $USER, then sign out and back in.
• Login failed for user sa (error 18456). If you reused a volume, the old sa password applies, not the one in MSSQL_SA_PASSWORD.
• Connection refused (error 10061). Check that docker ps -a shows the container as Up and that you use the mapped port.
• Logs. SQL Server setup and error logs are in /var/opt/mssql/log inside the container.

Frequently asked questions

Sources

• Microsoft Learn: Run SQL Server Linux container images with Docker
• Microsoft Learn: Deploy and connect to SQL Server Linux containers
• Microsoft Learn: Configure and customize SQL Server Linux containers
• Microsoft Learn: Configure SQL Server settings with environment variables on Linux
• Microsoft Learn: Troubleshoot SQL Server Docker containers
• Docker Hub: microsoft/mssql-server (Microsoft)
• Microsoft Learn: sqlcmd utility
• Microsoft Learn: Local SQL Server container in the MSSQL extension for VS Code
• Microsoft Learn: Install SQL Server on Ubuntu (WSL note)
• Docker Docs: Volumes
• Docker Docs: Compose file reference, services
• Docker Docs: Install Docker Desktop on Mac

Checked 8 October 2026.

How we research guides: our editorial method. We link only to official downloads and never host installers.