How to Extract Alternative Text (Alt Text) from Images in PDF?

[krish-tech02]

Description

I'm trying to extract the alternative text (alt text) from images embedded in PDF documents using PyMuPDF. Alt text is typically used for accessibility purposes in tagged PDFs (PDF/UA).

What I've Tried

I've attempted several approaches to extract the alt text, but none of them have worked successfully:

Approach 1: Using xref_get_key

import fitz

doc = fitz.open("sample.pdf")
page = doc[0]
images = page.get_images(full=True)

for img in images:
    xref = img[0]
    try:
        alt_text = doc.xref_get_key(xref, "Alt")
        print(f"Alt text: {alt_text}")
    except Exception as e:
        print(f"Error: {e}")

Approach 2: Checking ActualText

import fitz

doc = fitz.open("sample.pdf")
page = doc[0]
images = page.get_images(full=True)

for img in images:
    xref = img[0]
    try:
        # Check Alt key
        alt_key = doc.xref_get_key(xref, "Alt")
        if alt_key[0] == "string":
            print(f"Alt: {alt_key[1]}")
        
        # Check ActualText key
        actual_key = doc.xref_get_key(xref, "ActualText")
        if actual_key[0] == "string":
            print(f"ActualText: {actual_key[1]}")
    except Exception as e:
        print(f"Error: {e}")

Approach 3: Checking Structure Tree

import fitz

doc = fitz.open("sample.pdf")

# Check if PDF has structure tree
catalog = doc.pdf_catalog()
print(f"Has StructTreeRoot: {'StructTreeRoot' in catalog}")
print(f"Has MarkInfo: {'MarkInfo' in catalog}")

Results

None of the above approaches successfully extracted the alt text from my PDF, even though:

• The PDF is tagged and accessible
• The images definitely have alt text assigned

The xref_get_key method either returns None or throws exceptions when trying to access the Alt or ActualText keys.

Questions

1. Is there a supported way to extract alt text from images in PyMuPDF? None of my attempts have worked.
2. Does PyMuPDF currently support accessing alt text or the structure tree for tagged PDFs?
3. If this feature doesn't exist yet, are there plans to add support for accessibility metadata?
4. Is there any workaround or undocumented method to access this information?

Environment

• PyMuPDF Version: 1.24.5
• Python Version: Python 3.12.10

Sample PDF

I'm attaching a sample PDF file that contains images with alt text. The PDF is created with accessibility features (PDF/UA compliant).

Breast Care After Birth 10–02-2025 FR - Copy.pdf

[Attach your sample PDF file here]

Expected Behavior

I expect to be able to extract the alternative text associated with images in the PDF, similar to how it appears in Adobe Acrobat's accessibility checker or other PDF readers that support accessibility features.

Any guidance on accessing these properties through PyMuPDF would be greatly appreciated!

Thank you for maintaining this excellent library!
@JorjMcKie

[JorjMcKie]

We are planning to publish a new version soon that will support optimized layout analysis. The images in your example file would then appear as something like this:

BTW this PDF has no StrutureTreeRoot so there exists no such identification of that text as "alt-text" in the PDF itself! You seem to not have exported it from Word with the right options.

Nonetheless our layout analyzer has detected that text as "caption".

[krish-tech02]

@JorjMcKie, I am looking to fetch the alt text example shown in the screenshot below(this is from microsoft word):

[JorjMcKie]

When exporting Word to PDF: which options do you choose?

[krish-tech02]

@JorjMcKie Sorry for the late reply, I am just using the Save as PDF option from a Word document.