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_format=None, thousands=None, decimal='.', comment=None, skipfooter=0, storage_options=None, dtype_backend=<no_default>, engine_kwargs=None)[源代码][源代码]#

将一个 Excel 文件读取到一个 pandas DataFrame 中。

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

参数:

iostr, ExcelFile, xlrd.Book, 路径对象, 或类文件对象

任何有效的字符串路径都是可接受的。字符串可以是一个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, 或 None, 默认 0

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

可用案例：

默认为 0：第1个表格作为 DataFrame
1: 作为 DataFrame 的第二张表
"Sheet1": 加载名为 “Sheet1” 的工作表
[0, 1, "Sheet5"]: 加载第一个、第二个和名为 “Sheet5” 的工作表作为 DataFrame 的字典
None: 所有工作表。

标题int, 整数列表, 默认值 0

用于解析的 DataFrame 的列标签的行（从 0 开始索引）。如果传递了一个整数列表，这些行位置将组合成一个 MultiIndex。如果没有标题，请使用 None。

名称类数组，默认无

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

index_colint, str, 整数列表, 默认 None

列（从0开始索引）用作DataFrame的行标签。如果没有这样的列，则传递None。如果传递一个列表，这些列将组合成一个``MultiIndex``。如果使用``usecols``选择数据子集，index_col基于该子集。

缺失值将被向前填充，以允许与 merged_cells=True 的 to_excel 进行往返操作。为了避免向前填充缺失值，请在读取数据后使用 set_index 而不是 index_col。

usecolsstr, 类似列表的, 或可调用的, 默认 None

如果为 None，则解析所有列。
如果是字符串，则表示以逗号分隔的 Excel 列字母和列范围（例如 “A:E” 或 “A,C,E:F”）。范围包括两端。
如果是整数列表，则表示要解析的列号列表（从0开始索引）。
如果是字符串列表，则表示要解析的列名列表。
如果是可调用的，那么针对每个列名进行评估，如果可调用对象返回 True，则解析该列。

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

dtype类型名称或列 -> 类型的字典，默认为 None

数据的类型或列的类型。例如：{‘a’: np.float64, ‘b’: np.int32} 使用 object 以保留数据在Excel中的存储方式，不解释数据类型，这必然会导致 object 数据类型。如果指定了转换器，它们将代替数据类型转换应用。如果你使用 None ，它将根据数据推断每列的数据类型。

引擎{‘openpyxl’, ‘calamine’, ‘odf’, ‘pyxlsb’, ‘xlrd’}, 默认 None

如果 io 不是一个缓冲区或路径，这必须被设置以识别 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。

转换器字典, 默认为 None

用于转换某些列中值的函数字典。键可以是整数或列标签，值是接受一个输入参数（Excel 单元格内容）并返回转换后内容的函数。

true_values列表，默认为无

视为 True 的值。

false_values列表，默认为无

视为 False 的值。

skiprows列表式、整数或可调用对象，可选

文件开头要跳过的行号（从0开始索引）或要跳过的行数（整数）。如果是一个可调用对象，该可调用函数将对行索引进行评估，如果该行应被跳过则返回 True，否则返回 False。一个有效的可调用参数示例是 lambda x: x in [0, 2]。

nrowsint, 默认为 None

要解析的行数。

na_values标量、字符串、类列表或字典，默认无

额外的字符串识别为 NA/NaN。如果传递的是字典，则为每列指定 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_na布尔值, 默认为 True

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

如果 keep_default_na 为 True，并且指定了 na_values，则 na_values 将被附加到用于解析的默认 NaN 值中。
如果 keep_default_na 为 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_filter布尔值, 默认为 True

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

详细布尔值, 默认为 False

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

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

行为如下：

bool。如果为真 -> 尝试解析索引。
list 的整数或名称。例如，如果 [1, 2, 3] -> 尝试将第1、2、3列分别解析为单独的日期列。
list 的列表。例如，如果 [[1, 3]] -> 合并第1列和第3列，并解析为一个单独的日期列。
dict，例如 {‘foo’ : [1, 3]} -> 将第1、3列解析为日期并调用结果为 ‘foo’

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

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

date_format : str 或列 -> 格式的字典, 默认 Nonestr 或列 -> 格式的字典, 默认

如果在使用 parse_dates 时使用，将根据此格式解析日期。对于更复杂的情况，请以 object 形式读入，然后根据需要应用 to_datetime()。

Added in version 2.0.0.

thousandsstr, 默认为 None

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

decimalstr, 默认 ‘.’

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

Added in version 1.4.0.

评论str, 默认为 None

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

skipfooterint, 默认 0

要跳过的末尾行数（0索引）。

storage_options字典, 可选

对于特定存储连接有意义的额外选项，例如主机、端口、用户名、密码等。对于HTTP(S) URL，键值对会作为头选项转发到 urllib.request.Request。对于其他URL（例如以“s3://”和“gcs://”开头），键值对会转发到 fsspec.open。请参阅 fsspec 和 urllib 获取更多详细信息，关于存储选项的更多示例请参考这里。

dtype_backend{‘numpy_nullable’, ‘pyarrow’}

应用于结果 DataFrame 的后端数据类型（仍在实验中）。如果未指定，默认行为是不使用可为空的数据类型。如果指定，行为如下：

"numpy_nullable": 返回支持可空数据类型的 DataFrame
"pyarrow": 返回支持 pyarrow 的可空 ArrowDtype DataFrame

Added in version 2.0.

engine_kwargs字典, 可选

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

返回:

DataFrame 或 DataFrames 的字典: 从传入的 Excel 文件生成的 DataFrame。有关何时返回 DataFrame 字典的更多信息，请参见 sheet_name 参数中的注释。

参见

DataFrame.to_excel: 将 DataFrame 写入 Excel 文件。
DataFrame.to_csv: 将 DataFrame 写入逗号分隔值（csv）文件。
read_csv: 将逗号分隔值（csv）文件读取到 DataFrame 中。
read_fwf: 将固定宽度格式化的行读取到 DataFrame 中。

备注

有关每个Excel引擎使用的方法的特定信息，请参阅pandas 用户指南

例子

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

>>> 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)  
       1      2
NaN      Name  Value
0.0   string1      1
1.0   string2      2
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

在excel输入文件中的注释行可以使用 comment kwarg 跳过。

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