(opens in a new tab)

How to Run SQL Server on Mac with Docker

September 28, 2026 by Chat2DB Team

There is no native SQL Server for macOS. Microsoft ships the database engine for Windows and Linux only, and SQL Server Management Studio (SSMS) runs only on Windows. On a Mac, the practical way to get a local SQL Server for development is to run the official Linux container image in Docker, then connect to it with a command-line tool or a Mac-native GUI client.

This guide walks through that setup step by step, covers the differences between Intel and Apple Silicon Macs, explains what happened to Azure SQL Edge (the image many older tutorials recommend for M1 and M2 machines), and shows how to connect with sqlcmd and a graphical client.

What You Need

• A Mac with Docker Desktop installed (or another Docker-compatible runtime).
• At least 2 GB of RAM available to the container, which is Microsoft's stated minimum for the SQL Server container. Give Docker's VM more than that if you also run other containers.
• A few GB of free disk space for the image and your databases.
• A terminal. Homebrew is optional but makes installing sqlcmd easy.

Check that Docker is running before you start:

docker version --format '{{.Server.Os}}/{{.Server.Arch}} {{.Server.Version}}'
uname -m

uname -m prints x86_64 on an Intel Mac and arm64 on Apple Silicon (M1, M2, M3, M4 and later). That one answer decides which section below applies to you.

SQL Server Versions and Image Tags

Microsoft publishes the images at mcr.microsoft.com/mssql/server. The rolling tags for current major versions are:

Match the version your production server runs, so features and query behavior are the same in development. If you do not have a constraint, 2022-latest and 2025-latest are both reasonable choices. For a reproducible setup, pin a specific cumulative update tag from the Microsoft Artifact Registry tag list instead of a latest tag.

All of these images are built for linux/amd64 (x86-64). There is no ARM64 build of SQL Server for Linux.

Step 1: Start SQL Server on an Intel Mac

On an Intel Mac, the image runs natively inside Docker's Linux VM. Pull and start it:

docker pull mcr.microsoft.com/mssql/server:2022-latest
 
docker run -d --name sql1 --hostname sql1 \
  -e "ACCEPT_EULA=Y" \
  -e "MSSQL_SA_PASSWORD=Str0ng!Passw0rd" \
  -p 1433:1433 \
  -v mssql-data:/var/opt/mssql \
  mcr.microsoft.com/mssql/server:2022-latest

What each option does:

• ACCEPT_EULA=Y confirms the license agreement. The container will not start without it.
• MSSQL_SA_PASSWORD sets the password of the sa login. The older SA_PASSWORD variable is deprecated.
• -p 1433:1433 publishes the default SQL Server port to your Mac, so clients connect to localhost,1433.
• -v mssql-data:/var/opt/mssql stores the data files in a named Docker volume. Without it, removing the container deletes your databases.

The Password Must Meet the Policy

The sa password has to satisfy SQL Server's default policy: at least eight characters, containing characters from three of these four groups: uppercase letters, lowercase letters, digits and symbols. If it does not, the container starts, fails to set up SQL Server, and exits. docker ps then shows nothing, and the reason is in the logs:

docker ps -a --filter name=sql1
docker logs sql1 | tail -20

Look for a line about the password not meeting the requirements. Remove the container, pick a stronger password, and run it again:

docker rm sql1
docker volume rm mssql-data   # only if the volume was created by the failed attempt

In shells, put the password in single or double quotes and avoid $ and ! characters that the shell may try to expand, or escape them.

Wait for the Server to Accept Connections

The container is running a few seconds before SQL Server finishes recovery. Wait for this line in the log before connecting:

docker logs -f sql1 | grep -m1 "SQL Server is now ready for client connections"

Step 2: Apple Silicon Options

Because SQL Server for Linux is x86-64 only, an M-series Mac has to emulate x86-64 to run it. Docker Desktop can do this with QEMU or with Apple's Rosetta 2 translation. SQL Server is widely reported to fail or crash under QEMU and to work much better under Rosetta, so enable Rosetta first.

Enable Rosetta in Docker Desktop

