Files and worksheets

Functions for opening, creating and saving files, and for the sheets in them. For a walk-through, see the XLSX Tutorial and Creating and editing workbooks.

Files

XLSX.XLSXFile — Method
XLSXFile(table)

Take a Tables.jl compatible table and create a new XLSXFile object for writing. Can act as a sink for functions such as CSV.read.

Example

julia> using CSV, XLSX

julia> xf = CSV.read("iris.csv", XLSXFile)
XLSXFile("blank.xlsx") containing 1 Worksheet
            sheetname size          range
-------------------------------------------------
               Sheet1 151x5         A1:E151
source
XLSX.Workbook — Type
Workbook

The workbook part of an XLSXFile: its sheets, shared strings, styles and defined names, parsed from xl/workbook.xml. An XLSXFile holds one, as xf.workbook. Its fields are internal: work through the file and its worksheets.

source
XLSX.readxlsx — Function
readxlsx(source::Union{AbstractString, IO}) :: XLSXFile

Main function for reading an Excel file. This function will read the whole Excel file into memory and return an XLSXFile.

Functionally equivalent to `openxlsx(source; mode="r", enable_cache=true)

Consider using XLSX.openxlsx for lazy loading of Excel file contents.

source
XLSX.readto — Function
readto(
    source,
    [sheet,
    [columns]],
    sink;
    [table_name],
    [first_row],
    [column_labels],
    [header],
    [infer_eltypes],
    [stop_in_empty_row],
    [stop_in_row_function],
    [enable_cache],
    [keep_empty_rows],
    [normalizenames],
    [missing_strings]
) -> sink

Read and parse an Excel worksheet, materializing directly using the sink function, which can be any Tables.jl-compatible function (e.g. DataFrame, StructArray or TypedTable`).

Takes the same keyword arguments as XLSX.readtable, including table_name to read a named Excel Table (see XLSX.table) rather than a range of cells. Specifying sheet alongside table_name is faster, since only that worksheet is decompressed; omitting it searches every worksheet for the named table.

Example

julia> using DataFrames, StructArrays, TypedTables, XLSX

julia> df = XLSX.readto("myfile.xlsx", DataFrame)

julia> sa = XLSX.readto("myfile.xlsx", StructArray)

julia> tt = XLSX.readto("myfile.xlsx", Table) # from TypedTables.jl

julia> df = XLSX.readto("myfile.xlsx", "mysheet", DataFrame)

julia> df = XLSX.readto("myfile.xlsx", "mysheet", "A:C", DataFrame)

julia> df = XLSX.readto("myfile.xlsx", "mysheet", DataFrame; table_name="Sales")

julia> df = XLSX.readto("myfile.xlsx", DataFrame; table_name="Sales")

See also: XLSX.gettable, XLSX.readtable, XLSX.table.

source
XLSX.openxlsx — Function
openxlsx(f::F, source::Union{AbstractString, IO}; mode::AbstractString="r", enable_cache::Bool=true) where {F<:Function}

Open an XLSX file for reading and/or writing and applies the function f to the content.

Do syntax

This function should be used with do syntax, like in:

XLSX.openxlsx("myfile.xlsx") do xf
    # read data from `xf`
end

Filemodes

The mode argument controls how the file is opened. The following modes are allowed:

  • r : read-only mode. The existing data in source will be accessible for reading. This is the default mode.

  • w : write mode. Opens an empty file that will be written to source. If source already exists it will be overwritten.

  • rw : edit mode. Opens source for editing. The file will be saved (overwritten) to disk when the function ends.

Warning

Using do-block syntax in "rw" mode will overwrite the file you read in with the modified data when the do block ends. If the do block throws an error, the file is not written and source is left unchanged. To keep the original, open the file in "rw" mode without a do block and write the XLSXFile to another file name with writexlsx.

Parts of the file that XLSX.jl doesn't model, such as pivot tables and their caches, slicers, timelines, external links, custom XML and VBA projects, are kept as they are, but they are not updated: a pivot table shows its old values until it is refreshed in Excel, and the cells and sheets they refer to are not changed by insertRows, renamesheet! and the like. When saving, the formula calculation chain (xl/calcChain.xml) is dropped and the workbook is marked for Excel to recalculate on opening, as Excel rebuilds the chain itself. A file in Strict Open XML is saved in the usual (Transitional) form.

If source is an IO, its content is replaced in the same way, so it must be writable and seekable (e.g. IOBuffer(bytes; read=true, write=true)).

Note

When a native Excel template (.xltx) file is opened in "rw" mode using do-block syntax, it will always be written back out as a regular Excel file with a .xlsx extension at the termination of the do block. It is not written out as an Excel template file.

Arguments

  • source is IO or the complete path to the file.

  • mode is the file mode, as explained in the last section.

  • enable_cache:

If enable_cache=true and the file is opened in read-only mode, each worksheet's cells are loaded and cached the first time any cell on that sheet is read — the whole sheet is loaded at once, not just the cell you asked for. Subsequent reads of any cell on that sheet then come from the cache instead of reading from disk. This lazy, per-sheet caching is most efficient if you only intend to access one (or a few) sheets in a multi-sheet workbook. If you intend to access all or most sheets in full, the parallel caching used in write mode may be more efficient for your use case.

If enable_cache=true and the file is opened in write mode, all worksheets are eagerly loaded into the cache in parallel as the file is opened (they will be needed for writing anyway).

If enable_cache=false, worksheet cells are read by streaming through the worksheet's XML directly, without building a persistent cache of parsed cell data. This avoids the memory and time cost of constructing that cache, at the expense of needing to re-scan from the current position for each row accessed. It's most useful for a single, sequential pass over a worksheet's rows (e.g. converting it once to a table), where building a cache you'll never reuse would be wasted work.

The default value is enable_cache=true.

Examples

Read from file

The following example shows how you would read worksheet cells, one row at a time, where myfile.xlsx is a spreadsheet that doesn't fit into memory.

julia> XLSX.openxlsx("myfile.xlsx", enable_cache=false) do xf
          for r in eachrow(xf["mysheet"])
              # read something from row `r`
          end
       end

Write a new file

XLSX.openxlsx("new.xlsx", mode="w") do xf
    sheet = xf[1]
    sheet[1, :] = [1, Date(2018, 1, 1), "test"]
end

Edit an existing file

XLSX.openxlsx("edit.xlsx", mode="rw") do xf
    sheet = xf[1]
    sheet[2, :] = [2, Date(2019, 1, 1), "add new line"]
end

See also XLSX.readxlsx.

source
openxlsx(source::Union{AbstractString, IO}; mode="r", enable_cache=true) :: XLSXFile

