pandas.read_excel() 详细介绍

看过来

《pandas 教程》持续更新中，提供建议、纠错、催更等加作者微信: gairuo123（备注：pandas教程）和关注公众号「盖若」ID: gairuo。跟作者学习，请进入 Python学习课程。欢迎关注作者出版的书籍：《深入浅出Pandas》和《Python之光》。

pandas.read_excel() 接口用于读取 excel 格式数据文件，由于它使用非常频繁，功能强大参数众多，所以在这里专门做详细介绍，我们在使用过程中可以查阅。

语法

它的语法如下：

pd.read_excel(io, sheet_name=0, header=0,
              names=None, index_col=None,
              usecols=None, squeeze=False,
              dtype=None, engine=None,
              converters=None, true_values=None,
              false_values=None, skiprows=None,
              nrows=None, na_values=None,
              keep_default_na=True, verbose=False,
              parse_dates=False, date_parser=None,
              thousands=None, comment=None, skipfooter=0,
              convert_float=True, mangle_dupe_cols=True, **kwds)

参数

文件 io

Excel 文件。

# str, bytes, ExcelFile, xlrd.Book, path object, or file-like object
# 本地相对路径：
pd.read_excel('data/data.xlsx') # 注意目录层级
pd.read_excel('data.xls') # 如果文件与代码文件在同目录下
# 本地绝对路径：
pd.read_excel('/user/gairuo/data/data.xlsx')
# 使用网址 url
pd.read_excel('https://gairuo.com/file/data/dataset/team.xlsx')

表格 sheet_name

可以指定 Excel 文件读取哪个 sheet，默认取第一个。

# str, int, list, or None, default 0
pd.read_excel('tmp.xlsx', sheet_name=1) # 第二个 sheet
pd.read_excel('tmp.xlsx', sheet_name='总结表') # 按 sheet 的名字

# 取第一个、第二个、名为 Sheet5 的，返回一个 df 组成的字典
dfs = pd.read_excel('tmp.xlsx', sheet_name=[0, 1, "Sheet5"])
dfs = pd.read_excel('tmp.xlsx', sheet_name=None) # 所有的 sheet
dfs['Sheet5'] # 读取时按 sheet 名

数据的表头，默认为第一行。

# int, list of int, default 0
pd.read_excel('tmp.xlsx', header=None)  # 不设表头
pd.read_excel('tmp.xlsx', header=2)  # 第三行为表头
pd.read_excel('tmp.xlsx', header=[0, 1])  # 两层表头，多层索引

列名/表头名 names

默认取数据中默认的表头名称，可以重新指定。

# array-like, default None
pd.read_excel('tmp.xlsx', names=['姓名', '年龄', '成绩'])
pd.read_excel('tmp.xlsx', names=c_list) # 传入列表变量
# 没有表头，需要设置为 None
pd.read_excel('tmp.xlsx', header=None, names=None)

索引列 index_col

作为索引的列，默认不设置，使用自然索引（从 0 开始）。

# int, list of int, default None
pd.read_excel('tmp.xlsx', index_col=0) # 指定第一列
pd.read_excel('tmp.xlsx', index_col=[0,1]) # 前两列，多层索引

使用列 usecols

指定使用的列，其余的不读取，默认是全部使用。

# int, str, list-like, or callable default None
pd.read_excel('tmp.xlsx', usecols='A,B')  # 取 A 和 B 两列
pd.read_excel('tmp.xlsx', usecols='A:H')  # 取 A 到 H 列
pd.read_excel('tmp.xlsx', usecols='A,C,E:H')  # 取 A和C列，再加E到H列
pd.read_excel('tmp.xlsx', usecols=[0,1])  # 取前两列
pd.read_excel('tmp.xlsx', usecols=['姓名','性别'])  # 取指定列名的列
# 表头包含 Q 的
pd.read_excel('team.xlsx', usecols=lambda x: 'Q' in x)

返回序列 squeezebool

如果只要一列，则返回一个 Series，默认还是 DataFrame。

# default False
pd.read_excel('tmp.xlsx', usecols='A', squeezebool=True)

数据类型 dtype

数据类型，如果不传则自动推断。如果被 converters 处理则不生效。

