Python Pandas String Operations: Contains, Split, and Replace
Practical guide to pandas `.str.contains`, `.str.split`, and `.str.replace` for text cleaning and transformation.

When working with text data in pandas, the .str accessor provides vectorized string operations that avoid Python-level loops. The core operations for checking, splitting, and replacing substrings are essential for cleaning and transforming text columns efficiently.
Checking Substring Presence with .str.contains
The .str.contains method checks whether each string in a Series contains a specified pattern. By default, the pattern is treated as a regular expression, but you can disable that behavior with regex=False when you need a literal substring match.
import pandas as pd
s = pd.Series(['apple', 'banana', 'cherry', 'date'])
# Literal substring check
s.str.contains('an', regex=False)
# 0 False
# 1 True
# 2 False
# 3 False
# dtype: bool
# Regex pattern: words starting with 'c'
s.str.contains('^c', regex=True)
# 0 False
# 1 False
# 2 True
# 3 False
# dtype: boolThe na parameter controls how missing values are handled. By default, NaN propagates as NaN in the boolean result. Set na=False to treat missing values as no match, which is often more convenient for filtering.
s2 = pd.Series(['apple', None, 'cherry'])
s2.str.contains('a', na=False)
# 0 True
# 1 False
# 2 False
# dtype: boolUse case=False to perform case-insensitive matching. This works for both regex and literal modes.
Splitting Strings with .str.split
.str.split breaks each string into substrings based on a delimiter. The default delimiter is whitespace, but you can specify any separator, including regex patterns.
s = pd.Series(['a,b,c', 'd,e', 'f'])
# Split on comma, return a Series of lists
s.str.split(',')
# 0 [a, b, c]
# 1 [d, e]
# 2 [f]
# dtype: objectSetting expand=True returns a DataFrame with each split element in its own column. This is often more useful for further analysis.
s.str.split(',', expand=True)
# 0 1 2
# 0 a b c
# 1 d e None
# 2 f None NoneThe n parameter limits the number of splits. For example, n=1 splits only on the first occurrence, which is helpful when you want to separate the first field from the rest.
s.str.split(',', n=1, expand=True)
# 0 1
# 0 a b,c
# 1 d e
# 2 f NoneIf you need to split on a regular expression, set regex=True. For a literal delimiter like a pipe character that has regex meaning, either escape it or set regex=False.
Replacing Substrings with .str.replace
.str.replace substitutes occurrences of a pattern with a replacement string. Pass regex=True when the pattern should be treated as a regular expression, or regex=False for literal replacement.
s = pd.Series(['foo123', 'bar456', 'baz789'])
# Replace digits with nothing
s.str.replace(r'\d+', '', regex=True)
# 0 foo
# 1 bar
# 2 baz
# dtype: object
# Literal replacement
s.str.replace('bar', 'BAR', regex=False)
# 0 foo123
# 1 BAR456
# 2 baz789
# dtype: objectThe case parameter controls case sensitivity, and flags allows you to pass regex flags like re.IGNORECASE. The n parameter limits the number of replacements per string.
s = pd.Series(['a-b-c', 'x-y-z'])
# Replace only the first hyphen
s.str.replace('-', '_', n=1, regex=False)
# 0 a_b-c
# 1 x_y-z
# dtype: objectWhen the replacement string contains backreferences (e.g., \1), you must use a regex pattern. For literal replacement, regex=False avoids the need to escape backslashes.
Combining Operations and Handling Missing Values
String methods can be chained to perform multi-step transformations. For example, you might split a column, extract a piece, then replace a pattern.
df = pd.DataFrame({'full_name': ['Smith, John', 'Doe, Jane', None]})
# Split on comma, take the last part, strip whitespace, and uppercase
df['first_name'] = df['full_name'].str.split(',', expand=True)[1].str.strip().str.upper()
# 0 JOHN
# 1 JANE
# 2 NoneMissing values propagate through these chains, which can produce unexpected NaN results. Use .fillna() or .dropna() before or after the operations depending on your goal.
# Replace missing with a placeholder
df['first_name'] = df['first_name'].fillna('UNKNOWN')When working with regex patterns that include special characters, consider using raw strings (prefix r) to avoid escaping backslashes. This is especially important in .str.replace when you need backreferences.
Performance Considerations for Vectorized String Operations
Pandas string methods are vectorized, meaning they operate on the entire Series without an explicit Python loop. This usually gives faster code than apply() with a custom function for typical text transformations.
However, regex operations can be more expensive than literal string operations. If you do not need regex, set regex=False to avoid regex compilation and matching overhead.
Another performance factor is memory allocation. .str.split with expand=True creates a new DataFrame, which can be memory-intensive for many columns. If you only need one part, consider using .str.extract() with a regex group instead of splitting and indexing.
For very large text columns, consider whether the operation can be done in a more efficient way, such as using Python's built-in string methods inside a list comprehension and then constructing a new Series. In some cases, that can be faster than pandas' regex engine, but it loses the convenience of handling NaN and the rest of the pandas API.
Choosing the Right String Method for Your Task
Different tasks call for different methods. The table below summarizes the primary use cases for the three core operations.
| Method | Primary Use Case | Key Parameters | When to Use |
|---|---|---|---|
.str.contains | Filter rows by substring or regex pattern | regex, case, na, flags | Boolean mask for filtering or conditional logic |
.str.split | Break a string into multiple parts | expand, n, regex | Parsing delimited fields into separate columns |
.str.replace | Substitute substrings or patterns | regex, case, flags, n | Cleaning text, normalizing formats, masking data |
Use .str.contains when you need a boolean indicator for each row. It is often used in df[df['col'].str.contains(...)] to filter rows.
Use .str.split when you need to break a column into multiple columns. The expand=True parameter is the cleanest way to create a DataFrame from the split result.
Use .str.replace when you need to modify the content of strings, such as removing punctuation, standardizing date formats, or redacting sensitive information.
For more complex extraction, such as pulling a specific substring that matches a pattern, .str.extract or .str.extractall may be more appropriate than splitting and indexing. These methods use regex capture groups and return the matched portion directly.
When performance matters, prefer literal matching over regex when possible, and avoid chaining too many operations on the same column if you can combine them into a single regex. For example, a single .str.replace with a regex alternation can often replace multiple patterns in one pass.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.