Supports opening an XLSX file without using do-syntax.

If opened with mode="rw" then use savexlsx to save the XLSXFile back to source, overwriting the original file. Alternatively, use writexlsx to write the XLSXFile to a different filename.

These two invocations of openxlsx are functionally equivalent:

XLSX.openxlsx("myfile.xlsx", mode="rw") do xf
    # Do some processing on the content
end

xf = openxlsx("myfile.xlsx", mode="rw")
# Do some processing on the content
XLSX.savexlsx(xf)
source
XLSX.savexlsx — Function
savexlsx(f::XLSXFile)

Save an XLSXFile instance back to the file from which it was opened (given in f.source), overwriting original content.

A new XLSXFile created with XLSX.newxlsx (or using openxlsx without specifying a filename) will have source set to "blank.xlsx" and cannot be saved with this function. Use writexlsx instead to specify a new file name for the saved file.

An XLSXFile created from a native Excel template (.xltx) file or a macro-enabled template (.xltm) file will be saved as standard worksheet (.xlsx) or macro-enabled worksheet (.xlsm) respectively, regardless of the extension of the original template file.

If f was opened from an IO, the IO's content is replaced: it is written from the start and truncated to the new workbook's length. The IO must be writable and seekable, such as an IOBuffer(bytes; read=true, write=true).

Returns the filepath of the written file if a filename is supplied, or nothing if writing to an IO.

source
XLSX.opentemplate — Function
opentemplate(source::Union{AbstractString, IO}) :: XLSXFile

Read an existing Excel (.xlsx) file as a template and return as a writable XLSXFile for editing and saving to another file with XLSX.writexlsx.

A convenience function equivalent to openxlsx(source; mode="rw", enable_cache=true)

Examples

julia> xf = opentemplate("myExcelFile.xlsx")
source
XLSX.newxlsx — Function
newxlsx([sheetname::AbstractString]; update_timestamp::Bool) :: XLSXFile

Return an empty, writable XLSXFile with 1 worksheet for editing and subsequent saving to a file with XLSX.writexlsx. By default, the worksheet is Sheet1. Specify sheetname to give the worksheet a different name.

Use keyword argument update_timestamp=false to prevent timestamps in the file properties from being updated to the current date/time. This ensures bit-for-bit reproducible output when the file is written. The file Date will remain as 2018-05-22T02:41:32Z. The default is update_timestamp=true, resulting in the Date being set to the current UTC time in the new file.

Examples

julia> xf = XLSX.newxlsx()

julia> xf = XLSX.newxlsx("MySheet")
source
XLSX.writexlsx — Function
writexlsx(output_source::Union{AbstractString,IO}, xf::XLSXFile; [overwrite=false])

Write an XLSXFile given by xf to the IO or filepath output_source.

The source attribute of the XLSXFile will be updated to the output_source if it is a filepath.

Returns the filepath of the written file if a filename is supplied, or nothing if writing to an IO.

If overwrite=true, output_source (when a filepath) will be overwritten if it exists.

When output_source is an IO, it should be at its start (e.g. a new IOBuffer()), and overwrite has no effect. To save a workbook back to the IO it was opened from, replacing its content, use savexlsx.

See also savexlsx.

Note

When XLSX.jl reads strict (ISO/IEC 29500) XLSX files, it converts them eagerly on to transitional (ECMA 376) format. On write, XLSX.jl will always write in the transitional format, which is the Excel default. Excel itself can convert between strict and transitional formats. Use Excel directly to convert a transitional file to strict format, if needed.

source
XLSX.writetable — Function
writetable(filename, table; [overwrite], [sheetname])

Write a Tables.jl compatible table as an Excel file with the specified file name (and sheet name, if specified).

If a file with the given name already exists, writing will fail unless overwrite=true is specified, in which case the existing file will be overwritten.

This method also accepts a vector of (sheetname, data, columnnames) tuples, writing one worksheet per element. Sheet names may be AbstractString or Symbol, data may be any iterable of columns, and columnnames are converted to strings.

source
writetable(filename::Union{AbstractString, IO}, tables::Vector{<:Pair}; overwrite::Bool=false, as_table::Bool=false, table_style=nothing)
writetable(filename::Union{AbstractString, IO}, tables::Pair...; overwrite::Bool=false, as_table::Bool=false, table_style=nothing)

Write multiple Tables.jl compatible tables, one per worksheet, given as sheetname => table pairs — either collected in a vector or passed as separate arguments.

Sheet names may be AbstractString or Symbol, and the two may be mixed in a single call.

Example

julia> df1 = DataFrames.DataFrame(COL1=[10,20,30], COL2=["Fist", "Sec", "Third"])

julia> df2 = DataFrames.DataFrame(AA=["aa", "bb"], AB=[10.1, 10.2])

julia> XLSX.writetable("report.xlsx", "REPORT_A" => df1, :REPORT_B => df2)

julia> XLSX.writetable("report.xlsx", "REPORT_A" => df1, :REPORT_B => df2;
           overwrite=true, as_table=true, table_style="TableStyleMedium2")
source
writetable(filename, data, columnnames; [overwrite], [sheetname], [anchor_cell], [as_table], [table_name], [table_style], [totals],
           [column_widths], [column_formats], [freeze_header], [streaming], [shared_strings])
  • data is a vector of columns.
  • columnames is a vector of column labels.
  • overwrite is a Bool to control if filename should be overwritten if already exists.
  • sheetname is the name for the worksheet.
  • as_table is a Bool to turn the written range into an Excel Table if true.
  • table_name is the name of the Excel Table (if as_table=true)
  • table_style is the Excel style to use for the Table (if as_table=true)
  • totals defines whether and how Table totals are defined (if as_table=true)
  • column_widths, column_formats and freeze_header set the columns' widths and number formats and freeze the header row (see XLSX.writetable!).
  • streaming=true writes the rows straight into the file, a chunk at a time, rather than building the workbook in memory first, so a table of any size is written in about the same memory. A Tables.jl table that is read a row at a time (not by columns) is never held in memory as a whole. A streamed table starts in cell A1 and has no totals; strings are written inline unless shared_strings=true. See XLSX.streamxlsx and Writing large files.

For more details on table_name, table_style, totals, refer to XLSX.writetable!, XLSX.addtable! and XLSX.settotals!

The other forms of writetable, which write several sheets, take streaming too.

Returns the filepath of the written file if a filename is supplied, or nothing if writing to an IO.

Example

import XLSX
columns = [ [1, 2, 3, 4], ["Hey", "You", "Out", "There"], [10.2, 20.3, 30.4, 40.5] ]
colnames = [ "integers", "strings", "floats" ]
XLSX.writetable("table.xlsx", columns, colnames)