# Type name or dict of column -> type, default None
pd.read_excel(data, dtype=np.float64) # 所有数据均为此数据类型
pd.read_excel(data, dtype={'c1':np.float64, 'c2': str}) # 指定字段的类型
pd.read_excel(data, dtype=[datetime, datetime, str, float]) # 依次指定

处理引擎 engine

可接受的参数值是 “xlrd”, “openpyxl” 或者 “odf”，如果文件不是缓冲或路径，就需要指定，用于处理 excel 使用的引擎，三方库。

# str, default None
pd.read_excel('tmp.xlsx', engine='xlrd')

在我的实践中，默认的 xlrd 引擎不会读取内容为星号*、百分号 % 等特殊字符的行，可以更换为 openpyxl 解决。

Excel 的三方库依赖：

从 Pandas 1.3 版本开始，在读取新的 Excel 2007+（.xlsx）文件时，read_excel() 默认参数 engine=None，将配置项 io.Excel.xlsx.reader 设置为“auto”时，都会使用 openpyxl 引擎。以前，有些情况下会使用 xlrd 引擎。

由于不再维护用于编写旧式 .xls Excel 文件的 xlwt 包。从 Pandas 1.2 开始，xlrd 包现在仅用于读取旧式 .xls 文件。

以前，read_excel() 的默认参数 engine=None 下使用 xlrd 引擎，包括新的 Excel 2007+（.xlsx）文件。如果安装了openpyxl，许多情况下现在将默认使用 openpyxl 引擎。

因此，强烈建议安装 openpyxl 来读取Excel 2007+（.xlsx）文件。使用 xlrd 读取 .xlsx 文件时，不再支持，请改为使用 openpyxl。

除非选项 io.excel.xls.writer 设置为“xlwt”，否则尝试使用 xlwt 引擎将发出未来警告。虽然此选项现在已被弃用，并且还会引发 FutureWarning，但可以全局设置此选项并抑制警告。建议用户使用 openpyxl 引擎编写 .xlsx 文件。

列数据处理 converters

对列的数据进行转换，列名与函数组成的字典。key 可以是列名或者列的序号。

# dict, default None
def foo(p):
   return p + 's'

# x 应用函数, y 使用 lambda
pd.read_excel('tmp.xlsx', converters={'x': foo,
                                    'y': lambda x: x * 3})
# 使用列索引
pd.read_excel('tmp.xlsx',
            converters={0: foo, 1: lambda x: x * 3})

真假值指定 true_values false_values

将指定的文本转换为 True 或者 False, 可以用列表指定多个值。

# list, default None
pd.read_excel('tmp.xlsx',
            true_values=['Yes'], false_values=['No'])

跳过指定行 skiprows

# list-like, int or callable, optional
# 跳过前三行
pd.read_excel(data, skiprows=2)
# 跳过前三行
pd.read_excel(data, skiprows=range(2))
# 跳过指定行
pd.read_excel(data, skiprows=[24,234,141])
# 跳过指定行
pd.read_excel(data, skiprows=np.array([2, 6, 11]))
# 隔行跳过
pd.read_excel(data, skiprows=lambda x: x % 2 != 0)
# 跳过最后几行用 skipfooter=2

读取行数 nrows

需要读取的行数，从文件开头算起，经常用于较大的数据，先取部分进行代码编写。

# int, default None
pd.read_excel(data, nrows=1000)

空值替换 na_values

一组用于替换 NA/NaN 的值。如果传参，需要制定特定列的空值。

# scalar, str, list-like, or dict, default None
# 5 和 5.0 会被认为 NaN
pd.read_excel(data, na_values=[5])
# ? 会被认为 NaN
pd.read_excel(data, na_values='?')
# 空值为 NaN
pd.read_excel(data, keep_default_na=False, na_values=[""])
# 字符 NA 字符 0 会被认为 NaN
pd.read_excel(data, keep_default_na=False, na_values=["NA", "0"])
# Nope 会被认为 NaN
pd.read_excel(data, na_values=["Nope"])
# a、b、c 均会被认为 NaN 等于 na_values=['a','b','c']
pd.read_excel(data, na_values='abc')
# 指定列的指定值会被认为 NaN
pd.read_excel(data, na_values={'c':3, 1:[2,5]})

保留默认空值 keep_default_na

