Note

Go to the endto download the full example code.

Text properties and layout#

Controlling properties of text and its layout with Matplotlib.

matplotlib.text.Text instances have a variety of properties which can beconfigured via keyword arguments toset_title,set_xlabel,text, etc.

Property

Value Type

alpha

float

backgroundcolor

any matplotlibcolor

bbox

Rectangle prop dict plus key'pad' which is a pad in points

clip_box

a matplotlib.transform.Bbox instance

clip_on

bool

clip_path

aPath instance and aTransform instance, aPatch

color

any matplotlibcolor

family

['serif' |'sans-serif' |'cursive' |'fantasy' |'monospace' ]

fontproperties

FontProperties

horizontalalignment or ha

['center' |'right' |'left' ]

label

any string

linespacing

float

multialignment

['left' |'right' |'center' ]

name or fontname

string e.g., ['Sans' |'Courier' |'Helvetica' ...]

picker

[None|float|bool|callable]

position

(x, y)

rotation

[ angle in degrees |'vertical' |'horizontal' ]

size or fontsize

[ size in points | relative size, e.g.,'small','x-large' ]

style or fontstyle

['normal' |'italic' |'oblique' ]

text

string or anything printable with '%s' conversion

transform

Transform subclass

variant

['normal' |'small-caps' ]

verticalalignment or va

['center' |'top' |'bottom' |'baseline' ]

visible

bool

weight or fontweight

['normal' |'bold' |'heavy' |'light' |'ultrabold' |'ultralight']

x

float

y

float

zorder

any number

Text alignment#

You can lay out text with the alignment argumentshorizontalalignment,verticalalignment, andmultialignment.horizontalalignment controls whether the xpositional argument for the text indicates the left, center or rightside of the text bounding box.verticalalignment controls whetherthe y positional argument for the text indicates the bottom, center ortop side of the text bounding box.multialignment, for newlineseparated strings only, controls whether the different lines are left,center or right justified. Here is an example which uses thetext() command to show the various alignmentpossibilities. The use oftransform=ax.transAxes throughout thecode indicates that the coordinates are given relative to the Axesbounding box, with (0, 0) being the lower left of the Axes and (1, 1) theupper right.

importmatplotlib.pyplotaspltimportmatplotlib.patchesaspatches# build a rectangle in axes coordsleft,width=0.25,0.5bottom,height=0.25,0.5right=left+widthtop=bottom+heightfig=plt.figure()ax=fig.add_axes((0,0,1,1))# axes coordinates: (0, 0) is bottom left and (1, 1) is upper rightp=patches.Rectangle((left,bottom),width,height,fill=False,transform=ax.transAxes,clip_on=False)ax.add_patch(p)ax.text(left,bottom,'left top',horizontalalignment='left',verticalalignment='top',transform=ax.transAxes)ax.text(left,bottom,'left bottom',horizontalalignment='left',verticalalignment='bottom',transform=ax.transAxes)ax.text(right,top,'right bottom',horizontalalignment='right',verticalalignment='bottom',transform=ax.transAxes)ax.text(right,top,'right top',horizontalalignment='right',verticalalignment='top',transform=ax.transAxes)ax.text(right,bottom,'center top',horizontalalignment='center',verticalalignment='top',transform=ax.transAxes)ax.text(left,0.5*(bottom+top),'right center',horizontalalignment='right',verticalalignment='center',rotation='vertical',transform=ax.transAxes)ax.text(left,0.5*(bottom+top),'left center',horizontalalignment='left',verticalalignment='center',rotation='vertical',transform=ax.transAxes)ax.text(0.5*(left+right),0.5*(bottom+top),'middle',horizontalalignment='center',verticalalignment='center',fontsize=20,color='red',transform=ax.transAxes)ax.text(right,0.5*(bottom+top),'centered',horizontalalignment='center',verticalalignment='center',rotation='vertical',transform=ax.transAxes)ax.text(left,top,'rotated\nwith newlines',horizontalalignment='center',verticalalignment='center',rotation=45,transform=ax.transAxes)ax.set_axis_off()plt.show()
text props

