:orphan:

.. _tutorials:

Tutorials
=========

This page contains more in-depth guides for using Matplotlib.
It is broken up into beginner, intermediate, and advanced sections,
as well as sections covering specific topics.

For shorter examples, see our `examples page <../gallery/index.html>`_.
You can also find `external resources <../resources/index.html>`_ and
a `FAQ <../faq/index.html>`_ in our `user guide <../contents.html>`_.



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    </div>


Introductory
-------------

These tutorials cover the basics of creating visualizations with
Matplotlib, as well as some best-practices in using the package
effectively.



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="An introduction to the pyplot interface.  Please also see /tutorials/introductory/quick_start f...">

.. only:: html

  .. image:: /tutorials/introductory/images/thumb/sphx_glr_pyplot_thumb.png
    :alt: Pyplot tutorial

  :ref:`sphx_glr_tutorials_introductory_pyplot.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Pyplot tutorial</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A short tutorial on plotting images with Matplotlib.">

.. only:: html

  .. image:: /tutorials/introductory/images/thumb/sphx_glr_images_thumb.png
    :alt: Image tutorial

  :ref:`sphx_glr_tutorials_introductory_images.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Image tutorial</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial aims to show the beginning, middle, and end of a single visualization using Matpl...">

.. only:: html

  .. image:: /tutorials/introductory/images/thumb/sphx_glr_lifecycle_thumb.png
    :alt: The Lifecycle of a Plot

  :ref:`sphx_glr_tutorials_introductory_lifecycle.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The Lifecycle of a Plot</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Tips for customizing the properties and default styles of Matplotlib.">

.. only:: html

  .. image:: /tutorials/introductory/images/thumb/sphx_glr_customizing_thumb.png
    :alt: Customizing Matplotlib with style sheets and rcParams

  :ref:`sphx_glr_tutorials_introductory_customizing.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Customizing Matplotlib with style sheets and rcParams</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial covers some basic usage patterns and best practices to help you get started with ...">

.. only:: html

  .. image:: /tutorials/introductory/images/thumb/sphx_glr_quick_start_thumb.png
    :alt: Quick start guide

  :ref:`sphx_glr_tutorials_introductory_quick_start.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Quick start guide</div>
    </div>


.. raw:: html

    </div>


Intermediate
------------

These tutorials cover some of the more complicated classes and functions
in Matplotlib. They can be useful for particular custom and complex
visualizations.



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Using Artist objects to render on the canvas.">

.. only:: html

  .. image:: /tutorials/intermediate/images/thumb/sphx_glr_artists_thumb.png
    :alt: Artist tutorial

  :ref:`sphx_glr_tutorials_intermediate_artists.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Artist tutorial</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Generating legends flexibly in Matplotlib.">

.. only:: html

  .. image:: /tutorials/intermediate/images/thumb/sphx_glr_legend_guide_thumb.png
    :alt: Legend guide

  :ref:`sphx_glr_tutorials_intermediate_legend_guide.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Legend guide</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Demo of custom property-cycle settings to control colors and other style properties for multi-l...">

.. only:: html

  .. image:: /tutorials/intermediate/images/thumb/sphx_glr_color_cycle_thumb.png
    :alt: Styling with cycler

  :ref:`sphx_glr_tutorials_intermediate_color_cycle.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Styling with cycler</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="How to use constrained-layout to fit plots within your figure cleanly.">

.. only:: html

  .. image:: /tutorials/intermediate/images/thumb/sphx_glr_constrainedlayout_guide_thumb.png
    :alt: Constrained Layout Guide

  :ref:`sphx_glr_tutorials_intermediate_constrainedlayout_guide.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Constrained Layout Guide</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="How to use tight-layout to fit plots within your figure cleanly.">

.. only:: html

  .. image:: /tutorials/intermediate/images/thumb/sphx_glr_tight_layout_guide_thumb.png
    :alt: Tight Layout guide

  :ref:`sphx_glr_tutorials_intermediate_tight_layout_guide.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Tight Layout guide</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Often more than one Axes is wanted on a figure at a time, usually organized into a regular grid...">

.. only:: html

  .. image:: /tutorials/intermediate/images/thumb/sphx_glr_arranging_axes_thumb.png
    :alt: Arranging multiple Axes in a Figure

  :ref:`sphx_glr_tutorials_intermediate_arranging_axes.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Arranging multiple Axes in a Figure</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The limits on an axis can be set manually (e.g. ax.set_xlim(xmin, xmax)) or Matplotlib can set ...">

.. only:: html

  .. image:: /tutorials/intermediate/images/thumb/sphx_glr_autoscale_thumb.png
    :alt: Autoscaling

  :ref:`sphx_glr_tutorials_intermediate_autoscale.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Autoscaling</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="imshow allows you to render an image (either a 2D array which will be color-mapped (based on *n...">

