Swiftpack.co - Package - MaxDesiatov/CoreXLSX


Excel spreadsheet (XLSX) format parser written in pure Swift

Build Status Version License Platform Coverage

CoreXLSX is a library focused on representing the low-level structure of XML-based XLSX spreadsheet format. It allows you to open a spreadsheet archive and map its XML structure into model types expressed directly in Swift.


To run the example project, clone the repo, and run pod install from the Example directory first.

Model types in CoreXLSX directly map internal structure of XLSX format with more sensible naming applied to a few attributes. The API is pretty simple:

import CoreXLSX

guard let file = XLSXFile(filepath: "./categories.xlsx") else {
  fatalError("XLSX file corrupted or does not exist")

for path in try file.parseWorksheetPaths() {
  let ws = try file.parseWorksheet(at: path)
  for row in ws.data?.rows ?? [] {
    for c in row.cells {

This prints every cell from every worksheet in the given XLSX file. Please refer to the Worksheet model for more atttributes you might need to read from a parsed file.

Shared strings

Some cells (usually with strings) have their values shared in a separate model type, which you can get by evaluating try file.parseSharedString(). You can refer to the SharedStrings model for the full list of its properties.

Here's how you can get all shared strings in column "C" for example:

let sharedStrings = try file.parseSharedStrings()
let columnCStrings = ws.cells(atColumns: [ColumnReference("C")!])
  .filter { $0.type == "s" }
  .compactMap { $0.value }
  .compactMap { Int($0) }
  .compactMap { sharedStrings.items[$0].text }


Since version 0.5.0 you can parse style information from the archive with the new parseStyles() function. Please refer to the Styles model for more details. You should also note that not all XLSX files contain style information, so you should be prepared to handle the errors thrown from parseStyles() function in that case.

Here's a short example that fetches a list of fonts used:

let styles = try file.parseStyles()
let fonts = styles.fonts?.items.compactMap { $0.name?.value }

Reporting compatibility issues

If you stumble upon a file that can't be parsed, please file an issue posting the exact error message. Thanks to use of standard Swift Codable protocol, detailed errors are generated listing a missing attribute, so it can be easily added to the model enabling broader format support. Attaching a file that can't be parsed would also greatly help in diagnosing issues. If these files contain any sensitive data, we suggest obfuscating or generating fake data with same tools that generated original files, assuming the issue can still be reproduced this way.

If the whole file can't be attached, try passing a sufficiently large value (between 10 and 20 usually works well) to errorContextLength argument of XLSXFile initializer. This will bundle the failing XML snippet with the debug description of thrown errors. Please also attach the full debug description if possible when reporting issues.

How does it work?

Since every XLSX file is a zip archive of XML files, CoreXLSX uses XMLCoder library and standard Codable protocols to map XML nodes and atrributes into plain Swift structs. ZIPFoundation is used for in-memory decompression of zip archives. A detailed description is available here.


  • Xcode 10.0 or later
  • Swift 4.2 or later
  • iOS 9.0 / watchOS 2.0 / tvOS 9.0 / macOS 10.11 or later deployment targets


Swift Package Manager

Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies.

Once you have your Swift package set up, adding CoreXLSX as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
  .package(url: "https://github.com/MaxDesiatov/CoreXLSX.git",
           .upToNextMajor(from: "0.8.0"))


CoreXLSX is available through CocoaPods. To install it, simply add pod 'CoreXLSX', '~> 0.8.0' to your Podfile like shown here:

source 'https://github.com/CocoaPods/Specs.git'
# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'
target '<Your Target Name>' do
  pod 'CoreXLSX', '~> 0.8.0'


Carthage is a dependency manager that builds your dependencies and provides you with binary frameworks.

Carthage can be installed with Homebrew using the following command:

$ brew update
$ brew install carthage

Inside of your Cartfile, add GitHub path to CoreXLSX and its latest version:

github "MaxDesiatov/CoreXLSX" ~> 0.8.0

Then, run the following command to build the framework:

$ carthage update

Drag the built frameworks (including the subdependencies XMLCoder and ZIPFoundation) into your Xcode project.


For development work and for running the tests in Xcode you need to run carthage bootstrap in the root directory of the cloned repository first. Then you can open the CoreXLSX.xcodeproj from the same directory and select the CoreXLSXmacOS scheme. This is the only scheme that has the tests set up, but you can also build any other scheme (e.g. CoreXLSXiOS) to make sure it builds on other platforms.

If you prefer not to work with Xcode, the project fully supports SwiftPM and the usual workflow with swift build and swift test should work, otherwise please report this as a bug.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to corexlsx@desiatov.com.


Max Desiatov, Matvii Hodovaniuk


CoreXLSX is available under the Apache 2.0 license. See the LICENSE file for more info.


Stars: 295
Help us keep the lights on


0.8.0 - Jul 12, 2019

Feature and bugfix release that makes the library compatible with more spreadsheet types. It also adds support for Comments structure, which can be parsed with the new parseComments API.

Many thanks to @grin, @GoldenJoe and @LiewLi for reporting and fixing issues in this release.

Closed issues:

  • parseDocumentPaths has internal protection, but is needed by parseDocumentRelationships #74 (GoldenJoe)
  • Missing Documentation #73 (GoldenJoe)

Merged pull requests:

0.7.0 - May 25, 2019

Bugfix release that improves compatibility with different spreadsheet types.

Thanks to @grin for reporting and fixing issues in this release.

Breaking changes

All properties on struct Format except fontId and numberFormatId are now optional.


New borderId and fillId properties on struct Format.

Fixed bugs

  • Can't get cell string #58
  • Can't load basic spreadsheets created in Google Docs #64
  • fillId and borderId attributes missing from CoreXLSX.Format #65

Merged pull requests

0.6.1 - May 9, 2019

Bugfix release that adds case externalLink to Relationship.SchemaType improving .xlsx compatibility.

0.6.0 - May 2, 2019

This is a bugfix release with changes to the model API that improve compatibility with files containing formulas and varied shared strings formats.


  • new struct Formula added with a corresponding property on struct Cell
  • property color on struct Properties became optional
  • properties on struct RichText became optional
  • new chartsheet case added to enum Relationship
  • richText on struct SharedStrings became an array, not optional

Closed issues

  • Error Domain=NSCocoaErrorDomain Code=4865 "Expected String but found null instead." #59
  • Importing XLSX file #56
  • Error ParseCellContent #51
  • error parseWorksheet #50
  • Couldn't find end of Start Tag c #37

Merged pull requests

0.5.0 - Apr 18, 2019

This is a release with API additions and bug fixes.

This release of CoreXLSX can be integrated as a Swift 5 module if you're using Xcode 10.2, but support for Swift 4.2 and earlier Xcode 10 versions is also maintained.

Compatibility is improved for big files and files that internally contain namespaced XML. A few other previously reported compatibility issues are now fixed. Many thanks to everyone who reported the issues, the improvements in this release wouldn't be possible without your contribution!

Breaking changes

Several properties on the model types became optional when there's no guarantee they are always available in files generated by different apps and tools.


Now you can parse style information from the archive with the new parseStyles() function. Please refer to the Styles model for more details. Please note that not all XLSX files contain style information, so you should be prepared to handle the errors thrown from parseStyles() function in that case.

Merged pull requests