Fixing Python xlrd Errors When Opening xlsx Files After Version 2.0

For years, Python developers relied on:

xlrd

to read Excel files.

Whether building:

• Data pipelines
• Reporting systems
• ETL processes
• Financial applications
• Business dashboards
• Spreadsheet automation tools

xlrd was often the default choice.

A typical workflow looked like:

import xlrd

workbook = xlrd.open_workbook(
    "report.xlsx"
)

Everything worked smoothly.

Then many projects suddenly started failing after upgrading dependencies.

Developers began encountering errors such as:

XLRDError:
Excel xlsx file; not supported

or:

Unsupported format,
or corrupt file

or:

XLRDError:
Unsupported format

Applications that had worked for years stopped processing modern Excel files.

The root cause surprised many developers:

xlrd version 2.0 removed support for XLSX files.

This change broke countless scripts, automation workflows, and production systems.

Fortunately, the issue is well understood and relatively easy to fix once you understand what changed.

In this guide, you'll learn why xlrd stopped supporting XLSX files, how to identify affected code, and the best approaches for migrating to modern Excel libraries.

What You Will Learn From This Article

After reading this guide, you'll understand:

• Why xlrd broke XLSX support.
• Common error messages.
• How to identify affected applications.
• How to migrate to openpyxl.
• How pandas handles Excel files.
• Alternative Excel libraries.
• Best practices for future compatibility.

Understanding xlrd

Historically:

xlrd

supported:

.xls

and:

.xlsx

files.

Developers could open both formats using:

xlrd.open_workbook()

without worrying about file types.

This simplicity made xlrd extremely popular.

What Changed in Version 2.0?

Beginning with:

xlrd 2.0

support for:

.xlsx

files was removed.

The library became limited to:

.xls

files only.

As a result:

xlrd.open_workbook(
    "file.xlsx"
)

started failing immediately.

Why Did xlrd Remove XLSX Support?

The maintainers simplified the project by focusing exclusively on:

Legacy XLS Files

rather than maintaining support for newer Office Open XML formats.

The change reduced:

• Maintenance burden
• Complexity
• Security concerns

However, it required users to migrate to alternative libraries.

Common Error Messages

One of the most common errors:

XLRDError:
Excel xlsx file; not supported

Example:

import xlrd

workbook = xlrd.open_workbook(
    "sales.xlsx"
)

Output:

XLRDError:
Excel xlsx file; not supported

This indicates the file format is no longer supported.

Another Common Error

Developers may see:

Unsupported format,
or corrupt file

and assume:

The Spreadsheet Is Damaged

Often:

The File Is Fine

The actual issue is library compatibility.

How to Verify Your xlrd Version

Check:

import xlrd

print(xlrd.__version__)

Example output:

2.0.1

If version 2.x is installed:

XLSX Support Removed

This immediately explains the error.

The Recommended Solution: Use openpyxl

Modern Python applications typically use:

openpyxl

for XLSX files.

Installation:

pip install openpyxl

Opening a workbook:

from openpyxl import load_workbook

workbook = load_workbook(
    "sales.xlsx"
)

This is now the preferred approach.

Reading Worksheet Data

Example:

from openpyxl import load_workbook

wb = load_workbook(
    "sales.xlsx"
)

sheet = wb.active

print(
    sheet["A1"].value
)

Simple and reliable.

Migrating Existing xlrd Code

Old code:

import xlrd

book =
    xlrd.open_workbook(
        "data.xlsx"
    )

New code:

from openpyxl import load_workbook

book =
    load_workbook(
        "data.xlsx"
    )

Additional worksheet access changes may be required.

Using pandas Instead

Many applications already use:

pandas

Example:

import pandas as pd

df = pd.read_excel(
    "sales.xlsx"
)

Modern pandas versions automatically use:

openpyxl

for XLSX files.

This often requires no code changes beyond installing the correct engine.

Explicitly Specifying the Engine

Example:

df = pd.read_excel(
    "sales.xlsx",
    engine="openpyxl"
)

Useful when:

