pandas.read_excel#

pandas.read_excel(io, sheet_name=0, *, header=0, names=None, index_col=None, usecols=None, dtype=None, engine=None, converters=None, true_values=None, false_values=None, skiprows=None, nrows=None, na_values=None, keep_default_na=True, na_filter=True, verbose=False, parse_dates=False, date_parser=_NoDefault.no_default, date_format=None, thousands=None, decimal='.', comment=None, skipfooter=0, storage_options=None, dtype_backend=_NoDefault.no_default, engine_kwargs=None)[源代码]#

将 Excel 文件读入 pandas DataFrame。

支持从本地文件系统或 URL 读取 xls、xlsx、xlsm、xlsb、odf、ods 和 odt 文件扩展名。支持读取单个工作表或多个工作表的选项。

Parameters:
iostr, bytes, ExcelFile, xlrd.Book, path object, or file-like object

任何有效的字符串路径都可以接受。字符串可以是 URL。有效的 URL 方案包括 http、ftp、s3 和 file。对于文件 URL，需要主机名。本地文件可以是： file://localhost/path/to/table.xlsx。

如果要传入路径对象，pandas 接受任何 os.PathLike。

我们所说的“类文件对象”指的是具有 read() 方法的对象，例如文件句柄（例如通过内置 open 函数）或 StringIO。

自 2.1.0 版本弃用: 传递字节字符串是过时的. 要从字节字符串读取，请将其包装在 BytesIO 对象中.

sheet_namestr, int, list, or None，默认为 0

字符串用于工作表名称. 整数用于零索引的工作表位置（图表工作表不计为工作表位置）. 字符串/整数列表用于请求多个工作表. 指定 None 以获取所有工作表.

可用情况：

  • 默认为 0：第一个工作表作为 DataFrame

  • 1：第二个工作表作为 DataFrame

  • "Sheet1"：加载名为 “Sheet1” 的工作表

  • [0, 1, "Sheet5"]：加载第一个、第二个和名为 “Sheet5” 的工作表，作为 DataFrame 的字典

  • None：所有工作表.

headerint, list of int，默认为 0

用于解析 DataFrame 列标签的行（零索引）. 如果传入整数列表，则将这些行位置合并为 MultiIndex. 如果不存在标题，则使用 None.

namesarray-like，默认为 None

要使用的列名列表. 如果文件不包含标题行，则应显式传递 header=None.

index_colint, str, list of int，默认为 None

用作 DataFrame 行标签的列（零索引）. 如果不存在此类列，则传递 None. 如果传递列表，则将这些列合并为 MultiIndex. 如果使用 usecols 选择数据的子集，则 index_col 基于子集.

将填充缺失值，以便与 merged_cells=True 的 to_excel 进行往返. 要避免填充缺失值，请在读取数据后使用 set_index 而不是 index_col.

usecolsstr, list-like, or callable，默认为 None

  • 如果为 None，则解析所有列.

  • 如果是 str，则表示逗号分隔的 Excel 列字母和列范围（例如 “A:E” 或 “A,C,E:F”）. 范围包含两端.

  • 如果是 int 列表，则表示要解析的列号列表（零索引）.

  • 如果是字符串列表，则表示要解析的列名列表.

  • 如果为 callable，则根据它评估每个列名，并在 callable 返回 True 時解析该列.

根据上述行为返回列的子集.

dtype类型名称或 dict，默认为 None

数据或列的数据类型. 例如 {‘a’: np.float64, ‘b’: np.int32}. 使用 object 来保留 Excel 中存储的数据，而不进行解释，这将不可避免地导致 object 类型的 dtypes. 如果指定了转换器，它们将**代替** dtype 转换. 如果使用 None，它将根据数据推断每列的 dtype.

engine{‘openpyxl’, ‘calamine’, ‘odf’, ‘pyxlsb’, ‘xlrd’}，默认为 None

如果 io 不是 buffer 或 path，则必须设置此项以标识 io. 引擎兼容性：

  • openpyxl 支持较新的 Excel 文件格式。

  • calamine 支持 Excel (.xls, .xlsx, .xlsm, .xlsb) 和 OpenDocument (.ods) 文件格式。

  • odf 支持 OpenDocument 文件格式 (.odf, .ods, .odt)。

  • pyxlsb 支持二进制 Excel 文件。

  • xlrd 支持旧式 Excel 文件 (.xls)。