julia> XLSX.writetable("table.xlsx", columns, colnames; as_table=true, table_name="MyData")

julia> XLSX.writetable("table.xlsx", columns, colnames;
           as_table=true, table_name="MyData",
           totals=["integers" => :sum, "strings" => "Total"])

See also: XLSX.writetable!, XLSX.addtable!, XLSX.settotals!.

source
writetable(filename::Union{AbstractString, IO}; overwrite::Bool=false, as_table::Bool=false, table_style=nothing, kw...)

Write multiple tables.

kw is a variable keyword argument list. Each element should be in this format: sheetname=( data, column_names ), where data is a vector of columns and column_names is a vector of column labels.

Set as_table=true to also turn each sheet's written range into an Excel Table. table_style (if given) is applied to every table the same way.

When as_table=true, each table's name defaults to its sheet's name. If that isn't a valid Excel Table name it is normalized (spaces and invalid characters become underscores) and a warning is issued. If the normalized name collides with an existing table or defined name, a second warning is issued and an auto-generated name ("Table1", "Table2", ...) is used instead — sheet names and table names don't share the same character rules or, in the case of defined names, the same namespace guarantees.

Example:

julia> cols_a = [[10, 20, 30], ["Fist", "Sec", "Third"]];

julia> names_a = ["COL1", "COL2"];

julia> cols_b = [["aa", "bb"], [10.1, 10.2]];

julia> names_b = ["AA", "AB"];

julia> XLSX.writetable("report.xlsx"; REPORT_A=(cols_a, names_a), REPORT_B=(cols_b, names_b))

julia> XLSX.writetable("report.xlsx"; overwrite=true, as_table=true, table_style="TableStyleMedium2",
           REPORT_A=(cols_a, names_a), REPORT_B=(cols_b, names_b))
Note

Because sheet names are given as keywords, they must be valid Julia identifiers — REPORT_A works, "Report A" does not. They also share the keyword namespace with this method's own options so, using this method, a sheet cannot be named overwrite, as_table, table_style or streaming — such a keyword is taken as the option, and the resulting error will not mention sheet names. Use the Vector{Tuple{String, …}} form, or "Report A" => table pairs, for names that don't satisfy this.

See also: XLSX.writetable!, XLSX.addtable!, XLSX.settotals!.

source
writetable(filename::Union{AbstractString, IO}, tables::Vector{Tuple{String, Vector{Any}, Vector{String}}}; overwrite::Bool=false, as_table::Bool=false, table_style=nothing)

Write multiple tables.

Each element of tables is (sheetname, data, column_names), where data is a vector of columns and column_names is a vector of column labels.

Set as_table=true to also turn each sheet's written range into an Excel Table. table_style (if given) is applied to every table the same way.

When as_table=true, each table's name defaults to its sheet's name. If that isn't a valid Excel Table name it is normalized (spaces and invalid characters become underscores) and a warning is issued. If the normalized name collides with an existing table or defined name, a second warning is issued and an auto-generated name ("Table1", "Table2", ...) is used instead — sheet names and table names don't share the same character rules or, in the case of defined names, the same namespace guarantees.

Example

julia> XLSX.writetable("report.xlsx", [
           ("REPORT_A", columns_a, colnames_a),
           ("REPORT_B", columns_b, colnames_b),
       ]; as_table=true)

See also: XLSX.writetable!, XLSX.addtable!, XLSX.settotals!.

source

Streaming writes

Guide: Writing large files. XLSX.writetable streams a whole table with streaming=true; XLSX.addsheet! adds a sheet to a StreamWriter.

XLSX.streamxlsx — Function
streamxlsx(f, dest; overwrite=false, shared_strings=false)

Write a new workbook to dest, a file name or an IO, one row at a time, using memory bounded by a chunk of rows however many are written. f is called with a StreamWriter: add sheets to it with XLSX.addsheet! and write each sheet's rows with XLSX.writerow!. The file is complete when f returns.

Strings are written inline in each cell by default, which keeps memory bounded and is fastest. With shared_strings=true they go in a shared string table, as Excel writes them, which makes a file with many repeated strings a little smaller but holds every distinct string in memory until the file is finished. Excel reads both, and stores strings in its own shared table when it saves the file.

Values are written as by sheet[ref] = value: numbers, strings, Bools, and dates and times (with a default date or time format); missing and nothing leave a cell empty, and other types are written as their string. If f throws, a file written to a path is deleted.

A streamed sheet is written in one pass, so it can't be read or changed afterwards within f, and has only what addsheet! sets: column widths, number formats, a frozen header row and an Excel Table. See XLSX.writetable with streaming=true to stream a whole table.

Returns the path of the file written, or nothing when writing to an IO.

Example

julia> XLSX.streamxlsx("big.xlsx") do s
           sh = XLSX.addsheet!(s, "Data"; columns=["id", "name", "when"], freeze_header=true)
           for i in 1:1_000_000
               XLSX.writerow!(sh, (i, "item $i", Date(2026, 1, 1) + Day(i % 365)))
           end
       end
source
XLSX.writerow! — Function
writerow!(sh::StreamSheet, row)

Write row, a tuple, NamedTuple or vector of values, as the next row of a sheet being written by XLSX.streamxlsx, starting from column A. Values are written as described there; a row of nothing but empty values leaves the row empty. A NamedTuple's values are written in order: its names are not matched to the sheet's columns.

source

Files (using FileIO)

Guide: FileIO Tutorial.

Note

These functions extend FileIO.load and FileIO.save. Call them as FileIO.load(...) and FileIO.save(...) after doing using FileIO.

XLSX.load — Function
    FileIO.load(
        source::String,
        [sheet::String,
        [columns::String]];
        [first_row::Int],
        [first_column::String]
        [column_labels::Vector{String}],
        [header::Bool],
        [normalizenames::Bool],
        [transpose::Bool]
    )

Read tabular data from an Excel file, source, and return it as a Tables.jl compatible table. The resulting table object can be passed directly to any function that accepts Tables.jl data (e.g. DataFrame from package DataFrames.jl).

This function requires both FileIO.jl v1.20.0 or higher to be active in the current environment and a Julia version >= v1.10.

Arguments:

  • source: The name of the file to be loaded.
  • sheet: Specifies the sheet name to be loaded. If sheet is not given, the first Excel sheet in the file will be used.
  • columns: Determines which columns to read. For example, "B:D" will select columns B, C and D. If columns is not given, the algorithm will find the first sequence of consecutive non-empty cells. A valid sheet must be specified when specifying columns. If transpose = true or is omitted, columns should be used to specify rows. For example, specifying "2:4" with transpose = true will read only from these rows.
Note

The file extension provided in source must be .xlsx, .xltx, .xlsm, or .xltm for FileIO to recognize the file format as an Excel file.

Keywords:

  • first_row: Indicates the first row of the data table to be read. For example, first_row=5 will look for a table starting at sheet row 5. If first_row is not given, the algorithm will look for the first non-empty row in the sheet (ignored if transpose = true).
  • first_column: Indicates the first row of the data table to be read. For example, first_column="B" will look for a table starting at sheet row 5. If first_row is not given, the algorithm will look for the first non-empty row in the sheet (ignored if transpose = false or is omitted).
  • column_labels: Specifies column names for the header of the table. If column_labels are given and header=true, the headers given by column_labels will be used, and the first row of the table (containing headers) will be ignored.
  • header: Indicates if the first row (column if transpose = true) is a header. If header=true and column_labels is not specified, the column labels for the table will be read from the first row (column) of the table. If header=false and column_labels is not specified, the algorithm will generate column labels. The default value is header=true.
  • normalizenames: Set to true to normalize column names to valid Julia identifiers. Default=false.
  • transpose: Set to true to transpose the table to read data from rows not columns.

Examples

julia> PrettyTable(load("HTable.xlsx", "Offset"; first_row=2))

julia> df = DataFrame(load("HTable.xlsx", "Offset", "2:7"; transpose=true, first_column="B"))

julia> df = DataFrame(load("HTable.xlsx"; normalizenames=true, transpose=true, column_labels=["Date", "Name1", "Name2", "Name3", "Name4", "Name5"]))
source
XLSX.save — Function
    FileIO.save(
        source::String,
        data;
        [sheetname::String],
        [overwrite::Bool]
    )

Save a Tables.jl compatible table to an Excel file, source.

This function requires both FileIO.jl v1.20.0 or higher to be active in the current environment and a Julia version >= v1.10.

Arguments:

  • source: The name of the file to be created on save.
  • data: A Tables.jl compatible table to be saved to the file. For example, a DataFrame from package DataFrames.jl.
Note

The file extension provided in source must be .xlsx, .xltx, .xlsm, or .xltm for FileIO to recognize the file format as an Excel file. The file created will be a standard workbook (ie not an Excel template nor a macro-enabled workbook) regardless of which of these four extensions is used.

Keywords:

  • sheetname: Specify the sheetname to be used in the created file. By default, the sheetname will be Sheet1.
  • overwrite: Set overwrite=true to overwite any existing file of the same name. Default = false.

Examples

julia> save("myfile.xlsx", myTable; sheetname="myname", overwrite=true)
source

Worksheets

Guide: Managing worksheets. Images, comments and hyperlinks are on their own API page.

XLSX.Worksheet — Type

A Worksheet represents a reference to an Excel Worksheet.

From a Worksheet you can query for Cells, cell values and ranges.

Example

xf = XLSX.readxlsx("myfile.xlsx")
sh = xf["mysheet"] # get a reference to a Worksheet
println( sh[2, 2] ) # access element "B2" (2nd row, 2nd column)
println( sh["B2"] ) # you can also use the cell name
println( sh["A2:B4"] ) # or a cell range
println( sh[:] ) # all data inside worksheet's dimension
source
XLSX.sheetnames — Function
sheetnames(xl::XLSXFile)
sheetnames(wb::Workbook)

Return a vector with Worksheet names for this Workbook.

source
XLSX.hassheet — Function
hassheet(wb::Workbook, sheetname::AbstractString)
hassheet(xl::XLSXFile, sheetname::AbstractString)

Return true if wb contains a sheet named sheetname.

Sheet names are matched without regard to case, as Excel matches them: a workbook can't hold two sheets whose names differ only in case, so hassheet(xf, "data") finds a sheet named Data.

source
XLSX.addsheet! — Function
addsheet!(wb::Workbook, [name::AbstractString=""]) --> ::Worksheet
addsheet!(xf::XLSXFile, [name::AbstractString=""]) --> ::Worksheet

Create a new worksheet named name. If name is not provided, a unique name is created.

See also renamesheet!, copysheet!, deletesheet!, movesheet!

source
addsheet!(s::StreamWriter, [name=""]; columns, column_widths, column_formats,
          freeze_header=false, as_table=false, table_name="", table_style=nothing) -> StreamSheet

Add a worksheet to a workbook being written by XLSX.streamxlsx, closing the sheet added before it: sheets are written one after another. name defaults to the next free SheetN.

  • columns: column names, written as the first row.
  • column_widths: one width for every column (needs columns), or a vector of widths by column, nothing leaving a column's width as it is. Widths are in characters, as XLSX.setColumnWidth takes them.
  • column_formats: a Dict from column (number, or name in columns) to a number format, as XLSX.setFormat takes it, for every cell below the header.
  • freeze_header: freeze the first row, as XLSX.freezePanes does.
  • as_table, table_name, table_style: make the rows an Excel Table when the sheet is closed, as XLSX.addtable! does. Needs columns and at least one row below them.
source
XLSX.copysheet! — Function
copysheet!(ws::Worksheet, [name::AbstractString=""]) --> ::Worksheet

Create a copy of the worksheet ws and add it to the end of the workbook with the specified worksheet name. Return the new worksheet object. If name is not provided, a new name is generated by appending " (copy)" to the original worksheet name, with a further numerical suffix to guarantee uniqueness if necessary. To copy worksheets, the XLSXFile must be writable (opened with mode="rw" or as a template). See also XLSX.openxlsx and XLSX.opentemplate.

Experimental

This function is experimental is not guaranteed to work with all XLSX files, especially those with complex features. However, cell formats, conditional formats and worksheet defined names should all copy OK. Please report any issues.

See also addsheet!, renamesheet!, deletesheet!, movesheet!

Examples

julia> f=XLSX.openxlsx("general.xlsx", mode="rw")
XLSXFile("C:\...\general.xlsx") containing 13 Worksheets
            sheetname size          range
-------------------------------------------------
              general 10x6          A1:F10
               table3 5x6           A2:F6
               table4 4x3           E12:G15
                table 12x8          A2:H13
               table2 5x3           A1:C5
                empty 1x1           A1:A1
               table5 6x1           C3:C8
               table6 8x2           B1:C8
               table7 7x2           B2:C8
               lookup 4x9           B2:J5
         header_error 3x4           B2:E4
       named_ranges_2 4x5           A1:E4
         named_ranges 14x6          A2:F15

julia> XLSX.copysheet!(f[4])
12×8 Worksheet: ["table (copy)"](A2:H13)