.. only:: html

  .. image:: /tutorials/intermediate/images/thumb/sphx_glr_imshow_extent_thumb.png
    :alt: *origin* and *extent* in `~.Axes.imshow`

  :ref:`sphx_glr_tutorials_intermediate_imshow_extent.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">*origin* and *extent* in `~.Axes.imshow`</div>
    </div>


.. raw:: html

    </div>


Advanced
--------

These tutorials cover advanced topics for experienced Matplotlib
users and developers.



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="*Blitting* is a `standard technique &lt;https://en.wikipedia.org/wiki/Bit_blit&gt;`__ in raster graph...">

.. only:: html

  .. image:: /tutorials/advanced/images/thumb/sphx_glr_blitting_thumb.png
    :alt: Faster rendering by using blitting

  :ref:`sphx_glr_tutorials_advanced_blitting.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Faster rendering by using blitting</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Defining paths in your Matplotlib visualization.">

.. only:: html

  .. image:: /tutorials/advanced/images/thumb/sphx_glr_path_tutorial_thumb.png
    :alt: Path Tutorial

  :ref:`sphx_glr_tutorials_advanced_path_tutorial.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Path Tutorial</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Defining paths that objects follow on a canvas.">

.. only:: html

  .. image:: /tutorials/advanced/images/thumb/sphx_glr_patheffects_guide_thumb.png
    :alt: Path effects guide

  :ref:`sphx_glr_tutorials_advanced_patheffects_guide.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Path effects guide</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Like any graphics packages, Matplotlib is built on top of a transformation framework to easily ...">

.. only:: html

  .. image:: /tutorials/advanced/images/thumb/sphx_glr_transforms_tutorial_thumb.png
    :alt: Transformations Tutorial

  :ref:`sphx_glr_tutorials_advanced_transforms_tutorial.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Transformations Tutorial</div>
    </div>


.. raw:: html

    </div>


Colors
------

Matplotlib has support for visualizing information with a wide array
of colors and colormaps. These tutorials cover the basics of how
these colormaps look, how you can create your own, and how you can
customize colormaps for your use case.

For even more information see the :ref:`examples page <color_examples>`.



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Matplotlib recognizes the following formats to specify a color.">

.. only:: html

  .. image:: /tutorials/colors/images/thumb/sphx_glr_colors_thumb.png
    :alt: Specifying Colors

  :ref:`sphx_glr_tutorials_colors_colors.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Specifying Colors</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to build and customize standalone colorbars, i.e. without an attached p...">

.. only:: html

  .. image:: /tutorials/colors/images/thumb/sphx_glr_colorbar_only_thumb.png
    :alt: Customized Colorbars Tutorial

  :ref:`sphx_glr_tutorials_colors_colorbar_only.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Customized Colorbars Tutorial</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Matplotlib has a number of built-in colormaps accessible via .matplotlib.colormaps.  There are ...">

.. only:: html

  .. image:: /tutorials/colors/images/thumb/sphx_glr_colormap-manipulation_thumb.png
    :alt: Creating Colormaps in Matplotlib

  :ref:`sphx_glr_tutorials_colors_colormap-manipulation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating Colormaps in Matplotlib</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Objects that use colormaps by default linearly map the colors in the colormap from data values ...">

.. only:: html

  .. image:: /tutorials/colors/images/thumb/sphx_glr_colormapnorms_thumb.png
    :alt: Colormap Normalization

  :ref:`sphx_glr_tutorials_colors_colormapnorms.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Colormap Normalization</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Matplotlib has a number of built-in colormaps accessible via .matplotlib.colormaps.  There are ...">

.. only:: html

  .. image:: /tutorials/colors/images/thumb/sphx_glr_colormaps_thumb.png
    :alt: Choosing Colormaps in Matplotlib

  :ref:`sphx_glr_tutorials_colors_colormaps.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Choosing Colormaps in Matplotlib</div>
    </div>


.. raw:: html

    </div>


Provisional
-----------

These tutorials cover proposed APIs of any complexity.  These are here
to document features that we have released, but want to get user
feedback on before committing to them.  Please have a look, try them
out and give us feedback on `gitter
<https://gitter.im/matplotlib/matplotlib>`__, `discourse
<https://discourse.matplotlib.org>`__, or the `the mailing list
<https://mail.python.org/mailman/listinfo/matplotlib-users>`__! But,
be aware that we may change the APIs without warning in subsequent
versions.



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="   This tutorial documents experimental / provisional API.    We are releasing this in v3.3 to ...">