Relative font sizes#

Font sizes can be specified in points, or as a string that indicates the sizerelative to the default font size. The following are valid values for relative font sizes:

Relative font size

Scaling of default font size

xx-small

0.579

x-small

0.694

small

0.833

medium

1.000

large

1.200

x-large

1.440

xx-large

1.728

Default Font#

The base default font is controlled by a set of rcParams. To set the fontfor mathematical expressions, use the rcParams beginning withmathtext(seemathtext).

rcParam

usage

'font.family'

List of font families (installed on user's machine)and/or{'cursive','fantasy','monospace','sans','sansserif','sans-serif','serif'}.

'font.style'

The default style, ex'normal','italic'.

'font.variant'

Default variant, ex'normal','small-caps'(untested)

'font.stretch'

Default stretch, ex'normal','condensed'(incomplete)

'font.weight'

Default weight. Either string or integer

'font.size'

Default font size in points. Relative font sizes('large','x-small') are computed againstthis size.

Matplotlib can use font families installed on the user's computer, i.e.Helvetica, Times, etc. Font families can also be specified withgeneric-family aliases like ({'cursive','fantasy','monospace','sans','sansserif','sans-serif','serif'}).

Note

To access the full list of available fonts:

matplotlib.font_manager.get_font_names()

The mapping between the generic family aliases and actual font families(mentioned atdefault rcParams)is controlled by the following rcParams:

CSS-based generic-family alias

rcParam with mappings

'serif'

'font.serif'

'monospace'

'font.monospace'

'fantasy'

'font.fantasy'

'cursive'

'font.cursive'

{'sans','sansserif','sans-serif'}

'font.sans-serif'

If any of generic family names appear in'font.family', we replace that entryby all the entries in the corresponding rcParam mapping.For example:

matplotlib.rcParams['font.family']=['Family1','serif','Family2']matplotlib.rcParams['font.serif']=['SerifFamily1','SerifFamily2']# This is effectively translated to:matplotlib.rcParams['font.family']=['Family1','SerifFamily1','SerifFamily2','Family2']

Text with non-latin glyphs#

As of v2.0 thedefault font, DejaVu, containsglyphs for many western alphabets, but not other scripts, such as Chinese,Korean, or Japanese.

To set the default font to be one that supports the code points youneed, prepend the font name to'font.family' (recommended), or to thedesired alias lists.

# first methodmatplotlib.rcParams['font.family']=['Source Han Sans TW','sans-serif']# second methodmatplotlib.rcParams['font.family']=['sans-serif']matplotlib.rcParams['sans-serif']=['Source Han Sans TW',...]

The generic family alias lists contain fonts that are either shippedalongside Matplotlib (so they have 100% chance of being found), or fontswhich have a very high probability of being present in most systems.

A good practice when setting custom font families is to appenda generic-family to the font-family list as a last resort.

You can also set it in your.matplotlibrc file:

font.family:SourceHanSansTW,Arial,sans-serif

To control the font used on per-artist basis use thename,fontname orfontproperties keyword arguments documented inText properties and layout.

On linux,fc-list can be auseful tool to discover the font name; for example

$ fc-list :lang=zh familyNoto to Sans Mono CJK TC,Noto Sans Mono CJK TC BoldNoto Sans CJK TC,Noto Sans CJK TC MediumNoto Sans CJK TC,Noto Sans CJK TC DemiLightNoto Sans CJK KR,Noto Sans CJK KR BlackNoto Sans CJK TC,Noto Sans CJK TC BlackNoto Sans Mono CJK TC,Noto Sans Mono CJK TC RegularNoto Sans CJK SC,Noto Sans CJK SC Light

lists all of the fonts that support Chinese.

Gallery generated by Sphinx-Gallery