I was working on a project where I needed to highlight certain thresholds in a chart. The data was from a survey on average working hours across US states, and I wanted to show benchmarks with labeled horizontal lines.
At first, I thought Matplotlib would have a direct option to add labeled horizontal lines. But as I dug deeper, I realized there are multiple ways to do this, and each method has its own use cases.
In this tutorial, I’ll share the methods I use to add horizontal lines with labels in Python Matplotlib. I’ll also include full working code examples so you can try them right away.
Methods to Add Horizontal Lines with Labels in Matplotlib
When you visualize data, context is everything. Adding horizontal lines with labels helps your audience quickly understand benchmarks or thresholds.
For example, if you’re plotting average household income in the USA, you might want to add a line showing the federal poverty threshold. Or if you’re analyzing student test scores, you might add a line for the passing mark. Labeled lines make your charts more readable and give viewers a clear reference point.
Method 1 – Use Python’s axhline() with text()
The simplest way to add a horizontal line in Matplotlib is with the axhline() function. We can then use the text() function to place a label near the line.
Here’s the full Python code example.
import matplotlib.pyplot as plt
# Sample data - average weekly working hours in the USA
states = ["California", "Texas", "New York", "Florida", "Illinois"]
hours = [38.5, 40.2, 39.1, 39.8, 38.9]
# Create the plot
plt.figure(figsize=(8, 5))
plt.bar(states, hours, color="skyblue")
# Add a horizontal line for the US average
us_average = 39.5
plt.axhline(y=us_average, color="red", linestyle="--", linewidth=2)
# Add a label to the line
plt.text(x=4.2, y=us_average+0.1, s=f"US Average: {us_average} hrs", color="red")
# Add titles and labels
plt.title("Average Weekly Working Hours by State")
plt.ylabel("Hours")
plt.show()You can see the output in the screenshot below.
In this code, I first created a bar chart of average working hours. Then I added a horizontal line at the US average and labeled it on the right side.
Method 2 – Use hlines() for Multiple Lines in Python
Sometimes you need to add more than one horizontal line. For example, you may want to show both a minimum and a maximum threshold. In that case, hlines() is more efficient because it lets you draw multiple lines at once.
Here’s how I do it in Python.
import matplotlib.pyplot as plt
# Sample data - household income in USD
states = ["California", "Texas", "New York", "Florida", "Illinois"]
income = [78000, 65000, 72000, 60000, 68000]
# Create the bar chart
plt.figure(figsize=(8, 5))
plt.bar(states, income, color="lightgreen")
# Add multiple horizontal lines
thresholds = [65000, 75000]
colors = ["orange", "purple"]
labels = ["Median US Income", "High Income Threshold"]
plt.hlines(y=thresholds, xmin=-0.5, xmax=4.5, colors=colors, linestyles="--")
# Add labels for each line
for y, label, color in zip(thresholds, labels, colors):
plt.text(x=4.2, y=y+500, s=label, color=color)
# Add titles and labels
plt.title("Average Household Income by State")
plt.ylabel("Income (USD)")
plt.show()You can see the output in the screenshot below.
In this example, I added two horizontal lines: one for the US median income and one for a high-income threshold. The labels clearly explain what each line represents.
Method 3 – Use Python’s annotate() for More Control
Sometimes you want the label to appear with an arrow pointing to the line. The annotate() function in Matplotlib gives you that flexibility.
Here’s a Python example.
import matplotlib.pyplot as plt
# Sample data - test scores of students
students = ["Alice", "Bob", "Charlie", "David", "Ella"]
scores = [78, 85, 92, 67, 88]
# Create the bar chart
plt.figure(figsize=(8, 5))
plt.bar(students, scores, color="lightcoral")
# Add a passing score line
passing_score = 70
plt.axhline(y=passing_score, color="blue", linestyle="--", linewidth=2)
# Annotate with arrow
plt.annotate("Passing Score",
xy=(4, passing_score),
xytext=(4, passing_score+10),
arrowprops=dict(facecolor="black", arrowstyle="->"),
color="blue")
# Add titles and labels
plt.title("Student Test Scores")
plt.ylabel("Score")
plt.show()You can see the output in the screenshot below.
With annotate(), you can place the label anywhere and connect it to the line with an arrow. This makes the chart more interactive and visually appealing.
Method 4 – Add Labels at the Center of the Line
By default, labels are often placed at the end of the line. But sometimes you want the label to appear in the middle of the line for balance.
Here’s how I handle it in Python.
import matplotlib.pyplot as plt
# Sample data - unemployment rate in percentage
years = [2018, 2019, 2020, 2021, 2022]
rate = [3.9, 3.7, 8.1, 5.4, 3.6]
# Create the line chart
plt.figure(figsize=(8, 5))
plt.plot(years, rate, marker="o", color="darkgreen")
# Add a recession threshold line
threshold = 6.0
plt.axhline(y=threshold, color="red", linestyle="--", linewidth=2)
# Add label at the center of the line
mid_x = (years[0] + years[-1]) / 2
plt.text(x=mid_x, y=threshold+0.2, s="Recession Threshold", ha="center", color="red")
# Add titles and labels
plt.title("US Unemployment Rate (2018-2022)")
plt.ylabel("Rate (%)")
plt.xlabel("Year")
plt.show()Notice how I calculated the midpoint of the x-axis and placed the label there. This makes the chart look cleaner, especially when presenting to an audience.
Tips for Adding Horizontal Lines with Labels
Here are a few tips I’ve learned over the years working with Python Matplotlib.
- Always use contrasting colors for lines and labels so they stand out.
- Keep labels short and clear to avoid clutter.
- If you have too many lines, consider using a legend instead of text labels.
- Use annotate() when you need arrows or flexible label positioning.
- Test your chart with different screen sizes to ensure readability.
These small adjustments can make a big difference in how your chart is perceived.
Conclusion
Adding horizontal lines with labels in Python Matplotlib is not difficult once you know the right methods. You can use axhline() for simple cases, hlines() for multiple lines, annotate() for arrows, and text() for centered labels.
I often employ these techniques in my projects when working with US-based data, such as income, unemployment, or test scores. They make the charts easier to understand and more professional for presentations or reports.
You may like to read other articles:
- Matplotlib Best Fit Curve in Python
- Matplotlib Dashed Line with Markers in Python
- Dashed Line Spacing in Python Matplotlib
- Make a Dashed Horizontal Line in Python Matplotlib
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.