.. only:: html

  .. image:: /tutorials/provisional/images/thumb/sphx_glr_mosaic_thumb.png
    :alt: Complex and semantic figure composition

  :ref:`sphx_glr_tutorials_provisional_mosaic.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Complex and semantic figure composition</div>
    </div>


.. raw:: html

    </div>


Text
----

matplotlib has extensive text support, including support for
mathematical expressions, truetype support for raster and
vector outputs, newline separated text with arbitrary
rotations, and Unicode support. These tutorials cover
the basics of working with text in Matplotlib.



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Introduction to plotting and working with text in Matplotlib.">

.. only:: html

  .. image:: /tutorials/text/images/thumb/sphx_glr_text_intro_thumb.png
    :alt: Text in Matplotlib Plots

  :ref:`sphx_glr_tutorials_text_text_intro.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Text in Matplotlib Plots</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Controlling properties of text and its layout with Matplotlib.">

.. only:: html

  .. image:: /tutorials/text/images/thumb/sphx_glr_text_props_thumb.png
    :alt: Text properties and layout

  :ref:`sphx_glr_tutorials_text_text_props.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Text properties and layout</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Annotating text with Matplotlib.">

.. only:: html

  .. image:: /tutorials/text/images/thumb/sphx_glr_annotations_thumb.png
    :alt: Annotations

  :ref:`sphx_glr_tutorials_text_annotations.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Annotations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="You can use a subset of TeX markup in any Matplotlib text string by placing it inside a pair of...">

.. only:: html

  .. image:: /tutorials/text/images/thumb/sphx_glr_mathtext_thumb.png
    :alt: Writing mathematical expressions

  :ref:`sphx_glr_tutorials_text_mathtext.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Writing mathematical expressions</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Using the pgf backend, Matplotlib can export figures as pgf drawing commands that can be proces...">

.. only:: html

  .. image:: /tutorials/text/images/thumb/sphx_glr_pgf_thumb.png
    :alt: Text rendering with XeLaTeX/LuaLaTeX via the ``pgf`` backend

  :ref:`sphx_glr_tutorials_text_pgf.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Text rendering with XeLaTeX/LuaLaTeX via the ``pgf`` backend</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Matplotlib can use LaTeX to render text.  This is activated by setting text.usetex : True in yo...">

.. only:: html

  .. image:: /tutorials/text/images/thumb/sphx_glr_usetex_thumb.png
    :alt: Text rendering with LaTeX

  :ref:`sphx_glr_tutorials_text_usetex.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Text rendering with LaTeX</div>
    </div>


.. raw:: html

    </div>


Toolkits
--------

These tutorials cover toolkits designed to extend the functionality
of Matplotlib in order to accomplish specific goals.



.. raw:: html

    <div class="sphx-glr-thumbnails">


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip=".axes_grid1 provides the following features:">

.. only:: html

  .. image:: /tutorials/toolkits/images/thumb/sphx_glr_axes_grid_thumb.png
    :alt: Overview of :mod:`mpl_toolkits.axes_grid1`

  :ref:`sphx_glr_tutorials_toolkits_axes_grid.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Overview of :mod:`mpl_toolkits.axes_grid1`</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The axisartist toolkit tutorial.">

.. only:: html

  .. image:: /tutorials/toolkits/images/thumb/sphx_glr_axisartist_thumb.png
    :alt: Overview of axisartist toolkit

  :ref:`sphx_glr_tutorials_toolkits_axisartist.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Overview of axisartist toolkit</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Generating 3D plots using the mplot3d toolkit.">

.. only:: html

  .. image:: /tutorials/toolkits/images/thumb/sphx_glr_mplot3d_thumb.png
    :alt: The mplot3d Toolkit

  :ref:`sphx_glr_tutorials_toolkits_mplot3d.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The mplot3d Toolkit</div>
    </div>


.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:

   /tutorials/introductory/index.rst
   /tutorials/intermediate/index.rst
   /tutorials/advanced/index.rst
   /tutorials/colors/index.rst
   /tutorials/provisional/index.rst
   /tutorials/text/index.rst
   /tutorials/toolkits/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: tutorials_python.zip </tutorials/tutorials_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: tutorials_jupyter.zip </tutorials/tutorials_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_