swift-numerics: three modules, one stability promise, and a Complex naming workaround

Two categories of API and one shared fate

The package explains itself through a taxonomy rather than a feature list. Some modules hold API that is too specialized for the standard library but general enough to centralize. Others hold API being developed toward possible future inclusion in the standard library.

The two categories overlap, and an API can move from the first to the second as it matures. That migration is the long-term argument for using the package: you are picking up code that may end up in the language itself, which changes how you should read its rough edges today.

The modules themselves are deliberately fine-grained. If you only need complex numbers, you import just that module rather than dragging in everything. A top-level Numerics module re-exports the complete public interface when you want the whole surface.

Dependencies are a design constraint worth noting. The current modules assume only the Swift and C standard libraries plus the runtime support provided by compiler-rt. Future expansion may assume BLAS and LAPACK, but the README states plainly that modules with heavier or platform-limited dependencies belong in a separate package instead.

Why the module is ComplexModule and not Complex

The naming looks odd until you know the reason. Swift currently cannot use the fully-qualified type name when a type and a module share a name, so a module called Complex would break name lookup for anyone who did not need the generic parameter:

import ComplexModule

let z = Complex<Double>.i

The pattern the README recommends is importing the Module-suffixed name and then defining your own typealias for the concrete instantiation:

import ComplexModule
// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
typealias Complex = ComplexModule.Complex<Double>
// But I can still refer to the generic type by qualifying the name if I need it occasionally:
let a = ComplexModule.Complex<Float>

The same suffix is applied to RealModule, for a different reason: the Real module contains no Real type, but it does define a Real protocol, and users may want to define their own Real type or re-export the module themselves.

The README also notes that new modules have to evaluate this decision carefully and can err on the side of adding the suffix. Expect it to spread.

Adding the package to a SwiftPM target in three edits

The integration path is a SwiftPM dependency, declared in Package.swift. First add the package:

.package(url: "https://github.com/apple/swift-numerics", from: "1.0.0"),

Then list Numerics as a dependency of your target:

.target(name: "MyTarget", dependencies: [
  .product(name: "Numerics", package: "swift-numerics"),
  "AnotherModule"
]),

Finally, import it in your source. If you want only part of the surface, importing the individual module such as ComplexModule works the same way and keeps the dependency narrow.

The repository also carries a CMakeLists.txt and a cmake directory alongside Package.swift, so the build is not SwiftPM exclusive, though the documented integration instructions cover the SwiftPM path only.

What source stable actually excludes

The stability promise is precise enough to be worth reading closely. The package is source stable and version numbers follow semantic versioning. The public API is defined as the non-underscored declarations marked either public or usableFromInline in modules re-exported by the top-level Numerics module.

Interfaces outside that definition may change in any release, including patch releases. There is one more explicit carve-out: the contents of _NumericsShims and _TestSupport modules, along with the contents of the Tests directory, are stated not to be public API at all. Their definitions may change at whim and the entire module may be removed in a new release.

If you need an underscored operation, the README asks you to raise an issue requesting that it become public API. That is the correct route rather than relying on it.

There is a forward-looking caveat too: minor versions of the package may change these rules as needed, and the maintainers expect new package versions to require a more recent Swift toolchain from time to time. Requiring a new Swift release only needs a minor version bump.

Three modules today, and one that is not in any release

The current module list is short. RealModule provides the Real protocol and the associated numeric API. ComplexModule provides complex numbers. IntegerUtilities is listed third with a parenthetical note that it is on main only and is not yet present in a released tag.

That parenthetical is the kind of detail that decides whether you can use a package today. Depending on from a released tag means IntegerUtilities is simply not there, and a code path that imports it will fail to resolve. Tracking main gets you the module at the cost of the stability promise above, since main carries whatever the next release will contain.

The planned expansion list is on GitHub issues rather than in the tree: large fixed-width integers, arbitrary-precision integers, shaped arrays and decimal floating-point. Those are directions, not shipped modules, and nothing in the repository indicates a timeline.

Apache-2.0 and a deliberate alignment with Swift upstream

The licence is Apache-2.0, and the package uses the same licence and contribution guidelines as the Swift project. The stated reason is an intention to make adoption into the standard library possible at some point.

The repository is separate from the core Swift project and functions as a staging ground. When an API here matures, it is proposed to the Swift Standard Library through the established Swift evolution process. The repository structure backs this up: a LICENSE.txt, a CONTRIBUTING.md and standard Swift project layout.

Proposals go through GitHub issues and development happens in pull requests. A new module starts with an issue carrying the new module tag, then a pull request with an implementation sketch, then consensus, then a feature branch created by an admin, and finally a pull request to merge into main. Enhancements to existing modules use the enhancement tag. Bug fixes are pull requests with added test coverage.

Questions that are not clearly bugs go to the Swift forums section for this package rather than to the issue tracker.

On maintenance: the repository is not archived and the last push was on 2026-10-11. Release 1.1.1 added $Embedded support on 2025-09-25, preceded by 1.1.0, tagged Relax, on 2025-08-28.

Editorial conclusion

Adopt swift-numerics for numeric work in Swift when you want library-quality Complex and Real types without pulling in BLAS-sized dependencies, and pin to a released tag rather than main because IntegerUtilities ships on main only. Do not build against underscored operations, since the package reserves the right to change or delete them in any patch release. Before adding it, read the stability section of the README against your Swift toolchain version, because a new package release can require a newer toolchain on a minor version bump alone.

Frequently asked questions

Official sources

1. apple/swift-numerics on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases