Save a workbook to file

Save a workbook to file

Usage

wb_save(
  wb,
  file = NULL,
  overwrite = TRUE,
  path = NULL,
  flush = FALSE,
  use_modification_date = FALSE
)

Arguments

wb

A wbWorkbook object to write to file

file

A path to save the workbook to

overwrite

If FALSE, will not overwrite when file already exists.

path

Deprecated argument. Please use file in new code.

flush

Experimental, streams the worksheet file to disk

use_modification_date

If TRUE, sets timestamps of files within the resulting xlsx to the datetime_modified property of wb.

Value

the wbWorkbook object, invisibly

Details

When saving a wbWorkbook to a file, memory usage may spike depending on the worksheet size. This happens because the entire XML structure is created in memory before writing to disk. The memory required depends on worksheet size, as XML files consist of character data and include additional overhead for validity checks.

The flush argument streams worksheet XML data directly to disk, avoiding the need to build the full XML tree in memory. This reduces memory usage but skips some XML validity checks. It also bypasses the pugixml functions that openxlsx2 uses, omitting certain preliminary sanity checks before writing. As the name suggests, the output is simply flushed to disk.

By default, the utils::zip() function is used to create output files. This requires a working zip utility to be available on the system. A valid zip program must be found either via Sys.which("zip") or through the R_ZIPCMD environment variable.

On Windows, a suitable zip tool is typically provided by Rtools. If R_ZIPCMD is not set, openxlsx2 will automatically use the first detected Rtools installation. If no zip utility is available, bsdtar can be used as an alternative. On Windows this is shipped as tar.exe; on Mac and Linux it is usually available as bsdtar (often requiring installation of the archive package).

A further fallback—primarily for older Windows systems—is to point R_ZIPCMD to 7z.exe. This approach has not been extensively tested and is not reliable with 7-Zip on macOS.

As an additional fallback, the zip package can be used. It is no longer listed in Imports and must be installed separately if needed.

The use_modification_date argument causes the resulting xlsx file to be cryptographically deterministic when given the same wbWorkbook object and when using the same zipping utility, which may prove to be convenient if the file is tracked within a Git repository.

See also

Other workbook wrappers: base_font-wb, col_widths-wb, creators-wb, grouping-wb, row_heights-wb, wb_add_chartsheet(), wb_add_data(), wb_add_data_table(), wb_add_formula(), wb_add_hyperlink(), wb_add_pivot_table(), wb_add_slicer(), wb_add_worksheet(), wb_base_colors, wb_clone_worksheet(), wb_copy_cells(), wb_freeze_pane(), wb_merge_cells(), wb_set_last_modified_by(), wb_workbook()

Examples

## Create a new workbook and add a worksheet
wb <- wb_workbook("Creator of workbook")
wb$add_worksheet(sheet = "My first worksheet")

## Save workbook to working directory
# \donttest{
wb_save(wb, file = temp_xlsx(), overwrite = TRUE)

## do not try to find zip in Rtools
# options("openxlsx2.no_maybe_zip" = TRUE)

## do not use utils::zip, will try to use bsdtar
# options("openxlsx2.no_utils_zip" = TRUE)

## if the above is set as well, do not use bsdtar
# options("openxlsx2.no_bsdtar" = TRUE)

## use 7zip on Windows this works, on Mac not
# Sys.setenv("R_ZIPCMD" = "C:\Program Files\7-Zip\7z.exe")

# if the last one is left blank the fallback is zip::zip
openxlsx2::write_xlsx(x = cars, temp_xlsx())
# }