julia> f
XLSXFile("C:\...\general.xlsx") containing 14 Worksheets
            sheetname size          range
-------------------------------------------------
              general 10x6          A1:F10
               table3 5x6           A2:F6
               table4 4x3           E12:G15
                table 12x8          A2:H13
               table2 5x3           A1:C5
                empty 1x1           A1:A1
               table5 6x1           C3:C8
               table6 8x2           B1:C8
               table7 7x2           B2:C8
               lookup 4x9           B2:J5
         header_error 3x4           B2:E4
       named_ranges_2 4x5           A1:E4
         named_ranges 14x6          A2:F15
         table (copy) 12x8          A2:H13
source
XLSX.deletesheet! — Function
deletesheet!(ws::Worksheet) -> ::XLSXFile
deletesheet!(wb::Workbook, name::AbstractString) -> ::XLSXFile
deletesheet!(xf::XLSXFile, name::AbstractString) -> ::XLSXFile
deletesheet!(xf::XLSXFile, sheetId::Integer) -> ::XLSXFile

Delete the given worksheet, the worksheet with the given name or the worksheet with the given sheetId from its XLSXFile (sheetId is a 1-based integer representing the order in which worksheet tabs are displayed in Excel).

Caution

Cells in the other sheets that have references to the deleted sheet will fail when the sheet is deleted. The formulae are updated to contain a #REF! error in place of each sheetcell reference.

Defined names that refer to the deleted sheet are kept with the value "=#REF!", as in Excel. Names scoped to the deleted sheet are removed with it.

See also addsheet!, renamesheet!, copysheet!, movesheet!

Examples

julia> f = XLSX.opentemplate("general.xlsx")
XLSXFile("C:\...\general.xlsx") containing 13 Worksheets
            sheetname size          range
-------------------------------------------------
              general 10x6          A1:F10
               table3 5x6           A2:F6
               table4 4x3           E12:G15
                table 12x8          A2:H13
               table2 5x3           A1:C5
                empty 1x1           A1:A1        
               table5 6x1           C3:C8
               table6 8x2           B1:C8
               table7 7x2           B2:C8
               lookup 4x9           B2:J5
         header_error 3x4           B2:E4
       named_ranges_2 4x5           A1:E4
         named_ranges 14x6          A2:F15


julia> XLSX.deletesheet!(f[4])
XLSXFile("C:\...\general.xlsx") containing 12 Worksheets
            sheetname size          range
-------------------------------------------------
              general 10x6          A1:F10
               table3 5x6           A2:F6
               table4 4x3           E12:G15
               table2 5x3           A1:C5
                empty 1x1           A1:A1
               table5 6x1           C3:C8
               table6 8x2           B1:C8
               table7 7x2           B2:C8
               lookup 4x9           B2:J5
         header_error 3x4           B2:E4
       named_ranges_2 4x5           A1:E4
         named_ranges 14x6          A2:F15


julia> XLSX.deletesheet!(f, "table5")
XLSXFile("C:\...\general.xlsx") containing 11 Worksheets
            sheetname size          range
-------------------------------------------------
              general 10x6          A1:F10
               table3 5x6           A2:F6
               table4 4x3           E12:G15
               table2 5x3           A1:C5
                empty 1x1           A1:A1
               table6 8x2           B1:C8
               table7 7x2           B2:C8
               lookup 4x9           B2:J5
         header_error 3x4           B2:E4
       named_ranges_2 4x5           A1:E4
         named_ranges 14x6          A2:F15


julia> XLSX.deletesheet!(f, 1)
XLSXFile("C:\...\general.xlsx") containing 10 Worksheets
            sheetname size          range
-------------------------------------------------
               table3 5x6           A2:F6
               table4 4x3           E12:G15
               table2 5x3           A1:C5
                empty 1x1           A1:A1
               table6 8x2           B1:C8
               table7 7x2           B2:C8
               lookup 4x9           B2:J5
         header_error 3x4           B2:E4
       named_ranges_2 4x5           A1:E4
         named_ranges 14x6          A2:F15
source
XLSX.movesheet! — Function
movesheet!(ws::Worksheet; before=nothing, after=nothing) -> ::XLSXFile
movesheet!(wb::Workbook, sheet; before=nothing, after=nothing) -> ::XLSXFile
movesheet!(xf::XLSXFile, sheet; before=nothing, after=nothing) -> ::XLSXFile

Move a sheet to a new place in the workbook's tab order, immediately before or after another sheet. Give exactly one of before or after.

The sheet to move and the sheet to place it next to may each be given as a Worksheet, a sheet name or a 1-based tab position (as before the move). To move a sheet to the start use before=1, and to the end use after=sheetcount(xf).

Nothing in the workbook needs to be rewritten: formulas, charts and defined names refer to sheets by name, and names scoped to a sheet stay with that sheet. The active tab stays on the same sheet.

Caution

As in Excel, a 3D reference such as =SUM(Jan:Mar!A1) covers whichever sheets lie between Jan and Mar in tab order, so moving a sheet into or out of that span changes the result.

See also addsheet!, renamesheet!, copysheet!, deletesheet!

Examples

julia> xf = XLSX.newxlsx("A"); XLSX.addsheet!(xf, "B"); XLSX.addsheet!(xf, "C");

julia> XLSX.movesheet!(xf, "C"; before="A");

julia> XLSX.sheetnames(xf)
3-element Vector{String}:
 "C"
 "A"
 "B"

julia> XLSX.movesheet!(xf[1]; after=XLSX.sheetcount(xf));

julia> XLSX.sheetnames(xf)
3-element Vector{String}:
 "A"
 "B"
 "C"
source

Sheet visibility and tab colour

Guide: Hiding a sheet, Tab colour.

XLSX.setSheetVisibility — Function
setSheetVisibility(ws::Worksheet, visibility::Symbol)

Show or hide a sheet's tab. visibility is one of

  • :visible: the tab is shown;
  • :hidden: the tab is hidden, and can be shown again from Excel's Unhide menu;
  • :veryHidden: the tab is hidden and not listed in the Unhide menu. It can be shown again only from VBA, or with this function.

A workbook must keep at least one visible sheet, so hiding the last one is an error. Hiding the sheet the workbook opens on makes the first visible sheet the one it opens on instead.

Works on worksheets and chartsheets. The file must be open for writing (mode="rw").

Examples

julia> XLSX.setSheetVisibility(xf["Lookups"], :hidden)

julia> XLSX.setSheetVisibility(xf["Lookups"], :visible)

See also getSheetVisibility.

source
XLSX.setTabColor — Function
setTabColor(ws::Worksheet, color)

