.. Licensed to the Apache Software Foundation (ASF) under one .. or more contributor license agreements. See the NOTICE file .. distributed with this work for additional information .. regarding copyright ownership. The ASF licenses this file .. to you under the Apache License, Version 2.0 (the .. "License"); you may not use this file except in compliance .. with the License. You may obtain a copy of the License at

.. http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing, .. software distributed under the License is distributed on an .. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY .. KIND, either express or implied. See the License for the .. specific language governing permissions and limitations .. under the License.

.. currentmodule:: pyarrow

.. _feather:

Feather File Format

Feather is a portable file format for storing Arrow tables or data frames (from languages like Python or R) that utilizes the :ref:Arrow IPC format <ipc> internally. Feather was created early in the Arrow project as a proof of concept for fast, language-agnostic data frame storage for Python (pandas) and R. There are two file format versions for Feather:

• Version 2 (V2), the default version, which is exactly represented as the Arrow IPC file format on disk. V2 files support storing all Arrow data types as well as compression with LZ4 or ZSTD. V2 was first made available in Apache Arrow 0.17.0.
• Version 1 (V1), a legacy version available starting in 2016, replaced by V2. V1 files are distinct from Arrow IPC files and lack many features, such as the ability to store all Arrow data types. V1 files also lack compression support. We intend to maintain read support for V1 for the foreseeable future.

The pyarrow.feather module contains the read and write functions for the format. :func:~pyarrow.feather.write_feather accepts either a :class:~pyarrow.Table or pandas.DataFrame object:

.. code-block:: python

import pyarrow.feather as feather feather.write_feather(df, '/path/to/file')

:func:~pyarrow.feather.read_feather reads a Feather file as a pandas.DataFrame. :func:~pyarrow.feather.read_table reads a Feather file as a :class:~pyarrow.Table. Internally, :func:~pyarrow.feather.read_feather simply calls :func:~pyarrow.feather.read_table and the result is converted to pandas:

.. code-block:: python

Result is pandas.DataFrame

read_df = feather.read_feather('/path/to/file')

Result is pyarrow.Table

read_arrow = feather.read_table('/path/to/file')

These functions can read and write with file-paths or file-like objects. For example:

.. code-block:: python

with open('/path/to/file', 'wb') as f: feather.write_feather(df, f)

with open('/path/to/file', 'rb') as f: read_df = feather.read_feather(f)

A file input to read_feather must support seeking.

Using Compression

As of Apache Arrow version 0.17.0, Feather V2 files (the default version) support two fast compression libraries, LZ4 (using the frame format) and ZSTD. LZ4 is used by default if it is available (which it should be if you obtained pyarrow through a normal package manager):

.. code-block:: python

Uses LZ4 by default

feather.write_feather(df, file_path)

Use LZ4 explicitly

feather.write_feather(df, file_path, compression='lz4')

Use ZSTD

feather.write_feather(df, file_path, compression='zstd')

Do not compress

feather.write_feather(df, file_path, compression='uncompressed')

Note that the default LZ4 compression generally yields much smaller files without sacrificing much read or write performance. In some instances, LZ4-compressed files may be faster to read and write than uncompressed due to reduced disk IO requirements.

Writing Version 1 (V1) Files

For compatibility with libraries without support for Version 2 files, you can write the version 1 format by passing version=1 to write_feather. We intend to maintain read support for V1 for the foreseeable future.