在Pandas的数据处理流程中，文本列的模糊匹配是高频需求，str.contains方法作为Series字符串类型的专属方法，能够高效判断每个字符串元素是否包含指定内容，配合正则规则可以实现复杂的匹配逻辑，最终通过布尔索引筛选出符合要求的数据行。
str.contains方法基础用法
str.contains是Pandas中用于字符串匹配的核心方法，作用于DataFrame的文本列（Series对象），返回一个与原Series长度相同的布尔型Series，其中True表示该位置字符串包含目标内容，False则表示不包含。基础语法如下：
import pandas as pd
# 构造测试数据
data = {
"name": ["张三", "李四", "王五", "赵六abc", "钱七def"],
"score": [85, 90, 78, 92, 88]
}
df = pd.DataFrame(data)
# 匹配name列中包含abc的字符串
mask = df["name"].str.contains("abc")
print(mask)
# 输出：
# 0 False
# 1 False
# 2 False
# 3 True
# 4 False
# Name: name, dtype: bool
结合布尔索引筛选数据行
得到布尔型Series后，将其作为DataFrame的行索引，即可筛选出匹配成功的数据行，这是str.contains最常用的场景：
# 筛选name列包含abc的行 result = df[mask] print(result) # 输出： # name score # 3 赵六abc 92
正则模糊匹配配置
str.contains默认支持正则表达式，通过regex参数控制是否开启正则匹配，默认值为True，因此可以直接传入正则规则实现模糊匹配：
常用正则匹配场景
- 匹配多个可选字符：使用|分隔多个目标字符串，例如匹配包含abc或def的内容
- 匹配开头结尾：使用^表示开头，$表示结尾，例如匹配以张开头的字符串
- 匹配字符范围：使用[]定义字符范围，例如匹配包含数字的内容
以下是正则模糊匹配的示例：
# 匹配name列中包含abc或def的行
mask_multi = df["name"].str.contains("abc|def")
result_multi = df[mask_multi]
print(result_multi)
# 输出：
# name score
# 3 赵六abc 92
# 4 钱七def 88
# 匹配name列中以张开头的行
mask_start = df["name"].str.contains("^张")
result_start = df[mask_start]
print(result_start)
# 输出：
# name score
# 0 张三 85
# 匹配name列中包含数字的行（测试数据无数字，可新增数据测试）
df_test = df.copy()
df_test.loc[5] = ["孙八123", 95]
mask_num = df_test["name"].str.contains("[0-9]")
result_num = df_test[mask_num]
print(result_num)
# 输出：
# name score
# 5 孙八123 95
关闭正则匹配
如果不需要正则规则，仅需要普通字符串匹配，可以将regex参数设为False，此时方法会按普通字符串进行匹配，避免正则特殊字符被误解析：
# 匹配包含.的字符串，关闭正则避免.被解析为任意字符
df_dot = pd.DataFrame({"text": ["a.b", "ab", "c.d"]})
mask_dot = df_dot["text"].str.contains(".", regex=False)
result_dot = df_dot[mask_dot]
print(result_dot)
# 输出：
# text
# 0 a.b
# 2 c.d
特殊参数说明
str.contains还有两个常用参数需要处理特殊场景：
- na参数：指定原字符串为NaN时的返回结果，默认返回NaN，可设置为False让NaN位置返回False
- case参数：控制是否区分大小写，默认True区分，设为False则不区分大小写
示例如下：
# 处理NaN值，将NaN位置的匹配结果设为False
df_na = pd.DataFrame({"text": ["abc", "def", None, "abcc"]})
mask_na = df_na["text"].str.contains("abc", na=False)
result_na = df_na[mask_na]
print(result_na)
# 输出：
# text
# 0 abc
# 3 abcc
# 不区分大小写匹配
df_case = pd.DataFrame({"text": ["Abc", "def", "ABC"]})
mask_case = df_case["text"].str.contains("abc", case=False)
result_case = df_case[mask_case]
print(result_case)
# 输出：
# text
# 0 Abc
# 2 ABC
注意事项
使用str.contains前需要确保目标列是字符串类型，若列包含其他类型，可先使用astype(str)转换为字符串类型再进行匹配，避免报错。
如果匹配规则复杂，也可以提前编译正则对象传入str.contains，提升多次匹配的效率：
import re
# 编译正则对象
pattern = re.compile("abc|def")
mask_compile = df["name"].str.contains(pattern)
result_compile = df[mask_compile]
print(result_compile)
# 输出：
# name score
# 3 赵六abc 92
# 4 钱七def 88
Pandas字符串匹配str.contains正则模糊匹配数据行筛选修改时间：2026-06-22 02:27:34