<divid="unreleased-message"> You are reading an old version of the documentation (v1.4.0). For the latest version see <ahref="/stable/">https://matplotlib.org/stable/</a></div>
<li><aclass="reference internal" href="#controlling-the-legend-entries">Controlling the legend entries</a></li>
<li><aclass="reference internal" href="#creating-artists-specifically-for-adding-to-the-legend-aka-proxy-artists">Creating artists specifically for adding to the legend (aka. Proxy artists)</a></li>
<spanid="plotting-guide-legend"></span><h1>Legend guide<aclass="headerlink" href="#legend-guide" title="Permalink to this headline">¶</a></h1>
<p>This legend guide is an extension of the documentation available at
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.legend" title="matplotlib.pyplot.legend"><ttclass="xref py py-func docutils literal"><spanclass="pre">legend()</span></tt></a> - please ensure you are familiar with
contents of that documentation before proceeding with this guide.</p>
<p>This guide makes use of some common terms, which are documented here for clarity:</p>
<dlclass="glossary docutils">
<dtid="term-legend-entry">legend entry</dt>
<dd>A legend is made up of one or more legend entries. An entry is made up of
exactly one key and one label.</dd>
<dtid="term-legend-key">legend key</dt>
<dd>The colored/patterned marker to the left of each legend label.</dd>
<dtid="term-legend-label">legend label</dt>
<dd>The text which describes the handle represented by the key.</dd>
<dtid="term-legend-handle">legend handle</dt>
<dd>The original object which is used to generate an appropriate entry in
a list of handles/artists which exist on the Axes which can be used to
generate entries for the resulting legend - it is worth noting however that
not all artists can be added to a legend, at which point a “proxy” will have
to be created (see <aclass="reference internal" href="#proxy-legend-handles"><em>Creating artists specifically for adding to the legend (aka. Proxy artists)</em></a> for further details).</p>
<p>For full control of what is being added to the legend, it is common to pass
the appropriate handles directly to <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.legend" title="matplotlib.pyplot.legend"><ttclass="xref py py-func docutils literal"><spanclass="pre">legend()</span></tt></a>:</p>
<p>In some cases, it is not possible to set the label of the handle, so it is
possible to pass through the list of labels to <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.legend" title="matplotlib.pyplot.legend"><ttclass="xref py py-func docutils literal"><spanclass="pre">legend()</span></tt></a>:</p>
<spanid="proxy-legend-handles"></span><h2>Creating artists specifically for adding to the legend (aka. Proxy artists)<aclass="headerlink" href="#creating-artists-specifically-for-adding-to-the-legend-aka-proxy-artists" title="Permalink to this headline">¶</a></h2>
<p>Not all handles can be turned into legend entries automatically,
so it is often necessary to create an artist which <em>can</em>. Legend handles
don’t have to exists on the Figure or Axes in order to be used.</p>
<p>Suppose we wanted to create a legend which has an entry for some data which
<spanclass="n">red_patch</span><spanclass="o">=</span><spanclass="n">mpatches</span><spanclass="o">.</span><spanclass="n">Patch</span><spanclass="p">(</span><spanclass="n">color</span><spanclass="o">=</span><spanclass="s">'red'</span><spanclass="p">,</span><spanclass="n">label</span><spanclass="o">=</span><spanclass="s">'The red data'</span><spanclass="p">)</span>
<h2>Legend location<aclass="headerlink" href="#legend-location" title="Permalink to this headline">¶</a></h2>
<p>The location of the legend can be specified by the keyword argument
<em>loc</em>. Please see the documentation at <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.legend" title="matplotlib.pyplot.legend"><ttclass="xref py py-func docutils literal"><spanclass="pre">legend()</span></tt></a> for more details.</p>
<p>The <ttclass="docutils literal"><spanclass="pre">bbox_to_anchor</span></tt> keyword gives a great degree of control for manual
legend placement. For example, if you want your axes legend located at the
figure’s top right-hand corner instead of the axes’ corner, simply specify
the corner’s location, and the coordinate system of that location:</p>
<h2>Multiple legends on the same Axes<aclass="headerlink" href="#multiple-legends-on-the-same-axes" title="Permalink to this headline">¶</a></h2>
<p>Sometimes it is more clear to split legend entries across multiple
legends. Whilst the instinctive approach to doing this might be to call
the <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.legend" title="matplotlib.pyplot.legend"><ttclass="xref py py-func docutils literal"><spanclass="pre">legend()</span></tt></a> function multiple times, you will find that only one
legend ever exists on the Axes. This has been done so that it is possible
to call <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.legend" title="matplotlib.pyplot.legend"><ttclass="xref py py-func docutils literal"><spanclass="pre">legend()</span></tt></a> repeatedly to update the legend to the latest
handles on the Axes, so to persist old legend instances, we must add them
with the value in the <ttclass="docutils literal"><spanclass="pre">handler_map</span></tt> keyword.</li>
<li>Check if the <ttclass="docutils literal"><spanclass="pre">handle</span></tt> is in the newly created <ttclass="docutils literal"><spanclass="pre">handler_map</span></tt>.</li>
<li>Check if the type of <ttclass="docutils literal"><spanclass="pre">handle</span></tt> is in the newly created
which accepts a <ttclass="docutils literal"><spanclass="pre">numpoints</span></tt> argument (note numpoints is a keyword
on the <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.legend" title="matplotlib.pyplot.legend"><ttclass="xref py py-func docutils literal"><spanclass="pre">legend()</span></tt></a> function for convenience). We can then pass the mapping
of instance to Handler as a keyword to legend.</p>
<p>As you can see, “Line 1” now has 4 marker points, where “Line 2” has 2 (the
default). Try the above code, only change the map’s key from <ttclass="docutils literal"><spanclass="pre">line1</span></tt> to
<ttclass="docutils literal"><spanclass="pre">type(line1)</span></tt>. Notice how now both <aclass="reference internal" href="../api/lines_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><ttclass="xref py py-class docutils literal"><spanclass="pre">Line2D</span></tt></a> instances
get 4 markers.</p>
<p>Along with handlers for complex plot types such as errorbars, stem plots
and histograms, the default <ttclass="docutils literal"><spanclass="pre">handler_map</span></tt> has a special <ttclass="docutils literal"><spanclass="pre">tuple</span></tt> handler
<h3>Implementing a custom legend handler<aclass="headerlink" href="#implementing-a-custom-legend-handler" title="Permalink to this headline">¶</a></h3>
<p>A custom handler can be implemented to turn any handle into a legend key (handles
don’t necessarily need to be matplotlib artists).
The handler must implement a “legend_artist” method which returns a
single artist for the legend to use. Signature details about the “legend_artist”
are documented at <aclass="reference internal" href="../api/legend_api.html#matplotlib.legend_handler.HandlerBase.legend_artist" title="matplotlib.legend_handler.HandlerBase.legend_artist"><ttclass="xref py py-meth docutils literal"><spanclass="pre">legend_artist()</span></tt></a>.</p>
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">legend</span><spanclass="p">([</span><spanclass="n">AnyObject</span><spanclass="p">()],</span><spanclass="p">[</span><spanclass="s">'My first handler'</span><spanclass="p">],</span>
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">legend</span><spanclass="p">([</span><spanclass="n">c</span><spanclass="p">],</span><spanclass="p">[</span><spanclass="s">"An ellipse, not a rectangle"</span><spanclass="p">],</span>