1. Open Docker Desktop and go to Settings, then General.
2. Make sure Apple Virtualization framework is selected as the Virtual Machine Manager. The Rosetta option is only available with it.
3. Turn on Use Rosetta for x86_64/amd64 emulation on Apple Silicon.
4. Click Apply and restart.

If Rosetta 2 is not yet installed on the Mac, macOS can install it from the terminal:

softwareupdate --install-rosetta --agree-to-license

Run the amd64 Image

The command is the same as on Intel, with --platform linux/amd64 added so Docker does not look for an ARM64 image:

docker run -d --name sql1 --hostname sql1 \
  --platform linux/amd64 \
  -e "ACCEPT_EULA=Y" \
  -e "MSSQL_SA_PASSWORD=Str0ng!Passw0rd" \
  -p 1433:1433 \
  -v mssql-data:/var/opt/mssql \
  mcr.microsoft.com/mssql/server:2022-latest

Docker prints a warning that the image platform does not match the host platform. That is expected.

What Microsoft Supports

Be clear about the support status before you rely on this. Microsoft's quickstart states that SQL Server container images are supported only on Linux hosts running on Intel and AMD x86-64 CPUs, and that emulation or translation environments, naming Rosetta 2 as an example, "aren't tested or supported". In practice many developers run SQL Server this way on M-series Macs for local development and testing, but:

• Do not use it to measure performance. Translated code runs differently from native x86-64.
• If you hit a crash that you cannot reproduce on an x86-64 machine, emulation is the first suspect.
• Microsoft directs emulator-related reports to the microsoft/mssql-docker GitHub repository rather than normal support.

Apple has also announced that general-purpose Rosetta support will be reduced in a future macOS release. Check the current Docker Desktop and Apple documentation before building a long-term workflow on it.

What Happened to Azure SQL Edge

Many tutorials written for M1 Macs tell you to run mcr.microsoft.com/azure-sql-edge instead, because at the time it was the one SQL Server-family image with an ARM64 build. That advice is out of date for two reasons. Microsoft had already dropped ARM64 support from Azure SQL Edge (its archived documentation now states that it "no longer supports the ARM64 platform" and requires an x86 64-bit processor), and Microsoft retired the product entirely on September 30, 2025. After that date it no longer receives security updates, bug fixes or technical support, and its documentation has moved to the "previous versions" archive.

Even before retirement, it was not a drop-in replacement for SQL Server: it was a special edition aimed at IoT and edge devices, and Microsoft's feature list for it excludes many things ordinary SQL Server has, including CLR assemblies, CLR-dependent functions such as FORMAT, PARSE and TRY_PARSE, the spatial and hierarchyid data types, full-text search, linked servers and Service Broker. Code tested against it could fail in production, or the other way round.

For a new setup in 2026, do not start with Azure SQL Edge. Use the regular SQL Server image with Rosetta emulation on Apple Silicon, or one of the alternatives in the next section. If you already have an Edge container, plan to move its databases to a regular SQL Server container by backing them up and restoring them, as shown in Step 6.

Other Apple Silicon Alternatives

If emulation is not acceptable for your use case:

• A remote x86-64 machine. A small Linux VM in the cloud or on your network running the same container gives you a supported setup. You connect to it from your Mac the same way.
• Azure SQL Database. For application development that does not depend on instance-level features, a low-tier or serverless Azure SQL Database is a supported alternative with nothing to run locally.
• A Windows on ARM virtual machine. This is useful for running Windows-only tools like SSMS, but check Microsoft's current requirements before trying to install the database engine itself there.

Step 3: Install sqlcmd on the Mac

Microsoft maintains two variants of sqlcmd. The Go-based one (often called go-sqlcmd) is a standalone binary that runs natively on macOS, including Apple Silicon, and is the easiest to install:

brew install sqlcmd
sqlcmd --version

Connect to the container:

sqlcmd -S localhost,1433 -U sa -P 'Str0ng!Passw0rd' -C -Q "SELECT @@VERSION"

-C tells sqlcmd to trust the server certificate. A fresh SQL Server container uses a self-signed certificate, and clients that validate certificates will otherwise refuse the connection. That is acceptable for a local development container; for a shared server, install a proper certificate instead.