当 engine=None 时，将使用以下逻辑来确定引擎：

  • 如果 path_or_buffer 是 OpenDocument 格式 (.odf, .ods, .odt)，则将使用 odf 。

  • 否则，如果 path_or_buffer 是 xls 格式，将使用 xlrd。

  • 否则，如果 path_or_buffer 是 xlsb 格式，则将使用 pyxlsb.

  • 否则，将使用 openpyxl.

convertersdict, 默认为 None

用于转换特定列中值的函数的字典. 键可以是整数或列标签，值是接受 Excel 单元格内容作为单个输入参数并返回转换后内容的函数.

true_valueslist, default None

被视为 True 的值.

false_valueslist, default None

被视为 False 的值.

skiprowslist-like, int, or callable，可选

要跳过的行号（零索引）或要跳过的行数（int），位于文件开头. 如果是 callable，则将针对行索引调用 callable 函数，如果该行应被跳过，则返回 True，否则返回 False. 有效的 callable 参数示例为 lambda x: x in [0, 2].

nrowsint，默认 None

要解析的行数.

na_valuesscalar, str, list-like, or dict，默认为 None

额外要识别为 NA/NaN 的字符串. 如果传递了 dict，则为特定于列的 NA 值. 默认情况下，以下值被解释为 NaN： ‘’, ‘#N/A’, ‘#N/A N/A’, ‘#NA’, ‘-1.#IND’, ‘-1.#QNAN’, ‘-NaN’, ‘-nan’, ‘1.#IND’, ‘1.#QNAN’, ‘<NA>’, ‘N/A’, ‘NA’, ‘NULL’, ‘NaN’, ‘None’, ‘n/a’, ‘nan’, ‘null’.

keep_default_nabool, default True

在解析数据时是否包含默认 NaN 值. 根据是否传入 na_values，行为如下：

  • If keep_default_na is True，并且指定了 na_values，则将 na_values 追加到用于解析的默认 NaN 值.

  • If keep_default_na is True，并且未指定 na_values，则仅使用默认 NaN 值进行解析.

  • 如果 keep_default_na 为 False，并且指定了 na_values，则只有在 na_values 中指定的 NaN 值才会被用于解析。

  • 如果 keep_default_na 为 False，并且没有指定 na_values，则没有任何字符串会被解析为 NaN。

请注意，如果 na_filter 被设置为 False，则 keep_default_na 和 na_values 参数将被忽略。

na_filterbool, default True

检测缺失值标记（空字符串和 na_values 的值）。在没有任何 NA 的数据中，将 na_filter=False 可以提高读取大型文件的性能。

verbosebool，默认 False

指定非数字列中放置的 NA 值的数量。

parse_dates布尔值、类列表或字典，默认为 False

行为如下：

  • 布尔值。如果为 True -> 尝试解析索引。

  • ``列表``（整数或名称）。例如，如果为 [1, 2, 3] -> 尝试将第 1、2、3 列分别解析为日期列。

  • ``列表``（列表的列表）。例如，如果为 [[1, 3]] -> 将第 1 列和第 3 列合并并解析为单个日期列。

  • 字典，例如 {‘foo’ : [1, 3]} -> 将第 1 列和第 3 列解析为日期，并将结果命名为 ‘foo’

如果列或索引包含无法解析的日期，则整个列或索引将按原样返回为对象数据类型。如果您不想将某些单元格解析为日期，只需在 Excel 中将其类型更改为“文本”。对于非标准的日期时间解析，请在 pd.read_excel 之后使用 pd.to_datetime。

注意：对于 iso8601 格式的日期，存在一个快速路径。

date_parserfunction, optional

用于将一系列字符串列转换为日期时间实例数组的函数。默认使用 dateutil.parser.parser 进行转换。Pandas 将尝试以三种不同的方式调用 date_parser，如果发生异常则继续下一个：1) 将一个或多个数组（由 parse_dates 定义）作为参数传递；2) 将 parse_dates 定义的列中的字符串值按行连接成一个数组并传递；3) 使用一个或多个字符串（对应于 parse_dates 定义的列）作为参数，为每一行调用一次 date_parser。

自 2.0.0 版本弃用: 请改用 date_format，或者将数据读取为 object 类型，然后根据需要应用 to_datetime() 。

