Skip to main content

​
TextFrame

The part of a shape that contains its text. Not all shapes have a text frame.

​
Properties

​
text
str
All text in this text-frame as a single string. Line-feed characters ("\n") separate paragraphs, and vertical-tab characters ("\v") appear for line breaks.
text_frame.text = "First paragraph\nSecond paragraph"
​
paragraphs
tuple[_Paragraph, ...]
Sequence of paragraphs in this text frame. A text frame always contains at least one paragraph.
for paragraph in text_frame.paragraphs:
    print(paragraph.text)
​
auto_size
MSO_AUTO_SIZE | None
Resizing strategy used to fit text within this shape. May be None, MSO_AUTO_SIZE.NONE, MSO_AUTO_SIZE.SHAPE_TO_FIT_TEXT, or MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE.
from pptx.enum.text import MSO_AUTO_SIZE
text_frame.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE
​
vertical_anchor
MSO_VERTICAL_ANCHOR | None
Vertical alignment of text in this text frame. None indicates the value should be inherited from the style hierarchy.
from pptx.enum.text import MSO_VERTICAL_ANCHOR
text_frame.vertical_anchor = MSO_VERTICAL_ANCHOR.MIDDLE
​
word_wrap
bool | None
True when lines of text are wrapped to fit within the shape’s width. Assigning None causes the setting to be inherited from the style hierarchy.
text_frame.word_wrap = True
​
margin_bottom
Length
Inset of text from the bottom text frame border as a Length value.
from pptx.util import Inches
text_frame.margin_bottom = Inches(0.05)
​
margin_left
Length
Inset of text from left text frame border as Length value.
​
margin_right
Length
Inset of text from right text frame border as Length value.
​
margin_top
Length
Inset of text from top text frame border as Length value.

​
Methods

​
add_paragraph()
_Paragraph
Return new paragraph appended to the sequence of paragraphs in this text frame.
p = text_frame.add_paragraph()
p.text = "New paragraph"
​
clear()
None
Remove all paragraphs except one empty one.
text_frame.clear()
text_frame.text = "Fresh start"
​
fit_text(font_family, max_size, bold, italic, font_file)
None
Fit text entirely within bounds of its shape by setting word wrap on and applying the “best-fit” font size.
​
font_family
str
default:"Calibri"
Font family name
​
max_size
int
default:"18"
Maximum font size in points
​
bold
bool
default:"False"
Whether text should be bold
​
italic
bool
default:"False"
Whether text should be italic
​
font_file
str | None
default:"None"
Path to TrueType font file for font metrics
text_frame.fit_text(font_family="Arial", max_size=24, bold=True)

​
Paragraph

Paragraph object. Not intended to be constructed directly.

​
Properties

​
text
str
Text of paragraph as a single string. Vertical-tab characters ("\v") represent line-breaks.
paragraph.text = "Line 1\vLine 2"
​
runs
tuple[_Run, ...]
Sequence of runs in this paragraph.
for run in paragraph.runs:
    run.font.bold = True
​
font
Font
Font object containing default character properties for runs in this paragraph.
from pptx.util import Pt
paragraph.font.size = Pt(18)
paragraph.font.name = "Arial"
​
alignment
PP_PARAGRAPH_ALIGNMENT | None
Horizontal alignment of this paragraph. None indicates the paragraph inherits from its style hierarchy.
from pptx.enum.text import PP_ALIGN
paragraph.alignment = PP_ALIGN.CENTER
​
level
int
Indentation level of this paragraph (0..8 inclusive). 0 represents a top-level paragraph.
paragraph.level = 1  # First indent level
​
line_spacing
int | float | Length | None
Space between baselines in successive lines. Numeric values indicate multiples of line heights. Length values indicate fixed height.
from pptx.util import Pt
paragraph.line_spacing = 1.5  # 1.5x line spacing
paragraph.line_spacing = Pt(14)  # Fixed 14pt spacing
​
space_before
Length | None
Spacing to appear between this paragraph and the prior paragraph.
from pptx.util import Pt
paragraph.space_before = Pt(6)
​
space_after
Length | None
Spacing to appear between this paragraph and the subsequent paragraph.

​
Methods

​
add_run()
_Run
Return a new run appended to the runs in this paragraph.
run = paragraph.add_run()
run.text = "Bold text"
run.font.bold = True
​
add_line_break()
None
Add line break at end of this paragraph.
paragraph.add_line_break()
​
clear()
_Paragraph
Remove all content from this paragraph. Paragraph properties are preserved.
paragraph.clear()
paragraph.text = "New content"

​
Run

Text run object. Corresponds to a:r child element in a paragraph.

​
Properties

​
text
str
Unicode string containing the text in this run. Assignment replaces all text in the run.
run.text = "This is a text run"
​
font
Font
Font instance containing run-level character properties for the text in this run.
from pptx.util import Pt
run.font.size = Pt(14)
run.font.bold = True
run.font.color.rgb = RGBColor(255, 0, 0)
​
hyperlink
_Hyperlink
Proxy for any hyperlink element. Created on demand and available whether a hyperlink element is present or not.
run.hyperlink.address = "https://example.com"

​
Font

Character properties object, providing font size, font name, bold, italic, etc.

​
Properties

​
name
str | None
Typeface name for this font. Returns None if typeface is inherited from theme. Setting to None removes any override.
font.name = "Arial"
​
size
Length | None
Font height in English Metric Units (EMU). None indicates font size should be inherited.
from pptx.util import Pt
font.size = Pt(24)
print(font.size.pt)  # 24.0
​
bold
bool | None
Boolean bold value. None clears the bold setting and inherits from style hierarchy.
font.bold = True
​
italic
bool | None
Boolean italic value. Has same behaviors as bold with respect to None values.
font.italic = True
​
underline
bool | MSO_TEXT_UNDERLINE_TYPE | None
Underline setting. True indicates single underline, False indicates no underline. Members of MsoTextUnderlineType enumeration indicate other underline styles.
font.underline = True  # Single underline
from pptx.enum.text import MSO_UNDERLINE
font.underline = MSO_UNDERLINE.DOUBLE_LINE
​
color
ColorFormat
ColorFormat instance providing access to the color settings for this font.
from pptx.util import RGBColor
font.color.rgb = RGBColor(255, 0, 0)
​
fill
FillFormat
FillFormat instance for this font. Provides access to fill properties such as fill color.
font.fill.solid()
font.fill.fore_color.rgb = RGBColor(0, 0, 255)
​
language_id
MSO_LANGUAGE_ID | None
Language id of this font. Member of the MsoLanguageId enumeration. Assigning None removes any language setting.
from pptx.enum.lang import MSO_LANGUAGE_ID
font.language_id = MSO_LANGUAGE_ID.ENGLISH_US

Build docs developers (and LLMs) love

Get started for freeTalk to us