Colour a sheet's tab. The color can be a hex value ("FF0000", "#FF0000" or 8-digit "FFFF0000", whose first two digits, transparency, Excel ignores), the name of a Colors.jl color as a String or Symbol, a Colors.jl Colorant, or a theme color ("accent1", :tx1 or a XLSX.SchemeColor). See Specifying colors.

Works on worksheets and chartsheets. The file must be open for writing (mode="rw").

Examples

julia> XLSX.setTabColor(sheet, "FF0000")

julia> XLSX.setTabColor(sheet, :accent2)

See also getTabColor and removeTabColor.

source
XLSX.getTabColor — Function
getTabColor(ws::Worksheet) -> Union{Nothing, String}

The colour of a sheet's tab as an "FFRRGGBB" hex string, or nothing if it has none. A theme colour is given as the colour it has in the workbook's theme.

See also setTabColor.

source
XLSX.removeTabColor — Function
removeTabColor(ws::Worksheet) -> Bool

Remove a sheet's tab colour. Returns false if it had none.

The file must be open for writing (mode="rw").

source

Sheet protection

Guide: Protecting a sheet. Cell locking is set with XLSX.setCellProtection.

XLSX.protectSheet — Function
protectSheet(ws::Worksheet; password=nothing, allow...)

Protect a worksheet, as Excel's Review → Protect Sheet does, so that its locked cells can't be changed in Excel. Every cell is locked unless its format says otherwise.

password, if given, must be typed in Excel to unprotect the sheet. It is stored as Excel's legacy 16-bit hash, which Excel accepts but which is easily broken: sheet protection guards against mistakes, not against anyone determined to change the sheet. The password must be ASCII text of at most 15 characters, the most the legacy hash uses.

The other keywords say what a user may still do, as in Excel's dialog. Each is a Bool:

KeywordAllowsDefault
selectLockedCellsselecting locked cellstrue
selectUnlockedCellsselecting unlocked cellstrue
formatCellsformatting cellsfalse
formatColumnsformatting columnsfalse
formatRowsformatting rowsfalse
insertColumnsinserting columnsfalse
insertRowsinserting rowsfalse
insertHyperlinksinserting hyperlinksfalse
deleteColumnsdeleting columnsfalse
deleteRowsdeleting rowsfalse
sortsortingfalse
autoFilterusing AutoFilterfalse
pivotTablesusing PivotTablesfalse
objectsediting objects such as chartsfalse
scenariosediting scenariosfalse

Protecting a sheet that is already protected replaces its settings. Protection applies in Excel only: XLSX.jl reads and writes a protected sheet as any other.

The file must be open for writing (mode="rw").

Examples

julia> XLSX.protectSheet(sheet)

julia> XLSX.protectSheet(sheet; password="secret", sort=true, autoFilter=true)

See also unprotectSheet, isSheetProtected and getSheetProtection.

source
XLSX.unprotectSheet — Function
unprotectSheet(ws::Worksheet) -> Bool

Remove a worksheet's protection, whatever its password. Returns false if it wasn't protected.

The file must be open for writing (mode="rw").

source
XLSX.getSheetProtection — Function
getSheetProtection(ws::Worksheet) -> Union{Nothing, NamedTuple}

How a worksheet is protected, or nothing if it isn't. The NamedTuple has a field password, whether a password is needed to unprotect the sheet, and a Bool field for each thing a user may do, named as the keywords of protectSheet.

Examples

julia> p = XLSX.getSheetProtection(sheet);

julia> p.password, p.sort
(true, true)
source
XLSX.protectWorkbook — Function
protectWorkbook(xf::XLSXFile; password=nothing, structure=true, windows=false)

Protect a workbook's structure, as Excel's Review → Protect Workbook does, so that its sheets can't be added, deleted, moved, renamed, hidden or unhidden in Excel.

  • password, if given, must be typed in Excel to unprotect the workbook. As for protectSheet, it is stored as Excel's legacy hash, which Excel accepts but which is easily broken, and must be ASCII text of at most 15 characters.
  • structure: lock the sheets. The default is true.
  • windows: lock the size and position of the workbook's windows. Only Excel for Mac and older versions of Excel use this: Excel 365 for Windows neither shows nor applies it.

Protecting a workbook that is already protected replaces its settings. Protection applies in Excel only: XLSX.jl can still add, delete and rename sheets in a protected workbook.

The file must be open for writing (mode="rw").

Examples

julia> XLSX.protectWorkbook(xf)

julia> XLSX.protectWorkbook(xf; password="secret")

See also unprotectWorkbook, isWorkbookProtected and getWorkbookProtection.

source
XLSX.unprotectWorkbook — Function
unprotectWorkbook(xf::XLSXFile) -> Bool

Remove a workbook's protection, whatever its password. Returns false if it wasn't protected. Sheets keep their own protection: see unprotectSheet.

The file must be open for writing (mode="rw").

source
XLSX.getWorkbookProtection — Function
getWorkbookProtection(xf::XLSXFile) -> Union{Nothing, NamedTuple}

How a workbook is protected, or nothing if it isn't: a NamedTuple with Bool fields password (whether a password is needed to unprotect it), structure and windows, as the keywords of protectWorkbook.

Examples

julia> XLSX.getWorkbookProtection(xf)
(password = true, structure = true, windows = false)
source

Page setup and printing

Guide: Printing.

XLSX.setPageSetup — Function
setPageSetup(ws::Worksheet; orientation, paperSize, scale, fitToWidth, fitToHeight)

Set how a worksheet is printed, as Excel's Page Setup dialog does. Only the keywords given are changed.

  • orientation: :portrait or :landscape.
  • paperSize: one of :letter, :tabloid, :ledger, :legal, :executive, :A3, :A4, :A5, :B4, :B5, or Excel's number for any other size.
  • scale: print at this percentage of normal size, from 10 to 400.
  • fitToWidth, fitToHeight: shrink the sheet to fit this many pages wide and tall. 0 means as many as needed, and so does leaving one out: fitToWidth=1 alone fits the width to one page and lets the sheet run on to as many pages as it needs.

scale and fitting to pages are alternatives, as in Excel: giving one turns the other off.

The file must be open for writing (mode="rw").

Examples

julia> XLSX.setPageSetup(sheet; orientation=:landscape, paperSize=:A4, fitToWidth=1)

See also getPageSetup, setPageMargins, setPrintOptions, setPrintArea and setPrintTitles.

source
XLSX.getPageSetup — Function
getPageSetup(ws::Worksheet) -> NamedTuple

How a worksheet is printed: a NamedTuple with fields orientation, paperSize, scale, fitToWidth and fitToHeight, each nothing where the sheet doesn't set it. fitToWidth and fitToHeight are given only if the sheet is set to fit to pages, and scale only if it isn't. See setPageSetup.