date_format：字符串或字典（列 -> 格式），默认为 None字符串或字典（列 -> 格式），默认为

如果与 parse_dates 一起使用，将根据此格式解析日期。对于更复杂的情况，请将数据读取为 object 类型，然后根据需要应用 to_datetime() 。

在 2.0.0 版本加入.

thousandsstr，默认 None

用于将字符串列解析为数字的千位分隔符。请注意，此参数仅对于存储为 Excel 文本的列是必需的，任何数字列都将自动解析，无论其显示格式如何。

decimalstr, 默认为 ‘.’

用于将字符串列解析为数字的小数点字符。请注意，此参数仅对于存储为 Excel 文本的列是必需的，任何数字列都将自动解析，无论其显示格式如何（例如，欧洲数据可以使用 ‘,’）。

在 1.4.0 版本加入.

commentstr，默认 None

注释掉行中的其余部分。将字符串或字符串传递给此参数以指示输入文件中的注释。注释字符串和当前行末尾之间的任何数据都将被忽略。

skipfooterint，默认为 0

要跳过的末尾行（从 0 开始索引）。

storage_optionsdict, 可选

适用于特定存储连接的额外选项，例如主机、端口、用户名、密码等。对于 HTTP(S) URL，键值对将作为标头选项转发给 urllib.request.Request。对于其他 URL（例如，以 “s3://”, 和 “gcs://” 开头的 URL），键值对将转发给 fsspec.open。更多详情请参阅 fsspec 和 urllib，有关存储选项的更多示例，请参阅 here 。

dtype_backend{‘numpy_nullable’, ‘pyarrow’}, 默认 ‘numpy_nullable’

应用于结果 DataFrame 的后端数据类型（仍处于实验阶段）。行为如下：

  • "numpy_nullable"：返回支持可空 dtype 的 DataFrame （默认）。

  • "pyarrow"：返回 pyarrow 支持的可空 ArrowDtype DataFrame。

在 2.0 版本加入.

engine_kwargsdict, 可选

传递给 Excel 引擎的任意关键字参数。

Returns:
DataFrame 或 DataFrame 字典

从传入的 Excel 文件中读取的 DataFrame。有关何时返回 DataFrame 字典的信息，请参阅 sheet_name 参数中的注释。

参见

DataFrame.to_excel

将 DataFrame 写入 Excel 文件。

DataFrame.to_csv

将 DataFrame 写入逗号分隔值 (csv) 文件。

read_csv

将逗号分隔值 (csv) 文件读取到 DataFrame 中。

read_fwf

将固定宽度格式化行的表格读入 DataFrame。

Notes

有关每个 Excel 引擎所用方法的具体信息，请参阅 pandas 的 user guide

Examples

可以使用文件名字符串或打开的文件对象来读取文件：

>>> pd.read_excel('tmp.xlsx', index_col=0)  
       Name  Value
0   string1      1
1   string2      2
2  #Comment      3

>>> pd.read_excel(open('tmp.xlsx', 'rb'),
...               sheet_name='Sheet3')  
   Unnamed: 0      Name  Value
0           0   string1      1
1           1   string2      2
2           2  #Comment      3

索引和标题可以通过 index_col 和 header 参数指定

>>> pd.read_excel('tmp.xlsx', index_col=None, header=None)  
     0         1      2
0  NaN      Name  Value
1  0.0   string1      1
2  1.0   string2      2
3  2.0  #Comment      3

列类型是推断的，但也可以显式指定

>>> pd.read_excel('tmp.xlsx', index_col=0,
...               dtype={'Name': str, 'Value': float})  
       Name  Value
0   string1    1.0
1   string2    2.0
2  #Comment    3.0

True、False 和 NA 值以及千位分隔符都有默认值，但也可以显式指定。提供您想要的值作为字符串或字符串列表！

>>> pd.read_excel('tmp.xlsx', index_col=0,
...               na_values=['string1', 'string2'])  
       Name  Value
0       NaN      1
1       NaN      2
2  #Comment      3

可以使用 comment 关键字参数跳过 Excel 输入文件中的注释行。

>>> pd.read_excel('tmp.xlsx', index_col=0, comment='#')  
      Name  Value
0  string1    1.0
1  string2    2.0
2     None    NaN
On this page
显示源代码