1:orphan:
2
3.. title:: Matplotlib: Python plotting
4
5Matplotlib is a Python 2D plotting library which produces publication quality
6figures in a variety of hardcopy formats and interactive environments across
7platforms.  Matplotlib can be used in Python scripts, the Python and IPython_
8shells, the Jupyter_ notebook, web application servers, and four graphical user
9interface toolkits.
10
11.. _IPython: http://ipython.org
12.. _Jupyter: http://jupyter.org
13
14.. raw:: html
15
16   <div class="responsive_screenshots">
17      <a href="tutorials/introductory/sample_plots.html">
18         <div class="responsive_subfig">
19         <img align="middle" src="_images/sphx_glr_membrane_thumb.png"
20          border="0" alt="screenshots"/>
21         </div>
22         <div class="responsive_subfig">
23         <img align="middle" src="_images/sphx_glr_histogram_thumb.png"
24          border="0" alt="screenshots"/>
25         </div>
26         <div class="responsive_subfig">
27         <img align="middle" src="_images/sphx_glr_contour_thumb.png"
28          border="0" alt="screenshots"/>
29         </div>
30         <div class="responsive_subfig">
31         <img align="middle" src="_images/sphx_glr_3D_thumb.png"
32          border="0" alt="screenshots"/>
33         </div>
34      </a>
35   </div>
36   <span class="clear_screenshots"></span>
37
38Matplotlib tries to make easy things easy and hard things possible.  You
39can generate plots, histograms, power spectra, bar charts, errorcharts,
40scatterplots, etc., with just a few lines of code.  For examples, see the
41:doc:`sample plots <tutorials/introductory/sample_plots>` and :doc:`thumbnail
42gallery <gallery/index>`.
43
44For simple plotting the `pyplot` module provides a MATLAB-like interface,
45particularly when combined with IPython.  For the power user, you have full
46control of line styles, font properties, axes properties, etc, via an object
47oriented interface or via a set of functions familiar to MATLAB users.
48
49Installation
50------------
51
52Visit the :doc:`Matplotlib installation instructions <users/installing>`.
53
54Documentation
55-------------
56
57This is the documentation for Matplotlib version |version|.
58
59To get started, read the :doc:`User's Guide <users/index>`.
60
61.. raw:: html
62
63   <p id="other_versions"></p>
64
65   <script>
66   function getSnippet(id, url) {
67      var req = false;
68      // For Safari, Firefox, and other non-MS browsers
69      if (window.XMLHttpRequest) {
70         try {
71            req = new XMLHttpRequest();
72         } catch (e) {
73            req = false;
74         }
75      } else if (window.ActiveXObject) {
76         // For Internet Explorer on Windows
77         try {
78            req = new ActiveXObject("Msxml2.XMLHTTP");
79         } catch (e) {
80            try {
81            req = new ActiveXObject("Microsoft.XMLHTTP");
82            } catch (e) {
83            req = false;
84            }
85         }
86      }
87      var element = document.getElementById(id);
88      if (req) {
89         // Synchronous request, wait till we have it all
90         req.open('GET', url, false);
91         req.send(null);
92         if (req.status == 200) {
93            element.innerHTML = req.responseText;
94         } else {
95            element.innerHTML = "<mark>Could not find Snippet to insert at " + url + "</mark>"
96         }
97      }
98   }
99   getSnippet('other_versions', '/versions.html');
100   </script>
101
102Trying to learn how to do a particular kind of plot?  Check out the
103:doc:`examples gallery <gallery/index>` or the :doc:`list of plotting commands
104<api/pyplot_summary>`.
105
106Other learning resources
107~~~~~~~~~~~~~~~~~~~~~~~~
108
109There are many :doc:`external learning resources <resources/index>` available
110including printed material, videos and tutorials.
111
112Need help?
113~~~~~~~~~~
114
115Matplotlib is a welcoming, inclusive project, and we try to follow the `Python
116Software Foundation Code of Conduct <coc_>`_ in everything we do.
117
118.. _coc: http://www.python.org/psf/codeofconduct/
119
120Check the :doc:`FAQ <faq/index>` and the :doc:`API <api/index>` docs.
121
122For help, join the `gitter channel`_ and the matplotlib-users_,
123matplotlib-devel_, and matplotlib-announce_ mailing lists, or check out the
124Matplotlib tag on stackoverflow_.  The `search <search.html>`_ tool searches
125all of the documentation, including full text search of over 350 complete
126examples which exercise almost every corner of Matplotlib.
127
128.. _gitter channel: https://gitter.im/matplotlib/matplotlib
129.. _matplotlib-users: https://mail.python.org/mailman/listinfo/matplotlib-users
130.. _matplotlib-devel: https://mail.python.org/mailman/listinfo/matplotlib-devel
131.. _matplotlib-announce: https://mail.python.org/mailman/listinfo/matplotlib-announce
132.. _stackoverflow: http://stackoverflow.com/questions/tagged/matplotlib
133
134You can file bugs, patches and feature requests on the `issue tracker`_, but it
135is a good idea to ping us on the mailing list too.
136
137To keep up to date with what's going on in Matplotlib, see the :doc:`what's
138new <users/whats_new>` page or browse the `source code`_.  Anything that could
139require changes to your existing code is logged in the :doc:`API changes
140<api/api_changes>` file.
141
142Toolkits
143========
144
145Matplotlib ships with several add-on :doc:`toolkits <api/toolkits/index>`,
146including 3d plotting with `mplot3d`, axes helpers in `axes_grid1` and axis
147helpers in `axisartist`.
148
149Third party packages
150====================
151
152A large number of :doc:`third party packages <thirdpartypackages/index>`
153extend and build on Matplotlib functionality, including several higher-level
154plotting interfaces (seaborn_, holoviews_, ggplot_, ...), and two projection
155and mapping toolkits (basemap_ and cartopy_).
156
157.. _seaborn: https://seaborn.github.io/
158.. _holoviews: http://holoviews.org
159.. _ggplot: http://ggplot.yhathq.com
160.. _basemap: http://matplotlib.org/basemap
161.. _cartopy: http://scitools.org.uk/cartopy/docs/latest
162
163Citing Matplotlib
164=================
165
166Matplotlib is the brainchild of John Hunter (1968-2012), who, along with its
167many contributors, have put an immeasurable amount of time and effort into
168producing a piece of software utilized by thousands of scientists worldwide.
169
170If Matplotlib contributes to a project that leads to a scientific publication,
171please acknowledge this work by citing the project. A :doc:`ready-made citation
172entry <citing>` is available.
173
174Open source
175===========
176
177.. raw:: html
178
179   <a href="https://www.numfocus.org/">
180   <img src="_static/numfocus_badge.png"
181    alt="A Fiscally Sponsored Project of NUMFocus"
182    style="float:right; margin-left:20px" />
183   </a>
184
185Please consider `donating to the Matplotlib project <donating_>`_ through
186the Numfocus organization or to the `John Hunter Technology Fellowship
187<jdh-fellowship_>`_.
188
189.. _donating: https://www.flipcause.com/secure/cause_pdetails/MjI1OA==
190.. _jdh-fellowship: https://www.numfocus.org/programs/john-hunter-technology-fellowship/
191
192The :doc:`Matplotlib license <users/license>` is based on the `Python Software
193Foundation (PSF) license <psf-license_>`_.
194
195.. _psf-license: http://www.python.org/psf/license
196
197There is an active developer community and a long list of people who have made
198significant :doc:`contributions <users/credits>`.
199
200Matplotlib is hosted on `Github <source code_>`_.  `Issues <issue tracker_>`_
201and `Pull requests`_ are tracked at Github too.
202
203.. _source code: https://github.com/matplotlib/matplotlib
204.. _issue tracker: https://github.com/matplotlib/matplotlib/issues
205.. _pull requests: https://github.com/matplotlib/matplotlib/pulls
206