Running Q# and QDK on arm64 Mac

Β· 518 words Β· 3 minutes to read

Due to a combination of issues, the current Microsoft.Quantum.Sdk (at the time of writing, version 0.25.222597) does not support arm64 Macs, which of course are the flagship Apple silicon processors from the M1 and M2 family.

Hopefully these issues get resolved soon, but until then, this post will chronicle the necessary workarounds to be able to write Q#/QDK code on arm64 Macs.

.NET 6 SDK dependency πŸ”—

The QDK requires .NET 6 SDK to be installed on the developer’s machine. This is of course not a big obstacle, because the SDK can be quickly obtained from the official site. The problem is the SDK for Macs comes in two versions - one for arm64 and one for the x64 processor architecture. Being on the arm64 Mac, one naturally installs the arm64 flavor. However, QDK has never been compatible with the arm64 .NET (on any platform, not just Mac) and requires x64 .NET SDK installation. I reported this on Github a while ago, however it is unfortunately still not resolved.

The workaround in this case is to install x64 .NET 6 SDK and rely on Rosetta emulation. Both flavors of the SDK - arm64 and x64 - can happily co-exist on arm64 Mac, as the arm64 one gets installed into the primary path /usr/local/share/dotnet, while the x64 into the secondary one /usr/local/share/dotnet/x64.

Once x64 .NET SDK is installed, we can temporarily toggle from the default arm64 one and the x64 one by running:

export PATH=/usr/local/share/dotnet/x64:$PATH

Depending on one’s use case, this can also be done as a permanent change.

ARM processor incompatibility πŸ”—

The above workaround worked for several months, until release 0.22.186910 of the QDK. At that point, the default full state simulator of the QDK seemingly introduced additional instructions which are failing on the ARM processor architecture. The only thing affected is the default simulator, and other simulators work fine, but being the default one, it is also the one that is most commonly used. Due to the illegal hardware instructions the QDK became effectively unusable on arm64 Macs.

The workaround in this case is a lot more hacky, but at least recovers the core functionality of the simulator. The last working version of the full state simulator is 0.21.2112180703, and can be found on Nuget here. The page has a “Download package” link in the right hand column, which can be used to download the package, which has nupkg extension. The file is actually a ZIP file, so by changing the extension we can simply extract the contents.

Next, the files from the runtimes/os-x64/native folder have to be copied to the corresponding path under /.nuget/packages/microsoft.quantum.simulators/[current version], so for the current version of the QDK it would be: 0.25.222597/runtimes/os-x64/native. This effectively tells the current QDK to keep using the old 0.21.2112180703 full state simulator. There is no other way of doing this because the dependency version validation prevents one from succeeding.

The workaround is extremely fragile, but I have been using it successfully for several months now, and got reports from other users that it helped them too. Hopefully it is addressed at the QDK runtime level soon though!


Hi! I'm Filip W., a cloud architect from ZΓΌrich πŸ‡¨πŸ‡­. I like Toronto Maple Leafs πŸ‡¨πŸ‡¦, Rancid and quantum computing. Oh, and I love the Lowlands 🏴󠁧󠁒󠁳󠁣󠁴󠁿.

You can find me on Github and on Mastodon.

My Introduction to Quantum Computing with Q# and QDK book
Microsoft MVP