分析数据时是否包含默认的NaN值，是否自动识别。如果指定 na_values 参数，并且 keep_default_na=False，那么默认的NaN将被覆盖，否则添加。

和 na_values 的关系是：

keep_default_na	na_values	逻辑
True	指定	na_values 的配置附加处理
True	未指定	自动识别
False	指定	使用 na_values 的配置
False	未指定	不做处理

注：如果 na_filter 为 False （默认是 True）, 那么 keep_default_na 和 na_values parameters 均无效。

# boolean, default True
# 不自动识别空值
pd.read_excel(data, keep_default_na=False)

丢失值检查 na_filter

是否检查丢失值（空字符串或者是空值）。对于大文件来说数据集中没有空值，设定na_filter=False 可以提升读取速度。

# boolean, default True
pd.read_excel(data, na_filter=False) # 不检查

解析信息 verbose

是否打印各种解析器的输出信息，例如：“非数值列中缺失值的数量”等。

# boolean, default False
# 可以看到解析信息
pd.read_excel(data, verbose=True)
# Tokenization took: 0.02 ms
# Type conversion took: 0.36 ms
# Parser memory cleanup took: 0.01 ms

日期时间解析 parse_dates

本参数对时间日期进行解析。

# boolean or list of ints or names or list of lists or dict, default False.
pd.read_excel(data, parse_dates=True) # 自动解析日期时间格式
pd.read_excel(data, parse_dates=['年份']) # 指定日期时间字段进行解析
# 将 1、4 列合并解析成名为 时间的 时间类型列
pd.read_excel(data, parse_dates={'时间':[1,4]})

日期时间解析器 date_parser

用于解析日期的函数，默认使用dateutil.parser.parser来做转换。Pandas 尝试使用三种不同的方式解析，如果遇到问题则使用下一种方式。

使用一个或者多个arrays（由parse_dates指定）作为参数；
连接指定多列字符串作为一个列作为参数；
每行调用一次date_parser函数来解析一个或者多个字符串（由parse_dates指定）作为参数。

# function, default None
# 指定时间解析库，默认是 dateutil.parser.parser
date_parser=pd.io.date_converters.parse_date_time
date_parser=lambda x: pd.to_datetime(x, utc=True, format='%d%b%Y')
date_parser = lambda d: pd.datetime.strptime(d, '%d%b%Y')
# 使用
pd.read_excel(data, parse_dates=['年份'], date_parser=date_parser)

千分位分割符 thousands

千位分隔符。

# str, default None
pd.read_excel(data, thousands=',') # 逗号分隔

注释标识 comment

指示不应分析行的部分。如果在一行的开头找到该行，则将完全忽略该行。此参数必须是单个字符。像空行一样（只要skip_blank_lines = True），参数视为header会忽略完全注释的行，而skiprows 行会忽略。例如，如果comment ='＃'，则解析header= 0的'#empty \ na，b，c \ n1,2,3'会将'a，b，c'视为header。

# str, default None
s = '# notes\na,b,c\n# more notes\n1,2,3' # 仅为示例
pd.read_excel(data, sep=',', comment='#', skiprows=1)

尾部跳过 skipfooter

从文件尾部开始忽略。 (c引擎不支持)

# int, default 0
pd.read_excel(filename, skipfooter=1) # 最后一行不加载

转为浮点 convert_float

读取 Excel 默认把数字转为浮点，设为 False 将保留整型。

# bool, default True
pd.read_excel('tmp.xlsx', convert_float=False)

mangle_dupe_cols

处理重复列名 mangle_dupe_cols

当列名有重复时，解析列名将变为 ‘X’, ‘X.1’…’X.N’而不是 ‘X’…’X’。如果该参数为 False ，那么当列名中有重复时，前列将会被后列覆盖。

# bool, default True
data = 'a,b,a\n0,1,2\n3,4,5' # 仅为示例
pd.read_excel(data, mangle_dupe_cols=True)
# 表头为 a b a.1
# False 会报 ValueError 错误

存储选项 storage_options

见 pandas.read_csv 介绍。

其他参数 **kwds

TextFileReader 处理的其他参数。

一般情况下，会将读取到的数据返回一个 DataFrame，当然按照参数的要求会返回指定的类型。