• Multiple Excel libraries exist
• Dependency conflicts occur
• Environment consistency matters

Installing Required Packages

Typical setup:

pip install pandas
pip install openpyxl

or:

pip install pandas openpyxl

This covers most modern Excel workflows.

What If You Must Use xlrd?

Some legacy systems still require:

xlrd

for XLSX support.

One workaround:

pip install xlrd==1.2.0

Version:

1.2.0

still supports XLSX files.

However, this is generally not recommended for new projects.

Why Downgrading Isn't Ideal

Potential issues include:

• Outdated dependencies
• Security concerns
• Compatibility problems
• Lack of future maintenance

Migration is usually the better long-term solution.

Handling Both XLS and XLSX Files

Some applications process mixed spreadsheet formats.

Example:

.xls

and:

.xlsx

A common approach:

import os

extension =
    os.path.splitext(
        filename
    )[1]

Then:

.xls
↓
xlrd

.xlsx
↓
openpyxl

This ensures compatibility with both formats.

Detecting File Types Automatically

Example:

if filename.endswith(".xls"):
    # xlrd

elif filename.endswith(".xlsx"):
    # openpyxl

Useful for upload systems and automation pipelines.

Common Migration Mistakes

Mistake #1

Assuming the file is corrupted.

Example:

XLRDError
↓
Recreate Spreadsheet

The problem is often the library version.

Mistake #2

Installing openpyxl but not updating code.

Example:

pip install openpyxl

while still calling:

xlrd.open_workbook()

The error remains.

Mistake #3

Forgetting pandas engine dependencies.

Example:

pd.read_excel()

without:

openpyxl Installed

which causes import-related errors.

Real-World Example

A reporting application contains:

import xlrd

book =
    xlrd.open_workbook(
        uploaded_file
    )

After a dependency update:

xlrd 2.0 Installed

Users begin seeing:

Excel xlsx file;
not supported

The application stops processing uploads.

Solution:

from openpyxl import load_workbook

book =
    load_workbook(
        uploaded_file
    )

Result:

Uploads Work Again

with no spreadsheet modifications required.

Best Practices Checklist

When handling Excel files in Python:

✅ Use openpyxl for XLSX files

✅ Verify installed library versions

✅ Test dependency upgrades carefully

✅ Use pandas with supported engines

✅ Validate uploaded file formats

✅ Handle XLS and XLSX separately when needed

✅ Document Excel-processing dependencies

✅ Avoid relying on deprecated behavior

✅ Monitor package release notes

✅ Build migration plans for legacy systems

Common Mistakes to Avoid

Avoid:

❌ Assuming XLSX support still exists in xlrd 2.x

❌ Downgrading dependencies without understanding risks

❌ Ignoring package release notes

❌ Mixing Excel libraries unnecessarily

❌ Treating compatibility issues as file corruption

❌ Forgetting pandas engine requirements

❌ Testing only with legacy spreadsheets

Why This Issue Affected So Many Projects

The change was disruptive because:

Years of Existing Code
↓
Assumed XLSX Support

Many applications:

• Automated reports
• Imported customer spreadsheets
• Processed business data
• Ran ETL jobs

without explicit awareness of xlrd's evolving capabilities.

A routine dependency upgrade was enough to break production systems.

Wrapping Summary

The "Excel xlsx file; not supported" error became one of the most common spreadsheet-related issues in Python after xlrd version 2.0 removed support for XLSX files. Many applications that had successfully processed Excel spreadsheets for years suddenly began failing following routine dependency updates.

The root cause is not corrupted files but a fundamental change in library behavior. Modern Python applications should use openpyxl for XLSX files, while pandas users should ensure the appropriate engine is installed and configured. Although downgrading to xlrd 1.2.0 can temporarily restore compatibility, migrating to supported libraries is generally the safest and most future-proof solution.

By understanding the distinction between XLS and XLSX formats, verifying dependency versions, and adopting modern spreadsheet libraries, developers can avoid compatibility issues and build Excel-processing workflows that remain stable across future Python ecosystem updates.