# Single file versus multiple files in a Swift package

**URL:** <https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126>\
**Category:** Using Swift\
**Tags:** compiler, runtime, best-practices, swift-package\
**Created:** [July 15, 2025, 12:59pm UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126 "2025-07-15T12:59:55Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![wigging](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/wigging/32/34513_2.png) [@wigging](https://forums.swift.org/u/wigging)\
**Post date:** [July 15, 2025, 12:59pm UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/1 "2025-07-15T12:59:55Z")

</div>

I have a Swift package that does various numerical calculations. All of the algebra related code is in an `Algebra.swift` file which contains a protocol and extensions that conform to the protocol. This file has gotten very large and tedious to work with. So I extracted the code into several individual files such as the following:

```plaintext
.
├── Algebra.swift
├── Double+Algebra.swift
├── Float+Algebra.swift
├── Int+Algebra.swift
├── Matrix+Algebra.swift
└── Vector+Algebra.swift

```

where the protocol is defined in `Algebra.swift` and all the conforming type extensions are in the `+` files. I find this easier to work with instead of one large file but it drastically increases the number of files in the package.

I looked at some other Swift packages and noticed [BitArray](https://github.com/apple/swift-collections/tree/main/Sources/BitCollections/BitArray) in swift-collections uses multiple files instead of one large `BitArray.swift` file. However, [Chunked](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Chunked.swift) in swift-algorithms puts everything in one file including the extensions. Using one file versus multiple files seems to vary by project but I'm not sure why one approach is used over the other.

Does it matter in Swift if everything is in one large file compared to several smaller files? Does it affect compilation speed or runtime performance? What are the pros and cons of one file versus multiple files?

---

<div class="post-metadata">

**Author:** ![Max\_Desiatov](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/max_desiatov/32/20654_2.png) [@Max\_Desiatov](https://forums.swift.org/u/Max_Desiatov)\
**Post date:** [July 15, 2025, 1:46pm UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/2 "2025-07-15T13:46:51Z")

</div>

> [@wigging](#):
>
> Does it matter in Swift if everything is in one large file compared to several smaller files? Does it affect compilation speed or runtime performance? What are the pros and cons of one file versus multiple files?

Depends on how many smaller files. You'll potentially get multiple `swift-frontend` invocation for each file, but dependencies between files make parallelized builds not entirely straightforward. They at least can be parsed independently in parallel I suppose, but I don't think parsing was ever a bottleneck for most projects.

I don't have enough knowledge of `swiftc` and `swift-frontend` to clarify more from that perspective, but I'll comment from the current SwiftPM and build system implementation perspective: SwiftPM traverses all files in all targets in the root package and all of its transitive dependencies, and then serializes them in a (potentially huge) build manifest file before handing that off to a build system. The actual build with `swiftc`/`clang` invocations can't start before traversal and serialization of the build manifest is finished. The new build system changed the serialization format, but this principle stays the same: any addition of packages, targets, and files in them increases the time spent in this traversal and serialization step, which slows down the overall build time. And that's also the fixed cost incurred for any incremental build, not just cold builds.

If you split 1 file into 5 files, you probably won't notice the build manifest serialization slowdown. But if you split 100 files into 500 files, that could add significant delay to `swift build` invocations. That delay is also added to all packages that depend on your package with those 500 files, because their build manifests will have at least 500 build graph nodes (or more, depending on some implementation details) added to them.

---

<div class="post-metadata">

**Author:** ![wigging](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/wigging/32/34513_2.png) [@wigging](https://forums.swift.org/u/wigging)\
**Post date:** [July 15, 2025, 11:27pm UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/3 "2025-07-15T23:27:11Z")

</div>

Sounds like it's better to just keep everything in one file and navigate through that file with my text editor. That would definitely clean up the package directory.

---

<div class="post-metadata">

**Author:** ![j-f1](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/j-f1/32/12287_2.png) [@j-f1](https://forums.swift.org/u/j-f1)\
**Post date:** [July 16, 2025, 12:48am UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/4 "2025-07-16T00:48:24Z")

</div>

Performance concerns aside, one concrete benefit of breaking your code up into multiple files is that `private` and `fileprivate` declarations are inaccessible from other files. Especially for risky code, keeping the amount of code you have to read to verify correct behavior to a minimum can be handy.

---

<div class="post-metadata">

**Author:** ![ibex](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ibex/32/30439_2.png) [@ibex](https://forums.swift.org/u/ibex)\
**Post date:** [July 16, 2025, 1:11am UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/5 "2025-07-16T01:11:40Z")

</div>

> [@wigging](#):
>
> Sounds like it's better to just keep everything in one file and navigate through that file with my text editor.

Putting all your eggs in one basket - not a good idea. 🙂

---

<div class="post-metadata">

**Author:** ![coenttb](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/coenttb/32/44217_2.png) [@coenttb](https://forums.swift.org/u/coenttb)\
**Post date:** [July 16, 2025, 9:12pm UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/6 "2025-07-16T21:12:40Z")

</div>

I just wrote a blog post on this topic from an architectural perspective—without diving into build-time technicalities.

It might be useful if you’re interested in how to build a package step-by-step, starting simple and gradually adding complexity while surfacing the issues that come with it.

Read it here 👉 [coenttb.com/blog/4](https://coenttb.com/blog/4)

---

<div class="post-metadata">

**Author:** ![wigging](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/wigging/32/34513_2.png) [@wigging](https://forums.swift.org/u/wigging)\
**Post date:** [July 17, 2025, 3:55am UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/7 "2025-07-17T03:55:51Z")

</div>

Your article is great. Thank you for sharing. I have tried the multiple targets approach but it doesn't play nice with DocC. It gets confused sometimes when linking to code with similar names that are in different targets. I also had issues with the rendered docs on Swift Package Index where links wouldn't work. It would be great if you could write a follow-up article about the different architectural approaches and how they affect documentation and testing.

---

<div class="post-metadata">

**Author:** ![coenttb](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/coenttb/32/44217_2.png) [@coenttb](https://forums.swift.org/u/coenttb)\
**Post date:** [July 17, 2025, 5:55am UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/8 "2025-07-17T05:55:36Z")

</div>

Those are excellent suggestions - thank you! I hadn’t thought about writing on DocC, mostly because I ran into similar cross-linking limitations (though I know improvements are underway).

Testing, on the other hand, has been a real pleasure in a multi-target or multi-package setup. With each target narrowly scoped, achieving thorough test coverage becomes very manageable. If you’re curious how I approach this, feel free to check out [swift-html-css-pointfree](https://github.com/coenttb/swift-html-css-pointfree).

If you enjoyed the blog, I’d love it if you [subscribed to my newsletter](https://coenttb.com/newsletter/subscribe) - it really helps!

---

<div class="post-metadata">

**Author:** ![Josh\_Wisenbaker](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/josh_wisenbaker/32/2203_2.png) [@Josh\_Wisenbaker](https://forums.swift.org/u/Josh_Wisenbaker)\
**Post date:** [July 17, 2025, 3:32pm UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/9 "2025-07-17T15:32:40Z")

</div>

Another issue with multi-module packages is that they can't be delivered as a binary dependency as XCFrameworks can only contain one module. If SPM supported regular frameworks then it wouldn't be an issue.

Overall though breaking things into modules fits well with how Swift compiles and with the access controls in Swift. With packages it let us drop Carthage and deliver our mixed language Swift/Obj-C code as a single package as well.

---

<div class="post-metadata">

**Author:** ![coenttb](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/coenttb/32/44217_2.png) [@coenttb](https://forums.swift.org/u/coenttb)\
**Post date:** [July 21, 2025, 3:38pm UTC](https://forums.swift.org/t/single-file-versus-multiple-files-in-a-swift-package/81126/10 "2025-07-21T15:38:33Z")

</div>

I took your suggestion and wrote about testing. Would love to hear what you think!

👉 [Click here to read the article](https://coenttb.com/blog/6)
