In many real-world projects, especially when dealing with file names, column headers in CSV files, or user-generated content, I often had to replace spaces with underscores.
For example, if I had a file name like Annual Report 2025.pdf, I needed to convert it into Annual_Report_2025.pdf so that it’s easier to handle in code and doesn’t break in automated scripts.
Python makes this task simple, but there are several methods to do it. I’ve used different approaches depending on the situation. In this tutorial, I will show you the most practical ways to replace whitespaces with underscores in Python.
Method 1 – Use the str.replace() Method in Python
The simplest way to replace spaces with underscores is by using Python’s built-in replace() method. This method is easy and works perfectly when you know you only need to replace spaces.
Example
# Example: Replace spaces with underscores using replace()
text = "New York City Data Report"
result = text.replace(" ", "_")
print("Original:", text)
print("Modified:", result)Output:
Original: New York City Data Report
Modified: New_York_City_Data_ReportI executed the above example code and added the screenshot below.
This approach is fast and easy. I use it when I’m cleaning up simple strings like file names or column headers.
Method 2 – Use Regular Expressions (re.sub)
Sometimes, strings may contain multiple types of whitespace, such as tabs (\t) or newlines (\n). In these cases, replace() won’t work unless you handle each whitespace manually.
That’s where Python’s re module comes in handy. With re.sub(), I can replace all whitespace characters with a single underscore.
Example
import re
# Example: Replace all whitespace characters with underscores
text = "Los Angeles\tCounty Data\nReport"
result = re.sub(r"\s+", "_", text)
print("Original:", text)
print("Modified:", result)Output:
Original: Los Angeles County Data
Report
Modified: Los_Angeles_County_Data_ReportI executed the above example code and added the screenshot below.
I often use this method when working with messy data files where spaces, tabs, and line breaks are mixed.
Method 3 – Use split() and join()
Another method I like is splitting the string into words and then joining them back with underscores. This is useful when I want to normalize text and remove any extra spaces.
Example
# Example: Replace whitespaces with underscores using split() and join()
text = " San Francisco Housing Data "
result = "_".join(text.split())
print("Original:", text)
print("Modified:", result)Output:
Original: San Francisco Housing Data
Modified: San_Francisco_Housing_DataI executed the above example code and added the screenshot below.
Notice how this method automatically removes extra spaces at the beginning, middle, and end of the string. That makes it a great choice for cleaning up inconsistent data.
Method 4 – Use a For Loop
If you’re just starting with Python, you might want to see how this can be done manually with a loop. Although I don’t usually use this in production, it’s a good way to understand how string manipulation works.
Example
# Example: Replace spaces with underscores using a for loop
text = "Chicago Population Growth Report"
result = ""
for char in text:
if char == " ":
result += "_"
else:
result += char
print("Original:", text)
print("Modified:", result)Output:
Original: Chicago Population Growth Report
Modified: Chicago_Population_Growth_ReportThis method gives you full control, and you can easily extend it to handle other custom replacements.
Method 5 – Use map() Function
Another Pythonic way is to use the map() function with a small lambda expression. This is not the most common approach, but it’s a neat trick that I’ve used when working with functional-style code.
Example
# Example: Replace spaces with underscores using map()
text = "Boston Housing Price Index"
result = "".join(map(lambda x: "_" if x == " " else x, text))
print("Original:", text)
print("Modified:", result)Output:
Original: Boston Housing Price Index
Modified: Boston_Housing_Price_IndexThis method is concise and works well if you like functional programming patterns.
Real-World Example – Clean Column Names in a CSV File
In many U.S.-based data projects, especially when working with Census or housing datasets, column names often contain spaces.
For example, you might have a CSV file with column headers like:
City Name, Population Growth, Median IncomeIf you want to use these as DataFrame column names in pandas, it’s better to replace spaces with underscores.
Example
import pandas as pd
# Example CSV data
data = {
"City Name": ["New York", "Los Angeles", "Chicago"],
"Population Growth": [2.1, 1.8, 1.5],
"Median Income": [75000, 68000, 61000]
}
df = pd.DataFrame(data)
# Replace spaces in column names with underscores
df.columns = df.columns.str.replace(" ", "_")
print(df.head())Output:
City_Name Population_Growth Median_Income
0 New York 2.1 75000
1 Los Angeles 1.8 68000
2 Chicago 1.5 61000This is one of the most practical use cases I’ve seen in real projects. It makes column names easier to work with in Python.
Things to Keep in Mind
- If you only need to replace normal spaces, use replace() (fastest option).
- If you need to handle tabs, newlines, or multiple spaces, use re.sub().
- If you want to normalize text and remove extra spaces, use split() and join() methods in Python.
- For educational purposes or custom replacements, try loops or map().
- Always test your code with real-world data before finalizing the method.
Replacing whitespaces with underscores in Python is a common task, and as you’ve seen, there are multiple ways to do it.
When I work with clean and predictable strings, I prefer the simple replace() method. But when I’m cleaning messy datasets, I usually go with re.sub() or split() and join() methods in Python.
The method you choose depends on the type of data you’re working with. Try out these approaches in your own projects, and you’ll quickly see which one works best for your situation.
Other Python tutorials you may also like:
- Write to a File Without Newline in Python
- Delete a File if it Exists in Python
- Create a File in Python if It Doesn’t Exist
- Write JSON Data to a File in Python
I am Bijay Kumar, a Microsoft MVP in SharePoint. Apart from SharePoint, I started working on Python, Machine learning, and artificial intelligence for the last 5 years. During this time I got expertise in various Python libraries also like Tkinter, Pandas, NumPy, Turtle, Django, Matplotlib, Tensorflow, Scipy, Scikit-Learn, etc… for various clients in the United States, Canada, the United Kingdom, Australia, New Zealand, etc. Check out my profile.
