pyreadstat

library1.3.6pypypi✓ verified 24d ago

Pyreadstat is a Python library that allows reading and writing SAS (.sas7bdat, .xpt), SPSS (.sav, .zsav), and Stata (.dta) files into/from pandas and polars data frames. It is currently at version 1.3.3 and maintains an active, though irregular, release cadence to adapt to new pandas/polars versions and add features.

data serialization

pip install pyreadstat

github ↗package ↗

INSTALL

IMPORT

SIG · PYREADSTAT

pyreadstat

datapythonv1.3.6

Install

3.9s avg

Import

430ms

Disk

100MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.6 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 4.1s

py 3.11

✕ build_error

✓ 3.9s

py 3.12

✕ build_error

✓ 3.8s

py 3.13

✕ build_error

✓ 3.85s

py 3.9

✕ build_error

100MB installed

● package 100MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pyreadstat

✓ import pyreadstat

This quickstart demonstrates how to import pyreadstat, write a simple pandas DataFrame to a SAS .sas7bdat file, and then read it back, illustrating basic data and metadata retrieval. The same `read_*` and `write_*` patterns apply to SPSS and Stata files.

import pyreadstat import pandas as pd import os # Example: Create a dummy SAS file for reading and writing data = {'col1': [1, 2, 3], 'col2': ['A', 'B', 'C']} df_to_write = pd.DataFrame(data) output_file = 'test_sas_file.sas7bdat' # Write a dummy SAS file try: pyreadstat.write_sas7bdat(df_to_write, output_file) print(f"Dummy SAS file '{output_file}' created successfully.") # Read the SAS file df_read, meta = pyreadstat.read_sas7bdat(output_file) print("\nDataFrame read from file:") print(df_read) print("\nMetadata read from file:") print(f"Column Names: {meta.column_names}") print(f"Column Labels: {meta.column_labels}") print(f"Table Name: {meta.table_name}") except Exception as e: print(f"An error occurred: {e}") finally: if os.path.exists(output_file): os.remove(output_file) print(f"Cleaned up '{output_file}'.")

Debug

Known issues

breakingOlder versions of pyreadstat (prior to 1.3.3) may not be compatible with pandas 3.0 due to API changes in pandas. This can lead to errors when reading or writing dataframes.

fix

Upgrade pyreadstat to version 1.3.3 or newer to ensure compatibility with pandas 3.0. If you cannot upgrade pyreadstat, consider pinning your pandas version to `<3.0`.

affects: <1.3.3

gotchaHandling character encodings in statistical files (SAS, SPSS, Stata) can be complex. If you encounter encoding errors or corrupted text, explicitly specify the correct encoding when reading files.

fix

Use the `encoding` parameter in `read_sas7bdat()`, `read_sav()`, or `read_dta()`. Common encodings include 'latin-1', 'cp1252', 'utf-8'. Example: `pyreadstat.read_sas7bdat('file.sas7bdat', encoding='latin-1')`.

affects: All versions

gotchaReading very large statistical files can consume significant memory, potentially leading to `MemoryError` as `pyreadstat` loads the entire file into memory. This is particularly relevant for files with millions of rows or numerous columns.

fix

Ensure your system has sufficient RAM to accommodate the file size. For extremely large files, consider preprocessing them with other tools (e.g., SAS/SPSS/Stata itself) to extract subsets, or convert them to more memory-efficient formats (like Parquet or Feather) before processing with Python if only specific columns/rows are needed.

affects: All versions

gotchaSAS time variables are often stored as numeric values representing seconds or days since a reference date. pyreadstat attempts to convert these, but specific formats might require custom handling or the `sas_time_is_datetime_format` parameter.

fix

If SAS date/time variables are not parsed correctly, inspect the metadata (`meta.variable_formats`) and consider passing `sas_time_is_datetime_format=True` to `read_sas7bdat` if the SAS file explicitly stores datetime types. Otherwise, manual conversion might be necessary post-read.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pyreadstat'

The `pyreadstat` library has not been installed in the Python environment being used.

fix

Install the library using pip: `pip install pyreadstat`

PyreadstatError: There was an error reading the file. Problem with the file encoding.

The statistical file uses an encoding that `pyreadstat` did not correctly infer or cannot handle with default settings.

fix

Explicitly specify the correct encoding (e.g., `'latin1'`, `'cp1252'`, `'utf-8'`) using the `encoding` parameter in the `read_sas`, `read_spss`, or `read_stata` function.

FileNotFoundError: [Errno 2] No such file or directory: 'your_file.sav'

The specified file path is incorrect, the file does not exist at that location, or the program lacks necessary read permissions.

fix

Verify the exact file path and name, ensure the file exists at the specified location, and check that the user running the script has appropriate read permissions for the file.

error: Microsoft Visual C++ 14.0 or greater is required.

On Windows, `pyreadstat` depends on compiled C/C++ code, and the necessary Visual C++ Build Tools are not installed or configured, which are required for pip to compile the package.

fix

Download and install the 'Build Tools for Visual Studio' from Microsoft's website, ensuring that the 'Desktop development with C++' workload is selected during installation.

Upgrade

Version history

1.3.6latest on PyPI · released Aug 12, 2026

Audit

Dependencies

pandasrequiredCore dependency for DataFrame operations.

narwhalsrequiredCore dependency, provides a common API for DataFrame operations.

polarsoptionalOptional dependency for Polars DataFrame support.

Agent activity

32 hits · last 30 days

node

Resources

githubhttps://github.com/Roche/pyreadstat ↗

packagehttps://pypi.org/project/pyreadstat/ ↗