For an interactive session, leave out -Q. Type statements and run each batch with GO:

CREATE DATABASE devdb;
GO
USE devdb;
GO
CREATE TABLE dbo.customers (
  id    int IDENTITY PRIMARY KEY,
  email nvarchar(320) NOT NULL UNIQUE
);
INSERT INTO dbo.customers (email) VALUES (N'ada@example.com');
SELECT * FROM dbo.customers;
GO

Type EXIT to quit.

Use the sqlcmd Inside the Container

The image also contains the ODBC-based sqlcmd under /opt/mssql-tools18/bin (older images used /opt/mssql-tools/bin). It is handy if you do not want to install anything on the Mac:

docker exec -it sql1 /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'Str0ng!Passw0rd' -C

Let sqlcmd Create the Container

go-sqlcmd can also create and manage a SQL Server container for you, and store the connection in its own config:

sqlcmd create mssql --accept-eula --tag 2022-latest
sqlcmd query "SELECT name FROM sys.databases"
sqlcmd delete

sqlcmd create mssql get-tags lists the available tags. This uses the same container runtime underneath, so the Apple Silicon considerations above still apply.

Step 4: Connect From a GUI Client

SSMS does not run on macOS, and Azure Data Studio, which was Microsoft's cross-platform client, reached end of support on February 28, 2026 (see Azure Data Studio on Mac for what that means). On a Mac you have three kinds of options:

• A Mac-native multi-database client.
• Visual Studio Code with Microsoft's MSSQL extension, which Microsoft recommends as the successor to Azure Data Studio.
• SSMS inside a Windows virtual machine, for the administration features that exist nowhere else.

Whatever client you use, the connection settings for the container are the same:

If your client asks for a connection string, the ADO.NET form looks like this:

Server=localhost,1433;Database=devdb;User Id=sa;Password=Str0ng!Passw0rd;Encrypt=True;TrustServerCertificate=True;

Note the comma between host and port; SQL Server connection strings do not use a colon there. The SQL Server connection string builder (opens in a new tab) generates the equivalent string for ADO.NET, JDBC, ODBC and other drivers, and the SQL Server connection string guide explains each keyword.

Chat2DB (opens in a new tab) is a native Mac client, with Apple Silicon support, that connects to SQL Server as well as MySQL, PostgreSQL and other databases, so a container like the one above can sit next to your other local databases in a single app. For a side-by-side look at Mac clients that can replace SSMS for daily work, see SSMS for Mac alternatives (opens in a new tab).

Step 5: Create a Login for Your Application

Do not let your application connect as sa. Create a database, a login and a user with only the rights it needs:

CREATE DATABASE appdb;
GO
CREATE LOGIN app_user WITH PASSWORD = 'An0ther!Str0ngOne';
GO
USE appdb;
GO
CREATE USER app_user FOR LOGIN app_user;
ALTER ROLE db_datareader ADD MEMBER app_user;
ALTER ROLE db_datawriter ADD MEMBER app_user;
GO

It is also good practice to change the sa password after first start, because the value passed through MSSQL_SA_PASSWORD is visible in the container's environment (docker inspect sql1 shows it):

sqlcmd -S localhost,1433 -U sa -P 'Str0ng!Passw0rd' -C \
  -Q "ALTER LOGIN sa WITH PASSWORD = 'N3w!Str0ngerPass'"

Step 6: Keep, Back Up and Move Your Data

With the named volume from Step 1, your databases survive docker stop, docker rm and image upgrades:

docker stop sql1
docker rm sql1
docker run -d --name sql1 --hostname sql1 --platform linux/amd64 \
  -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=N3w!Str0ngerPass" \
  -p 1433:1433 -v mssql-data:/var/opt/mssql \
  mcr.microsoft.com/mssql/server:2022-latest

When you reuse a volume, the sa password stored in the volume wins; the environment variable only sets it on first initialization. Upgrading to a newer major version (for example 2022 to 2025) on the same volume upgrades the databases in place, and you cannot go back to the older version afterwards, so take a backup first.

To back up a database and copy the file to your Mac:

sqlcmd -S localhost,1433 -U sa -P 'N3w!Str0ngerPass' -C \
  -Q "BACKUP DATABASE appdb TO DISK = N'/var/opt/mssql/backup/appdb.bak' WITH INIT"
 
docker cp sql1:/var/opt/mssql/backup/appdb.bak ./appdb.bak

If the backup directory does not exist yet, create it first with docker exec -u root sql1 mkdir -p /var/opt/mssql/backup and give it to the mssql user with docker exec -u root sql1 chown mssql /var/opt/mssql/backup.

To restore a .bak from another server into the container, copy it in and look at its logical file names before restoring:

docker cp ./prod-copy.bak sql1:/var/opt/mssql/backup/prod-copy.bak

RESTORE FILELISTONLY FROM DISK = N'/var/opt/mssql/backup/prod-copy.bak';
 
RESTORE DATABASE prodcopy
FROM DISK = N'/var/opt/mssql/backup/prod-copy.bak'
WITH MOVE N'ProdDb'     TO N'/var/opt/mssql/data/prodcopy.mdf',
     MOVE N'ProdDb_log' TO N'/var/opt/mssql/data/prodcopy_log.ldf';

Replace ProdDb and ProdDb_log with the logical names from the FILELISTONLY output. The MOVE clauses are needed because a backup taken on Windows records paths like C:\Program Files\... that do not exist in the Linux container. The SQL Server backup and restore guide covers the options in more detail.

Step 7: A docker-compose File

For a project repository, a compose file documents the setup and starts it with one command:

services:
  mssql:
    image: mcr.microsoft.com/mssql/server:2022-latest
    platform: linux/amd64
    container_name: sql1
    hostname: sql1
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "Str0ng!Passw0rd"
      MSSQL_PID: "Developer"
    ports:
      - "1433:1433"
    volumes:
      - mssql-data:/var/opt/mssql
 
volumes:
  mssql-data:

MSSQL_PID selects the edition; Developer is the free, full-featured edition licensed for development and testing only, and it is what the image uses when you do not set the variable. Start it with docker compose up -d. The platform line is harmless on Intel Macs and required on Apple Silicon.

Troubleshooting

The container exits right after starting

Run docker logs sql1. The two usual causes are a password that does not meet the policy and too little memory assigned to Docker. Fix the cause, remove the container, and start it again.

"Login timeout expired" or "Connection refused"

SQL Server is still starting, the container is not running, or the port is not published. Check docker ps for 0.0.0.0:1433->1433/tcp, and wait for the "ready for client connections" log line. If another SQL Server or container already uses port 1433, publish a different one with -p 14330:1433 and connect to localhost,14330.

"The certificate chain was issued by an authority that is not trusted"

The client is validating the container's self-signed certificate. Enable "trust server certificate" in the client, add -C to sqlcmd, or add TrustServerCertificate=True to the connection string.

"Login failed for user 'sa'"

The password is wrong, often because the shell changed it (for example $ in double quotes) or because the volume was initialized earlier with a different password. Try the original password from when the volume was created.

It crashes or hangs on Apple Silicon

Confirm Rosetta is enabled in Docker Desktop, that the Virtual Machine Manager is the Apple Virtualization framework, and that Docker Desktop and macOS are up to date. Then try another image tag. If the problem persists, remember that this configuration is not supported by Microsoft, and consider a remote x86-64 host.

FAQ

Can I install SQL Server directly on macOS without Docker?

No. SQL Server runs on Windows and Linux. On a Mac it always runs inside something else: a Docker container, a Linux or Windows virtual machine, or a remote server.

Is there SSMS for Mac?

No. SSMS is a Windows application and Microsoft has not released a macOS version. Use a Mac-native client or VS Code with the MSSQL extension for daily work, and a Windows VM if you need SSMS-specific features.

Can I still use Azure SQL Edge on an M1 or M2 Mac?

Not as a long-term option. Microsoft dropped ARM64 support from Azure SQL Edge and then retired the product on September 30, 2025, so it receives no fixes or security updates. Use the SQL Server image with Rosetta emulation for new projects.

Which SQL Server edition does the container run?

Developer edition by default. You can set MSSQL_PID to Express, or to a paid edition if you have a license for it.