possible release notes for v0.11.0

[TimG1964]

(EDIT1 18-Sep - to reflect comments from @nhz2, below)
(EDIT2 19-Sep - to reflect #321 from @nhz2)
(EDIT3 09-Oct - to reflect #326 (proposed setFormula function) and add list of fixed issues)
(EDIT4 20-Oct - update list of fixed issues)
(EDIT5 10-Nov - update list of fixed issues (again))
(EDIT6 01-Dec - Change rename! to renamesheet! for consistency)
(EDIT7 07-Dec - to reflect #332 supporting transposed tables)
(EDIT8 16-Jan - to reflect #341 reducing the memory footprint)
(EDIT9 21-Feb - To reflect #343 including support for AnnotatedStrings to create rich text formats)
(EDIT10 03-Mar - To reflect comments left in #335)

Hi Felipe,

You may not want these, but I drafted some release notes for v0.11.0. Discard if inappropriate.

v0.11.0 Release Notes

There are almost no changes in functional APIs in v0.11.0 compared with v0.10.4. Those changes that have been made are described briefly here.

Documentation

The documentation for this package has been extended substantially to cover the new functionality and all changes are (should be) reflected therein. In particular, a detailed guide to using the new formatting functions has been added.

New Functions

A number of new functions have been added compared with v0.10.4.

These include 18 new functions to support formatting of cells and cell values together with functions to copy or delete a sheet, to merge cells and to add new defined names for cells or cell ranges. In addition, it is now also possible to assign AnnotatedStrings (from StyledStrings.jl) to cells to create content using Excel's rich text formatting.

A new function, XLSXFile, is provided that takes a Tables.jl compatible table and creates a new XLSXFile object for writing and which can act as a sink for functions such as CSV.read.

A new function, renamesheet! is created to replace rename! for consistency in naming with addsheet!, copysheet! and deletesheet! and to avoid potential name conflicts when exported (e.g. with DataFrames.rename!). However, the existing function XLSX.rename! is retained (but not exported) to avoid a breaking change.

Two new functions, gettransposedtable and readtransposedtable, mirror gettable and readtable for worksheet tables that have data organised in rows rather than columns.

Some additional convenience functions have also been added to streamline functions that were already available (such as newxlsx, savexlsx).

A wide range of additional indexing options is now widely supported by most functions. Most functions now support indexing rows and columns using vectors, ranges and step ranges and will accept a colon.

Exported Functions

Most useful functions are now public, and can be used without the XLSX. prefix. The following function names are now exported:

• Files and worksheets
  XLSXFile, readxlsx, openxlsx, opentemplate, newxlsx, writexlsx, savexlsx,
  Worksheet, sheetnames, sheetcount, hassheet,
  addsheet!, renamesheet!, copysheet!, deletesheet!

• Cells & data
  CellRef, row_number, column_number, eachtablerow,
  readdata, getdata, gettable, readtable, readto,
  gettransposedtable, readtransposedtable,
  writetable, writetable!,
  setFormula,
  addDefinedName

• Formats
  setFormat, setFont, setBorder, setFill, setAlignment,
  setUniformFormat, setUniformFont, setUniformBorder, setUniformFill, setUniformAlignment, setUniformStyle,
  setConditionalFormat,
  getRichTextFormat
setColumnWidth, setRowHeight,
  getMergedCells, isMergedCell, getMergedBaseCell, mergeCells

The iterator XLSX.eachrow has retained the XLSX prefix to avoid making a breaking change. However, Base.eachrow now refers to XLSX.eachrow for XLSX.Worksheet data types, meaning that eachrow can be used without qualification, too.

Fixed issues

This release addresses the following issues:
#52, #61, #63, #80, #88, #120, #147, #148, #150, #155, #156, #159, #165, #172, #179, #184, #189, #190, #198, #222, #224, #232, #234, #235, #238, #239, #241, #243, #251, #252, #253, #258, #259, #260, #275, #276, #277, #278, #281, #284, #299, #301, #305, #308, #311, #314, #316, #324, #331, #335, #338, #342.

Breaking changes

There is only one breaking change in this version:

• infer_eltypes now defaults to true (e.g. in gettable and readtable).

I don't think there are any other breaking changes.

Internal changes

A number of changes to package internals have been made. Specifically, changes have been made to the following data structs:

• SheetRowStreamIteratorState
• WorksheetCacheIteratorState
• WorksheetCache
• XLSXFile
• Workbook
• Worksheet
• SheetRow
• Cell

In particular, the internal memory configuration of an XLSXFile object and its components have been changed significantly, nearly halving the package's memory footprint.

Changed dependencies

v0.11.0 has now fully migrated to ZipArchives.jl whereas v0.10.4 relied upon both this and ZipFiles.jl. In addition, xml support is now from XML.jl rather than EzXML.jl.

The use of AnnotatedStrings is supported through a package extension. This requires StyledStrings.jl to be in the active environment.

New functionality that has been added has brought the following additional dependencies compared with v0.10.4:

• Colors.jl
• UUIDs.jl
• Random.jl

In addition, the test suite now has dependencies on CSV.jl, Distributions.jl and StyledStrings.jl.

Precompilation

v0.11.0 now makes use of PrecompileTools.jl (initially only in a small way).

[nhz2]

Thanks for writing this summary of the changes.

I have some comments on the breaking changes. You should try to keep the old XLSX.eachrow defined for backwards compatibility. Any internal changes are by definition not breaking, so they shouldn't be in that section of the release notes. Lastly, as enable_cache is a performance hint, arguably, this is not a breaking change either.

Also, do we need to wait for JuliaComputing/XML.jl#35 to be fixed before making a new release, or is it not a blocking issue?

[TimG1964]

Thanks for the feedback.

If I simply redefined XLSX.eachrow as a synonym for Base.eachrow, would that be sufficient, do you think? This might give the best of both worlds (the switch to extending Base.eachrow was made based on #147, so at least one user wanted it. Otherwise, reverting is a simple matter of changing the definition, so trivial. I'd be happy either way, actually.

I haven't found JuliaComputing/XML.jl#35 to be a blocking issue - everything currently works fine (unless you know different). I don't think there is a need to wait.

[TimG1964]

I've reverted to XLSX.eachrow as suggested and amended the above text to reflect your other comments.

[chris-b1]

I'm seeing a significant performance drop for both reading & writing with a medium sized dataframe (160k rows, 32 columns, mix of numeric/strings). This is on data I can't share, but I can work up a reproducible example probably tomorrow.

Reading

# 0.10.3
julia> @time DataFrame(XLSX.readtable("temp.xlsx", 1; infer_eltypes=true))
 14.556886 seconds (176.34 M allocations: 11.664 GiB, 20.27% gc time)

# 0.11.0-dev
julia> @time DataFrame(XLSX.readtable("temp.xlsx", 1; infer_eltypes=true))
 46.722050 seconds (774.97 M allocations: 48.905 GiB, 37.92% gc time)

Writing

# 0.10.3
julia> @time XLSX.writetable("temp.xlsx", df; overwrite=true)
 25.303916 seconds (106.44 M allocations: 3.667 GiB, 23.80% gc time, 0.02% compilation time)

# 0.11.0-dev
julia> @time XLSX.writetable("temp.xlsx", df; overwrite=true)
 40.144590 seconds (258.08 M allocations: 15.922 GiB, 41.48% gc time)

[TimG1964]

On my machine, readtable is a little slower than v0.10.4 but the margin is much smaller than you show. On the other hand, writetable is very close to the same speed as v0.10.4.

Here are some figures from my machine this morning (based on a single run using @time):

XLSX (#master) v0.11.0-Dev
df roundtrip (cache enabled)
    readtable to df      59.463058 seconds (2.04 G allocations: 131.657 GiB, 44.57% gc time, 2852376 lock conflicts)
    writetable to file   35.603583 seconds (344.82 M allocations: 22.300 GiB, 29.69% gc time, 132988 lock conflicts)
df roundtrip (no cache)
    readtable to df      96.689584 seconds (2.02 G allocations: 135.128 GiB, 27.10% gc time, 2991459 lock conflicts)
    writetable to file   26.856996 seconds (344.82 M allocations: 22.300 GiB, 24.26% gc time, 132600 lock conflicts)

XLSX (release) v0.10.4
df roundtrip (cache enabled)
    readtable to df      37.252313 seconds (376.99 M allocations: 26.314 GiB, 34.81% gc time, 0.54% compilation time)
    writetable to file   29.623137 seconds (140.00 M allocations: 6.015 GiB, 1.91% gc time, 0.26% compilation time)
df roundtrip (no cache)
    readtable to df      32.743151 seconds (376.26 M allocations: 26.203 GiB, 23.66% gc time)
    writetable to file   30.392381 seconds (139.93 M allocations: 6.012 GiB, 3.89% gc time)

The default behaviour has changed from enable_cache=false and infer_eltypes=false on v0.10.4 to both being true on v0.11.0-Dev.

A possible cause of your slowdown might be because you are running on a single thread, but it will be good to get an MWE to try here.

For what it is worth, this is my system:

julia> versioninfo()
Julia Version 1.11.7
Commit f2b3dbda30 (2025-09-08 12:10 UTC)
Build Info:
  Official https://julialang.org/ release
Platform Info:
  OS: Windows (x86_64-w64-mingw32)
  CPU: 24 × AMD Ryzen 9 9900X 12-Core Processor
  WORD_SIZE: 64
  LLVM: libLLVM-16.0.6 (ORCJIT, generic)
Threads: 8 default, 0 interactive, 4 GC (on 24 virtual cores)
Environment:
  JULIA_EDITOR = code
  JULIA_VSCODE_REPL = 1
  JULIA_NUM_THREADS = 8

I realise reading from Excel to a df and writing from a df to Excel are likely important use cases where performance matters and the new functionality in v0.11.0-Dev is just unnecessary bells and whistles.

It seems a bit magic to me that v0.10.4 can read a file from Excel to a DF and write it back out as an Excel file quicker than it can read it into an XLSXFile and write it back out - but it does! Definitely something to look in to.

PS. I don't think allocations can be compared easily because v0.10.4 uses EzXML, which relies on a C library, (where allocations don't count), whereas v0.11.0-Dev uses XML.jl, which is pure Julia.

[chris-b1]

I was testing single threaded - more below, it seems like the perf difference on writing goes away (an improves multi-threaded) but some remains on reading.

setup & versioninfo()

function make_df(N=10_000, string_cols=6, int_cols=6, float_cols=6)
    data = Dict{Symbol, AbstractArray}()
    for i in 1:string_cols
        data[Symbol("string_$i")] = rand(["asdfaddasdf", "asdfjlkajlsdf", "da", "gf", "asdf"], N)
    end
    for i in 1:int_cols
        data[Symbol("int_$i")] = rand(0:10000, N)
    end

    for i in 1:float_cols
        data[Symbol("float_$i")] = rand(N)
    end

    return DataFrame(data)
end
df = make_df()

julia> versioninfo()
Julia Version 1.11.1
Commit 8f5b7ca12a (2024-10-16 10:53 UTC)
Build Info:
  Official https://julialang.org/ release
Platform Info:
  OS: Windows (x86_64-w64-mingw32)
  CPU: 16 × 12th Gen Intel(R) Core(TM) i7-1270P
  WORD_SIZE: 64
  LLVM: libLLVM-16.0.6 (ORCJIT, alderlake)
Threads: 1 default, 0 interactive, 1 GC (on 16 virtual cores)

Single Threaded, Reading

# 0.10.4
julia> @btime DataFrame(XLSX.readtable("temp.xlsx", 1; infer_eltypes=true));
  615.872 ms (6238821 allocations: 439.88 MiB)

#0.11-dev
julia> @btime DataFrame(XLSX.readtable("temp.xlsx", 1; infer_eltypes=true));
  1.207 s (26389058 allocations: 1.70 GiB)

Single Threaded, Writing

# 0.10.4
julia> @btime XLSX.writetable("temp.xlsx", df; overwrite=true)
  428.155 ms (3605947 allocations: 145.51 MiB)

#0.11-dev
julia> @btime XLSX.writetable("temp.xlsx", df; overwrite=true)
  579.230 ms (6141699 allocations: 321.08 MiB)

Eight Threads, Reading

# 0.10.4
julia> @btime DataFrame(XLSX.readtable("temp.xlsx", 1; infer_eltypes=true));
  517.302 ms (6238821 allocations: 439.88 MiB)
# 0.11-dev
julia> @btime XLSX.readtable("temp.xlsx", 1; infer_eltypes=true);
  673.041 ms (26389186 allocations: 1.70 GiB)

Eight Threads, Writing

# 0.10.4
julia> @btime XLSX.writetable("temp.xlsx", df; overwrite=true)
  443.860 ms (3606083 allocations: 145.51 MiB)
# 0.11-dev
julia> @btime XLSX.writetable("temp.xlsx", df; overwrite=true)
  356.183 ms (6141953 allocations: 321.63 MiB)

Eight Threads, Reading, N=200_000

# 0.10.4
julia> @btime DataFrame(XLSX.readtable("temp.xlsx", 1; infer_eltypes=true));
  12.320 s (124853775 allocations: 8.52 GiB)
# 0.11-dev
julia> @btime DataFrame(XLSX.readtable("temp.xlsx", 1; infer_eltypes=true));
  16.525 s (527931957 allocations: 33.97 GiB)

[TimG1964]

I've had a go a re-writing the SheetRowIterator to speed up read. I've managed to get the no-cache speed to match the with cache speed now - although still not quite as fast as v0.10.4. The bulk of the remaining bottleneck seems to be in creating each cell from the xml node. I might try to look at that next.

[chris-b1]

Thanks @TimG1964. And for what it's worth I do think the new formatting stuff is great - haven't had a chance to test it much yet, but definitely a much needed feature.

[TimG1964]

Still slower on read but faster on write than v0.10.4 (with 8 threads). I don't think I can do better, but others are very welcome to try!

Code

using XLSX, DataFrames, BenchmarkTools

function make_df(N=10_000, string_cols=6, int_cols=6, float_cols=6)
    data = Dict{Symbol, AbstractArray}()
    for i in 1:string_cols
        data[Symbol("string_$i")] = rand(["asdfaddasdf", "asdfjlkajlsdf", "da", "gf", "asdf"], N)
    end
    for i in 1:int_cols
        data[Symbol("int_$i")] = rand(0:10000, N)
    end

    for i in 1:float_cols
        data[Symbol("float_$i")] = rand(N)
    end

    return DataFrame(data)
end

function measure()
    for n in [10000, 200000, 1000000]
        df = make_df(n)
        print(rpad("writetable: n=$n ", 24), " : ")
        @btime XLSX.writetable("myfile.xlsx", $df; overwrite=true)
        print(rpad("readtable:  n=$n ", 24), " : ")
        @btime DataFrame(XLSX.readtable("myfile.xlsx", 1; infer_eltypes=true))
        println()
        end
end

measure()

v0.11.0-Dev (local)

writetable: x=10000      :   254.593 ms (5649150 allocations: 311.10 MiB)
readtable:  x=10000      :   494.690 ms (26934177 allocations: 1.71 GiB)

writetable: x=200000     :   6.728 s (113063513 allocations: 6.08 GiB)
readtable:  x=200000     :   12.466 s (538831604 allocations: 34.15 GiB)

writetable: x=1000000    :   34.695 s (564570824 allocations: 30.11 GiB)
readtable:  x=1000000    :   63.578 s (2694185328 allocations: 170.67 GiB)

v0.10.4 (release)

writetable: n=10000      :   403.095 ms (3606212 allocations: 145.52 MiB)
readtable:  n=10000      :   334.469 ms (6238951 allocations: 439.90 MiB)

writetable: n=200000     :   8.683 s (72459568 allocations: 2.85 GiB)
readtable:  n=200000     :   7.577 s (124853496 allocations: 8.52 GiB)

writetable: n=1000000    :   58.035 s (362367723 allocations: 14.22 GiB)
readtable:  n=1000000    :   47.157 s (624305398 allocations: 42.53 GiB)

Comparing with the numbers I posted above (which were for a dataset with 650k rows):

df roundtrip (cache enabled)
    readtable to df      49.907497 seconds (2.08 G allocations: 132.699 GiB, 50.89% gc time, 4 lock conflicts)
    writetable to file   23.382945 seconds (328.59 M allocations: 21.911 GiB, 15.49% gc time, 153676 lock conflicts)

df roundtrip (no cache)
    readtable to df      63.676876 seconds (1.74 G allocations: 111.169 GiB, 28.41% gc time, 4 lock conflicts)
    writetable to file   25.174322 seconds (328.59 M allocations: 21.911 GiB, 17.75% gc time, 120822 lock conflicts)

This version of the code is in this fork of XLSX. It would be great if you'd give it a go @chris-b1 to check it is all as it should be. If it is, I'll make another PR.

[jonalm]

Thanks for bringing excel support to the julia ecosystem. I was wondering what the status on 0.11 release is? I would love to see the Format functions in the package. Are performance issues discussed above what is blocking the release, or are there other outstanding issues?

[TimG1964]

From my point of view, the performance issues are adequately resolved. I'm not aware of any outstanding issues, but this is obviously up to the package owner. I'd like to see a new release, too, preferably with the additional PR I've made (supporting setting formulas) merged, too. In the mean time, the format functions are now all merged into the package master, so you can always use the dev version.

[jonalm]

@felipenoris any thoughts on a potential new release?

[TimG1964]

@JuliaRegistrator register