source
XLSX.setPageMargins — Function
setPageMargins(ws::Worksheet; left, right, top, bottom, header, footer)

Set a worksheet's printed margins, in inches. header and footer are the distances of the header and footer from the edge of the page. Only the keywords given are changed; a sheet with no margins starts from Excel's defaults, left=0.7, right=0.7, top=0.75, bottom=0.75, header=0.3, footer=0.3.

The file must be open for writing (mode="rw").

Examples

julia> XLSX.setPageMargins(sheet; left=0.5, right=0.5)

See also getPageMargins.

source
XLSX.getPageMargins — Function
getPageMargins(ws::Worksheet) -> Union{Nothing, NamedTuple}

A worksheet's printed margins in inches, as a NamedTuple with fields left, right, top, bottom, header and footer, or nothing if the sheet doesn't set them. See setPageMargins.

source
XLSX.setPrintOptions — Function
setPrintOptions(ws::Worksheet; gridLines, headings, horizontalCentered, verticalCentered)

Choose what is printed with a worksheet. Each keyword is a Bool, and only those given are changed:

  • gridLines: print the cell gridlines;
  • headings: print the row and column headings (1, 2, 3... and A, B, C...);
  • horizontalCentered, verticalCentered: centre the sheet on the page.

The file must be open for writing (mode="rw").

See also getPrintOptions.

source
XLSX.getPrintOptions — Function
getPrintOptions(ws::Worksheet) -> NamedTuple

What is printed with a worksheet: a NamedTuple of Bools with fields gridLines, headings, horizontalCentered and verticalCentered. See setPrintOptions.

source
XLSX.setPrintArea — Function
setPrintArea(ws::Worksheet, rng)

Print only the cells in rng, as Excel's Page Layout → Print Area does. rng is a cell range ("A1:F40"), several separated by commas ("A1:F40,H1:K10", each printed on its own pages), or a defined name. It replaces any print area the sheet has.

Excel keeps the print area as a name scoped to the sheet, _xlnm.Print_Area, which is kept up to date as sheets are renamed, copied and deleted.

The file must be open for writing (mode="rw").

See also getPrintArea and removePrintArea.

source
XLSX.getPrintArea — Function
getPrintArea(ws::Worksheet) -> Union{Nothing, CellRange, NonContiguousRange, String}

A worksheet's print area: a CellRange, a NonContiguousRange of several, or nothing if it has none. A print area Excel wrote in another form, such as whole columns, is given as its text. See setPrintArea.

source
XLSX.removePrintArea — Function
removePrintArea(ws::Worksheet) -> Bool

Remove a worksheet's print area, so that the whole sheet is printed. Returns false if it had none.

The file must be open for writing (mode="rw").

source
XLSX.setPrintTitles — Function
setPrintTitles(ws::Worksheet; rows=nothing, cols=nothing)

Repeat rows at the top of every printed page, and columns at the left, as Excel's Page Layout → Print Titles does. rows is a row number, a range of rows (1:2) or a string ("1:2"); cols is a column number, a range or a string ("A", "A:B"). Give either or both; they replace any titles the sheet has.

Excel keeps the titles as a name scoped to the sheet, _xlnm.Print_Titles.

The file must be open for writing (mode="rw").

Examples

julia> XLSX.setPrintTitles(sheet; rows=1)              # repeat the header row

julia> XLSX.setPrintTitles(sheet; rows=1:2, cols="A")

See also getPrintTitles and removePrintTitles.

source
XLSX.getPrintTitles — Function
getPrintTitles(ws::Worksheet) -> Union{Nothing, NamedTuple}

The rows and columns repeated on every printed page, as a NamedTuple (rows, cols) of UnitRanges (each nothing if not set), or nothing if the sheet has no print titles. See setPrintTitles.

source
XLSX.removePrintTitles — Function
removePrintTitles(ws::Worksheet) -> Bool

Stop repeating rows and columns on every printed page. Returns false if the sheet had no print titles.

The file must be open for writing (mode="rw").

source
XLSX.setHeaderFooter — Function
setHeaderFooter(ws::Worksheet; header, footer, firstHeader, firstFooter, evenHeader, evenFooter,
                differentFirst, differentOddEven, scaleWithDoc, alignWithMargins)

Set the headers and footers printed on a worksheet's pages, as Excel's Page Setup → Header/Footer does. Only the keywords given are changed.

header and footer are printed on every page. Each is a NamedTuple of up to three sections, left, center and right, or a single string, which is centred:

XLSX.setHeaderFooter(sheet; header=(left="Sales", right="Page &P of &N"), footer="&F")

Each new value replaces the whole of that header or footer, and an empty string "" removes it.

The text may contain Excel's codes, which Excel replaces when it prints. The commonest are &P for the page number, &N for the number of pages, &D and &T for the date and time, &F and &Z for the file's name and folder, and &A for the sheet's name. headerFooterField gives these by name, and headerFooterFont gives the codes that change the font. Write && for an ampersand.

  • firstHeader, firstFooter: printed on the first page instead. Giving either, even as "", turns differentFirst on.
  • evenHeader, evenFooter: printed on even pages, while header and footer are printed on odd ones. Giving either, even as "", turns differentOddEven on.
  • differentFirst, differentOddEven: whether the first page, and even pages, have their own headers and footers, which are blank where none is given. Set them to false to print header and footer on those pages again.
  • scaleWithDoc: scale the headers and footers with the sheet when it is printed at another size. The default is true.
  • alignWithMargins: align the headers and footers with the page margins. The default is true.

A header or footer holds at most 255 characters, counting its codes, as in Excel. Pictures in headers and footers aren't supported.

The file must be open for writing (mode="rw").

Examples

julia> XLSX.setHeaderFooter(sheet; header=(center = XLSX.headerFooterFont(bold=true, size=14) * "Quarterly report",),
                                   footer=(left="&F", right="Page &P of &N"))

julia> XLSX.setHeaderFooter(sheet; firstHeader="")   # no header on the first page

See also getHeaderFooter, removeHeaderFooter and setPageMargins, which sets the distance of headers and footers from the edge of the page.

source
XLSX.getHeaderFooter — Function
getHeaderFooter(ws::Worksheet) -> Union{Nothing, NamedTuple}

A worksheet's printed headers and footers, or nothing if it has none. The result is a NamedTuple with fields:

  • header, footer, evenHeader, evenFooter, firstHeader and firstFooter: each a NamedTuple (left, center, right) of the sections' text, with Excel's codes such as &P as they are, or nothing if the sheet has no such header or footer. An empty section is nothing.
  • differentOddEven, differentFirst, scaleWithDoc and alignWithMargins: the options described in setHeaderFooter.

