readstat-rs

Read, inspect, and convert SAS binary (.sas7bdat) files — from Rust code, the command line, or the browser. Converts to CSV, Parquet, Feather, and NDJSON using Apache Arrow.

The original use case was a command-line tool for converting SAS files, but the project has since expanded into a workspace of crates that can be used as a Rust library, a CLI, or compiled to WebAssembly for browser and JavaScript runtimes.

:clapper: The demo above is generated from scripts/demo.sh and recorded with scripts/record-demo.sh.

🔑 Dependencies

The command-line tool is developed in Rust and is only possible due to the following excellent projects:

• The ReadStat C library developed by Evan Miller
• The arrow Rust crate developed by the Apache Arrow community

The ReadStat library is used to parse and read sas7bdat files, and the arrow crate is used to convert the read sas7bdat data into the Arrow memory format. Once in the Arrow memory format, the data can be written to other file formats.

💡 Note: The ReadStat C library supports SAS, SPSS, and Stata file formats. The readstat-sys crate exposes the full ReadStat API — all 125 functions across all formats. However, the higher-level crates (readstat, readstat-cli, readstat-wasm) only implement support for SAS .sas7bdat files. SPSS and Stata support is a possible future addition, but is not planned at this time — if you need those formats today, the readstat-sys bindings already expose the complete SPSS (.sav, .zsav, .por) and Stata (.dta) C API to build on.

🚀 CLI Quickstart

Convert the first 50,000 rows of example.sas7bdat to the file example.parquet, overwriting the file if it already exists. File output uses bounded parallel writing by default while preserving row order.

readstat convert /some/dir/to/example.sas7bdat --output /some/dir/to/example.parquet --rows 50000 --overwrite

📦 CLI Install

From Cargo

If you have Rust installed, the easiest way to install is via cargo:

cargo install readstat-cli

The default CLI omits the substantially larger DataFusion SQL engine. To add the --sql and --sql-file options, install with the opt-in sql feature:

cargo install readstat-cli --features sql

Download a Release

[Mostly] static binaries for Linux, macOS, and Windows may be found at the Releases page. Release binaries use the CLI’s lean default feature set and do not include SQL.

Setup

Move the readstat binary to a known directory and add the binary to the user’s PATH.

Linux & macOS

Ensure the path to readstat is added to the appropriate shell configuration file.

Windows

For Windows users, path configuration may be found within the Environment Variables menu. Executing the following from the command line opens the Environment Variables menu for the current user.

rundll32.exe sysdm.cpl,EditEnvironmentVariables

Alternatively, update the user-level PATH in PowerShell (replace C:\path\to\readstat with the actual directory):

$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$currentPath;C:\path\to\readstat", "User")

After running the above, restart your terminal for the change to take effect.

Run

Run the binary.

readstat --help

⚙️ CLI Usage

The binary is invoked using subcommands:

• metadata → writes file and variable metadata to standard out or JSON
• preview → writes the first N rows of parsed data as csv to standard out
• convert → converts data to CSV, Feather, NDJSON, or Parquet; the output extension selects the format, or omitted output writes CSV to stdout

Column metadata — labels, SAS format strings, and storage widths — is preserved in Parquet and Feather output as Arrow field metadata. See docs/TECHNICAL.md for details.

For a one-page visual overview see the CLI Cheatsheet (rendered). For the full CLI reference — including column selection, parallelism, memory considerations, SQL queries, reader modes, and debug options — see docs/USAGE.md.

For library, API server, and WebAssembly usage, see Examples below.

🛠️ Build from Source

Clone the repository (with submodules), install platform-specific developer tools, and run cargo build. Platform-specific instructions for Linux, macOS, and Windows are in docs/BUILDING.md.

:information_source: Minimum Supported Rust Version (MSRV): 1.88 (let-chains; Rust edition 2024). All published crates set rust-version = "1.88".

💻 Platform Support

📚 Documentation

:notebook: Online Book (GitHub Pages) — full reference including installation, CLI usage, architecture, technical details, and memory safety.

🧩 Workspace Crates

For full architectural details, see docs/ARCHITECTURE.md.

💡 Examples

The examples/ directory contains runnable demos showing different ways to use readstat-rs.

To use readstat as a library in your own Rust project, add the readstat crate as a dependency.

SQL support (synchronous and asynchronous DataFusion APIs) and all four output writers are enabled by default. Disable defaults only when building a deliberately smaller library.

⚖️ License

readstat-rs is licensed under the MIT License.

:information_source: On Windows the readstat-iconv-sys crate compiles and statically links the vendored win-iconv, which is placed in the public domain and imposes no obligations — Windows binaries are MIT like everything else. Linux and macOS builds use the system iconv.

🔗 Resources

The following have been incredibly helpful while developing!

• How to not RiiR
• Making a *-sys crate
• Rust Closures in FFI
• Rust FFI: Microsoft Flight Simulator SDK
  • Part 1
  • Part 2
• Stack Overflow answers by Jake Goulding
• ReadStat pull request to add MSVC/Windows support
• jamovi-readstat appveyor.yml file to build ReadStat on Windows
• Arrow documentation for utilizing ArrayBuilders