By default, pat is interpreted as a regex pattern, unlike str.replace(), which defaults to a literal match, so characters with special regex meaning need escaping, or regex=False, if you want a purely literal substring search. The na parameter controls what boolean value to use for missing, NaN, entries in the Series, since a NaN element has no string to search and would otherwise need special handling; case=False makes the match case-insensitive.
1Understanding Series.str.contains()
By default, pat is interpreted as a regex pattern, unlike str.replace(), which defaults to a literal match, so characters with special regex meaning need escaping, or regex=False, if you want a purely literal substring search. The na parameter controls what boolean value to use for missing, NaN, entries in the Series, since a NaN element has no string to search and would otherwise need special handling; case=False makes the match case-insensitive.
Remember str.contains() defaults to treating its pattern as a regex, the opposite default from str.replace() — pass regex=False for a purely literal substring search if your pattern happens to include regex special characters you don't want interpreted.
import pandas as pd
s = pd.Series(["apple pie", "banana bread", "apple juice"])
print(s.str.contains("apple"))2Practical Example
Here is a real-world application of Series.str.contains() showing how it is used in production Pandas code.
import pandas as pd
df = pd.DataFrame({"email": ["alice@company.com", "bob@other.com"]})
work_emails = df[df["email"].str.contains("company")]
print(work_emails)3Best Practices
Follow these guidelines when working with Series.str.contains():
1. Combine str.contains() with boolean indexing to filter rows whose text matches a pattern or keyword
2. Pass case=False for case-insensitive matching instead of separately lowercasing both the Series and the search pattern first
3. Handle NaN values explicitly via the na parameter, or with an upfront fillna(), rather than letting them propagate as NaN into your boolean filter unexpectedly
Tip: Remember str.contains() defaults to treating its pattern as a regex, the opposite default from str.replace() — pass regex=False for a purely literal substring search if your pattern happens to include regex special characters you don't want interpreted.
import pandas as pd
s = pd.Series(["apple pie", "banana bread", "apple juice"])
print(s.str.contains("apple"))