When shipping a Swift HTTP service in Linux containers, how does building with the Static Linux SDK differ from swift build --static-swift-stdlib?
answer
- two different meanings of static
- who still provides the C library
- musl instead of glibc
- no dlopen at all
- SDK and toolchain versions must match
basics
~10 s--static-swift-stdlib links the Swift runtime and standard library into the binary but still loads glibc and system libraries dynamically; the Static Linux SDK links everything, musl included, so the binary has no shared-library dependencies.
solid answer
~50 sWith a normal glibc toolchain, `swift build -c release --static-swift-stdlib` removes the need to install the Swift runtime on the host, but the executable still links glibc dynamically, plus any system library it uses, such as libcurl for FoundationNetworking or libxml2 for FoundationXML, so the runtime image must provide those and be close to the build distribution. The Static Linux SDK, available since Swift 6.0, is a Swift SDK installed with `swift sdk install <url> --checksum <sum>`. Building with `--swift-sdk x86_64-swift-linux-musl` or `aarch64-swift-linux-musl` links against musl and the SDK's bundled copies of libraries such as curl, libxml2 and zlib, so the binary depends only on the Linux system-call interface and runs on any distribution. The price: no dynamic linking at all (`dlopen()` does not work), C dependencies must be static archives, `import Glibc` code needs a `canImport(Musl)` branch, and the SDK must match the toolchain version exactly. On macOS that means a swift.org toolchain; Xcode's cannot use the SDK.
code
bash · 11 lines# glibc toolchain: Swift runtime linked in, glibc and libcurl still shared
swift build -c release --static-swift-stdlib
# Static Linux SDK: install once per toolchain version
swift sdk install <static-linux-sdk-url> --checksum <checksum>
swift sdk list
# fully static binaries for x86-64 and ARM64 servers
swift build -c release --swift-sdk x86_64-swift-linux-musl
swift build -c release --swift-sdk aarch64-swift-linux-musl
file .build/x86_64-swift-linux-musl/release/<product>go deeper
Recall that a Linux binary normally needs the Swift runtime and glibc on the host, and that the Static Linux SDK builds one that needs neither.
Explain the table: --static-swift-stdlib links only the Swift runtime, while the SDK links musl and bundled libraries, and give the musl target IDs.
Diagnose a port: missing libcurl in a slim image, an import Glibc failure under musl, a dlopen plugin, a mismatched SDK version, and the fix for each.
Decide the deployment shape: fully static binaries simplify images and distribution but forbid dynamic loading and make every C dependency your build's responsibility.
## Two different meanings of "static" A Swift executable on Linux depends on three layers of code it did not compile itself: the **Swift runtime and standard library**, the **C library** (glibc on most distributions), and any **system libraries** it uses, such as libcurl behind `URLSession`. "Static" can mean linking some or all of these into the binary. | | default build | `--static-swift-stdlib` | Static Linux SDK | |---|---|---|---| | Swift runtime and stdlib | shared, must be installed | linked in | linked in | | C library | glibc, shared | glibc, shared | **musl, linked in** | | libcurl, libxml2, zlib | shared from the host | shared from the host | bundled, linked in | | Runs on | matching distributions | matching distributions | any Linux kernel | | `dlopen()` | works | works | **does not work** | The swift.org server packaging guide notes that a `--static-swift-stdlib` build using FoundationNetworking or FoundationXML still needs libcurl or libxml2 installed on the target. And because glibc stays dynamic, a binary built on one distribution, or even one major version of it, is not guaranteed to run on another. ## What the Static Linux SDK is A **Swift SDK** (SE-0387) is an artifact bundle holding everything needed to compile for another platform: a sysroot, target libraries and a description of the tools to use. The **Static Linux SDK**, introduced with Swift 6.0, targets Linux with **musl**, a C library chosen because it supports static linking well and is permissively licensed. Everything is linked statically, so the program depends only on the Linux system-call interface and "will run on any Linux distribution." The SDK can be used from any host the toolchain supports, so you can build a Linux server binary on a Mac without a container. There is no Apple equivalent: Darwin's system-call table is not part of its ABI, so every system call must go through the dynamic system library, `libSystem`. ## Building with it 1. Install an **open-source swift.org toolchain**, for example with swiftly; on macOS, Xcode's bundled toolchain cannot be used with the SDK. 2. Install the SDK whose version matches that toolchain exactly: `swift sdk install <url> --checksum <checksum>` (the checksum is required for a remote URL). Remove an SDK left over from an older toolchain first with `swift sdk remove`. 3. Build: `swift build -c release --swift-sdk x86_64-swift-linux-musl` (or `aarch64-swift-linux-musl` for ARM64 servers). 4. Check: `file` reports the result as an ELF executable that is "statically linked". 5. Copy the binary into any Linux host or a minimal container image and run it. ## What breaks, and how to fix it - **No dynamic linking whatsoever.** `dlopen()` does not work, so plugin systems that load shared objects at run time must change design. - **Bring your own dependencies.** System libraries from the distribution are unusable. The SDK ships a small set (curl, libxml2, zlib and the others its SBOM lists); any other C or C++ library must be built as a static `.a` archive and given a module map. - **Glibc-specific imports.** Code that does `#elseif os(Linux) import Glibc` fails; switch to `#elseif canImport(Glibc) … #elseif canImport(Musl) import Musl`. Use `swift package edit` to patch a dependency locally and send the fix upstream. - **C API differences.** A C type may import differently under musl: a result `Optional` in one library and not the other, or a pointer imported as `OpaquePointer` instead of `UnsafePointer<T>`. - **Version lock-step.** Upgrading the toolchain means installing the matching SDK; mismatches fail to build. Packages that use Foundation or SwiftNIO "should just work"; static linking also means you only pay for the library code you actually use. ## Choosing for a container - `--static-swift-stdlib` is enough when you control the base image and it matches the build distribution; the image still carries glibc and libcurl or libxml2 if you use them. - The Static Linux SDK fits a tool you copy onto unknown hosts, an image with nothing else in it, or a team building Linux binaries from Macs. - Neither changes the language: the same source, language mode and concurrency checking apply; only linking differs. ## Auditing what you ship - The Static Linux SDK includes a **software bill of materials** in SPDX format, listing the exact versions of musl, curl, libxml2, zlib and the other bundled libraries; tools such as `bom document outline` print it. - You can override a bundled library by placing a newer static build earlier in the linker's search path, but it must stay ABI-compatible with the version the SDK's other libraries were built against. - Because the binary carries its C library and dependencies, a security fix in one of them means rebuilding and redeploying the binary, not updating a package on the host.
- A dependency fails to build with the Static Linux SDK at import Glibc. What is the fix?The SDK uses musl, not glibc, so the module is `Musl`. Replace an `os(Linux)` branch with `#elseif canImport(Glibc) import Glibc #elseif canImport(Musl) import Musl`. Make the dependency editable locally with `swift package edit`, fix it there, and upstream the change. Occasionally a C function also imports with different optionality under musl, which needs a small source adjustment.
- Why can't you build a fully static executable for macOS the same way?On Linux the system-call interface is the stable ABI, so a binary can talk to the kernel directly. Darwin's system-call table is not part of its ABI; every system call must go through the dynamic system library `libSystem`, so a 100 % statically linked macOS binary is not possible and no such SDK exists.
- Your service uses a C library the SDK does not bundle. What do you have to provide?A static build of it: the `.a` archive on the linker's search path, its headers on the include path if Swift calls it directly, and a module map so Swift can import it. If it replaces a library the SDK already ships, it must stay ABI-compatible with the version the SDK's other libraries were built against.
--static-swift-stdlib is moving into a flat with your own furniture but still using the building's plumbing, so you can only move into buildings with compatible pipes. The Static Linux SDK is a camper van that carries its own water too: it parks anywhere, but it can never hook into a building's supply, which is why dlopen() stops working.
- Says --static-swift-stdlib produces a binary with no dynamic dependencies.
- Expects dlopen-based plugins to keep working with the Static Linux SDK.
- Uses Xcode's bundled toolchain on macOS to build with the Static Linux SDK.
- Thinks the Static Linux SDK still links against the host's glibc.
- Installs a Static Linux SDK from an older toolchain release and expects it to work.
Assumes Swift 6.4; the fully static Linux SDK has been available from swift.org since Swift 6.0, and each SDK release must match the toolchain version exactly.