qs qsave() in R: Save R Objects Fast to Disk

The qs qsave() function in R serializes any R object to a compressed binary file, running several times faster than base R's saveRDS() while producing smaller files.

qsave(df, "df.qs")                      # default, high compression
qsave(df, "df.qs", preset = "fast")     # speed over file size
qsave(df, "df.qs", preset = "archive")  # smallest file
qsave(model, "model.qs", nthreads = 4)  # parallel write
qread("df.qs")                          # read it back
qsavem(a, b, file = "vars.qs")          # save several objects
qs::qsave(x, "x.qs")                    # call without attaching

What qsave() does

qsave() writes any in-memory R object to a single compressed file on disk. It is the workhorse of the qs package, designed to serialize objects far faster than saveRDS() while keeping files small. You pass an object and a path, and qsave() writes the file and returns it invisibly.

Unlike format-specific writers such as write_csv() or write_fst(), qsave() is not limited to data frames. It serializes lists, fitted models, nested structures, S4 objects, and anything else R can hold in memory. The companion reader qread() restores the object exactly as it was, with every attribute, class, and environment intact.

The speed comes from two design choices. qs uses modern compression libraries (zstd and lz4) that are quicker than the gzip compression in saveRDS(), and it can spread that work across several CPU cores.

qsave() syntax and arguments

A qsave() call needs an object, a file path, and an optional compression preset. Everything else has a sensible default, so most real code passes just two arguments.

The full signature exposes the compression controls. The preset argument is the one you reach for most often, because it bundles the algorithm and its level into a single named choice.

The default "high" preset uses zstd compression at a moderate level, a good balance for most work. The "fast" preset switches to lz4 for the quickest write at the cost of a larger file, while "archive" pushes zstd hard for the smallest file. Set preset = "custom" only when you want to combine an algorithm and compress_level by hand.

Saving objects with qsave(): four common cases

Round-trip a data frame

The core pattern is qsave() to write and qread() to read. A correct round-trip returns an object identical to the original.

The identical() check returns TRUE because qsave() preserves column types, row names, and attributes. This is the everyday use: write an object after an expensive step, then read it back instead of recomputing.

Trade file size against speed with presets

Presets tune the speed-versus-size balance without touching algorithm internals. The "fast" preset writes quickly but leaves larger files, while "archive" compresses hardest.

The "fast" file is larger because lz4 prioritizes write speed over compression ratio. For a cache you rewrite often that is the right call; for an object you save once and keep, "archive" is the better trade.

Speed up large saves with multiple threads

The nthreads argument splits compression across CPU cores. For large objects this is the single biggest speed lever qsave() offers, and it applies to qread() too.

Compression parallelizes cleanly, so a four-thread write finishes far sooner than the single-threaded default. Match nthreads to the cores you can spare; values beyond your physical core count give no further gain.

Save several objects in one file

qsavem() saves multiple named objects together, and qload() restores them. This mirrors base R's save() and load() pair but with qs speed.

After qload() the objects reappear under their original names, so there is no assignment step. Use qsavem() when a checkpoint involves several related objects, such as a model plus its training data.

qsave() vs saveRDS() and other formats

qsave() wins on speed for any object type, but a .qs file is not portable. The table below shows where each writer fits.

Reach for qsave() when speed matters and the reader is another R session with qs installed. Fall back to saveRDS() when the file must open anywhere without extra packages, and pick write_csv() or write_parquet() when tools outside R need the data.

Common pitfalls

Sending a .qs file to a colleague without qs installed. The file is unreadable anywhere the qs package is missing. For data you must share widely, write a .csv or .rds file instead, or have the recipient run install.packages("qs") first.

Passing a connection instead of a path. Unlike saveRDS(), qsave() expects a plain character file path, not a connection object. Wrapping the path in gzfile() fails because qs manages compression itself.

Leaving nthreads at 1 for large objects. The default is single-threaded, so a multi-gigabyte object compresses slower than it needs to. Set nthreads to match the cores you can spare for an easy win.

Try it yourself

Related qs and data import functions

These functions cover the rest of the fast serialization workflow:

• readr write_rds() writes .rds files with a tidyverse-friendly interface.
• readr read_rds() reads .rds files back into R.
• fst write_fst() stores data frames with fast random-access reads.
• arrow write_parquet() saves data frames in the portable Parquet format.
• qread() is the qs reader that restores any object written by qsave().

FAQ

Is qsave() faster than saveRDS()?

Yes. For most objects qsave() writes and reads several times faster than saveRDS(), and the gap widens for large data because qsave() can use multiple threads. It also tends to produce smaller files at the default "high" preset. The trade-off is that the qs package must be installed to open the file, whereas .rds files work in any base R session.

What file extension should qs files use?

By convention qs files use the .qs extension, as in qsave(x, "results.qs"). The extension is not enforced, so a file saved under any name still reads correctly through qread(). Sticking to .qs keeps your project readable and signals the format to collaborators and to scripts that scan directories for cached output.

Can qsave() save a fitted model?

Yes. qsave() serializes any R object, including lm(), glm(), randomForest, and other model objects, together with their attributes and environments. Use qsave(model, "model.qs") and restore it with qread(). This makes qsave() a fast way to cache trained models between sessions so you do not re-fit them on every run.

Should I use qs or qs2 for a new project?

The classic qs package and its qsave() function remain fully supported and are a safe choice today. The newer qs2 package offers an updated on-disk format through qs_save() and is worth considering for new projects that prioritize a stable long-term format. For everyday caching inside an active project, either package works well.

For the official argument reference, see the qs package documentation.