Each header and footer can be given back to setHeaderFooter as it is.

Examples

julia> XLSX.getHeaderFooter(sheet).footer
(left = "&F", center = nothing, right = "Page &P of &N")
source
XLSX.removeHeaderFooter — Function
removeHeaderFooter(ws::Worksheet) -> Bool

Remove all of a worksheet's headers and footers and their options. Returns false if it had none.

The file must be open for writing (mode="rw").

source
XLSX.headerFooterField — Function
headerFooterField(field::Symbol) -> String

The code Excel replaces with field when it prints a header or footer:

fieldCodePrinted as
:page&Pthe page number
:pages&Nthe number of pages
:date&Dthe date it is printed
:time&Tthe time it is printed
:file&Fthe workbook's file name
:path&Zthe folder the workbook is in
:sheet&Athe sheet's name

Examples

julia> "Page " * XLSX.headerFooterField(:page) * " of " * XLSX.headerFooterField(:pages)
"Page &P of &N"

See also setHeaderFooter and headerFooterFont.

source
XLSX.headerFooterFont — Function
headerFooterFont(; name, bold, italic, under, strike, size, color, vertAlign) -> String

The codes that change the font of the text that follows them in a header or footer. The keywords are those of setFont:

  • name::String: the font's name. Without it, the font is unchanged.
  • bold::Bool, italic::Bool: make the text bold or italic.
  • under::String: "single" or "double" to underline the text.
  • strike::Bool: strike through the text.
  • size::Integer: the font's size in points, from 1 to 409.
  • color: the text's colour, which can be a hex value ("FF0000", "#FF0000" or 8-digit "FFFF0000", whose

first two digits, transparency, Excel ignores), the name of a Colors.jl color as a String or Symbol, a Colors.jl Colorant, or a theme color ("accent1", :tx1 or a XLSX.SchemeColor). See Specifying colors.

  • vertAlign::String: "superscript" or "subscript".

The font applies to the rest of the section, or until another font is given. If the text after a size starts with a digit, separate them with a space, or Excel reads the digits as part of the size.

Examples

julia> XLSX.headerFooterFont(name="Arial", bold=true, size=14)
"&\"Arial,Bold\"&14"

julia> XLSX.headerFooterFont(italic=true, color="red")
"&\"-,Italic\"&KFF0000"

See also setHeaderFooter and headerFooterField.

source

Document properties

Guide: Document properties.

XLSX.setDocumentProperties — Function
setDocumentProperties(xf::XLSXFile; title, subject, creator, keywords, description,
                      lastModifiedBy, category, contentStatus, created, modified,
                      company, manager)

Set a workbook's document properties, as Excel's File → Info → Properties does. Only the keywords given are changed, and an empty string "" removes a property.

KeywordIn Excel
titleTitle
subjectSubject
creatorAuthor
keywordsTags
descriptionComments
lastModifiedByLast Modified By
categoryCategories
contentStatusStatus
createdCreated
modifiedLast Modified
companyCompany
managerManager

created and modified are a DateTime or Date in UTC (Coordinated Universal Time), as the file keeps them; Excel shows them in local time. The others are strings.

XLSX.jl doesn't change modified or lastModifiedBy when it saves a file; Excel does.

The file must be open for writing (mode="rw").

Examples

julia> XLSX.setDocumentProperties(xf; title="Quarterly sales", creator="Finance team", keywords="sales; Q3")

julia> XLSX.setDocumentProperties(xf; created=DateTime(2026, 1, 15, 9, 30))

See also getDocumentProperties and setCustomProperty.

source
XLSX.getDocumentProperties — Function
getDocumentProperties(xf::XLSXFile) -> NamedTuple

A workbook's document properties: a NamedTuple with the fields described in setDocumentProperties, each nothing if the workbook doesn't have it. created and modified are DateTimes in UTC, or the text as written if it isn't a date.

Works on files opened for reading only.

Examples

julia> XLSX.getDocumentProperties(xf).title
"Quarterly sales"
source
XLSX.setCustomProperty — Function
setCustomProperty(xf::XLSXFile, name::AbstractString, value)

Set the custom document property name to value, as Excel's File → Info → Properties → Advanced Properties → Custom does, adding it if the workbook doesn't have it. A property of the same name, ignoring case as Excel does, is replaced.

value is a string, a whole number, a real number, a Bool, or a Date or DateTime in UTC. A whole number Excel can't keep as one (beyond ±2,147,483,647) is kept as a real number.

Other custom properties are kept as they are, including ones other programs write, such as sensitivity labels.

The file must be open for writing (mode="rw").

Examples

julia> XLSX.setCustomProperty(xf, "Project", "Apollo")

julia> XLSX.setCustomProperty(xf, "Approved", true)

See also getCustomProperty, getCustomProperties and deleteCustomProperty.

source
XLSX.getCustomProperty — Function
getCustomProperty(xf::XLSXFile, name::AbstractString)

The value of the custom document property name, ignoring case, or nothing if the workbook doesn't have it. See getCustomProperties for the types of the values.

Works on files opened for reading only.

source
XLSX.getCustomProperties — Function
getCustomProperties(xf::XLSXFile) -> OrderedDict{String,Any}

All of a workbook's custom document properties, in the order the file keeps them, by name. Each value is a String, an Int, a Float64, a Bool or a DateTime (in UTC), as the property is typed, and a list (which other programs can write) is a Vector of these. A value of another type, such as currency, is given as its text.

Works on files opened for reading only.

Examples

julia> XLSX.getCustomProperties(xf)
OrderedCollections.OrderedDict{String, Any} with 2 entries:
  "Project"  => "Apollo"
  "Approved" => true
source
XLSX.deleteCustomProperty — Function
deleteCustomProperty(xf::XLSXFile, name::AbstractString) -> Bool

Delete the custom document property name, ignoring case. Returns false if the workbook doesn't have it.

The file must be open for writing (mode="rw").

source

Errors

XLSX.XLSXError — Type
XLSXError(msg::String)

The exception type XLSX.jl throws for every error it raises itself: a malformed or unsupported file, an argument that names something the workbook does not contain, a value outside what the format allows, or an operation the file's mode does not permit.

One type covers all of them, so e isa XLSXError in a catch distinguishes an error the package raised from one escaping out of Julia or a dependency. The message says what went wrong and, where it helps, what was found instead.

Fields

  • msg::String — the message, printed after XLSXError:.

Example

julia> XLSX.Charts.getChartAxis(c, 99)
ERROR: XLSXError: Chart `chart1` has no axis with axId 99. Found: 1, 2.
source