Skip to content

Commit 4a68cb2

Browse files
jklymakjklymak
committed
DOC: some debug steps for backend issues
1 parent 4c73219 commit 4a68cb2

File tree

4 files changed

+286
-11
lines changed

4 files changed

+286
-11
lines changed

‎doc/users/faq.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@
88
Frequently Asked Questions
99
==========================
1010

11+
.. _how-do-no-figure:
12+
13+
I don't see a figure window
14+
---------------------------
15+
16+
Please see :ref:`figures_not_showing`.
17+
1118
.. _how-to-too-many-ticks:
1219

1320
Why do I have so many ticks, and/or why are they out of order?
@@ -301,6 +308,7 @@ you must in that case use a *non-interactive backend* (typically Agg), because
301308
most GUI backends *require* being run from the main thread as well.
302309

303310
.. _reporting-problems:
311+
.. _get-help:
304312

305313
Get help
306314
--------

‎doc/users/faq/troubleshooting_faq.rst

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
.. _troubleshooting-faq:
2+
3+
.. redirect-from:: /faq/troubleshooting_faq
4+
5+
***************
6+
Troubleshooting
7+
***************
8+
9+
.. contents::
10+
:backlinks: none
11+
12+
.. _matplotlib-version:
13+
14+
Obtaining Matplotlib version
15+
============================
16+
17+
To find out your Matplotlib version number, import it and print the
18+
``__version__`` attribute::
19+
20+
>>> import matplotlib
21+
>>> matplotlib.__version__
22+
'0.98.0'
23+
24+
25+
.. _locating-matplotlib-install:
26+
27+
:file:`matplotlib` install location
28+
===================================
29+
30+
You can find what directory Matplotlib is installed in by importing it
31+
and printing the ``__file__`` attribute::
32+
33+
>>> import matplotlib
34+
>>> matplotlib.__file__
35+
'/home/jdhunter/dev/lib64/python2.5/site-packages/matplotlib/__init__.pyc'
36+
37+
.. _locating-matplotlib-config-dir:
38+
39+
:file:`matplotlib` configuration and cache directory locations
40+
==============================================================
41+
42+
Each user has a Matplotlib configuration directory which may contain a
43+
:ref:`matplotlibrc <customizing-with-matplotlibrc-files>` file. To
44+
locate your :file:`matplotlib/` configuration directory, use
45+
:func:`matplotlib.get_configdir`::
46+
47+
>>> import matplotlib as mpl
48+
>>> mpl.get_configdir()
49+
'/home/darren/.config/matplotlib'
50+
51+
On Unix-like systems, this directory is generally located in your
52+
:envvar:`HOME` directory under the :file:`.config/` directory.
53+
54+
In addition, users have a cache directory. On Unix-like systems, this is
55+
separate from the configuration directory by default. To locate your
56+
:file:`.cache/` directory, use :func:`matplotlib.get_cachedir`::
57+
58+
>>> import matplotlib as mpl
59+
>>> mpl.get_cachedir()
60+
'/home/darren/.cache/matplotlib'
61+
62+
On Windows, both the config directory and the cache directory are
63+
the same and are in your :file:`Documents and Settings` or :file:`Users`
64+
directory by default::
65+
66+
>>> import matplotlib as mpl
67+
>>> mpl.get_configdir()
68+
'C:\\Documents and Settings\\jdhunter\\.matplotlib'
69+
>>> mpl.get_cachedir()
70+
'C:\\Documents and Settings\\jdhunter\\.matplotlib'
71+
72+
If you would like to use a different configuration directory, you can
73+
do so by specifying the location in your :envvar:`MPLCONFIGDIR`
74+
environment variable -- see
75+
:ref:`setting-linux-osx-environment-variables`. Note that
76+
:envvar:`MPLCONFIGDIR` sets the location of both the configuration
77+
directory and the cache directory.
78+
79+
.. _reporting-problems:
80+
.. _getting-help:
81+
82+
Getting help
83+
============
84+
85+
There are a number of good resources for getting help with Matplotlib.
86+
There is a good chance your question has already been asked:
87+
88+
- The `mailing list archive
89+
<https://discourse.matplotlib.org/c/community/matplotlib-users/6>`_.
90+
91+
- `GitHub issues <https://github.com/matplotlib/matplotlib/issues>`_.
92+
93+
- Stackoverflow questions tagged `matplotlib
94+
<https://stackoverflow.com/questions/tagged/matplotlib>`_.
95+
96+
If you are unable to find an answer to your question through search, please
97+
provide the following information in your e-mail to the `mailing list
98+
<https://mail.python.org/mailman/listinfo/matplotlib-users>`_:
99+
100+
* Your operating system (Linux/Unix users: post the output of ``uname -a``).
101+
102+
* Matplotlib version::
103+
104+
python -c "import matplotlib; print(matplotlib.__version__)"
105+
106+
* Where you obtained Matplotlib (e.g., your Linux distribution's packages,
107+
GitHub, PyPI, or `Anaconda <https://www.anaconda.com/>`_).
108+
109+
* Any customizations to your ``matplotlibrc`` file (see
110+
:ref:`customizing`).
111+
112+
* If the problem is reproducible, please try to provide a *minimal*, standalone
113+
Python script that demonstrates the problem. This is *the* critical step.
114+
If you can't post a piece of code that we can run and reproduce your error,
115+
the chances of getting help are significantly diminished. Very often, the
116+
mere act of trying to minimize your code to the smallest bit that produces
117+
the error will help you find a bug in *your* code that is causing the
118+
problem.
119+
120+
* Matplotlib provides debugging information through the `logging` library, and
121+
a helper function to set the logging level: one can call ::
122+
123+
plt.set_loglevel("info") # or "debug" for more info
124+
125+
to obtain this debugging information.
126+
127+
Standard functions from the `logging` module are also applicable; e.g. one
128+
could call ``logging.basicConfig(level="DEBUG")`` even before importing
129+
Matplotlib (this is in particular necessary to get the logging info emitted
130+
during Matplotlib's import), or attach a custom handler to the "matplotlib"
131+
logger. This may be useful if you use a custom logging configuration.
132+
133+
If you compiled Matplotlib yourself, please also provide:
134+
135+
* any changes you have made to ``setup.py`` or ``setupext.py``.
136+
* the output of::
137+
138+
rm -rf build
139+
python setup.py build
140+
141+
The beginning of the build output contains lots of details about your
142+
platform that are useful for the Matplotlib developers to diagnose your
143+
problem.
144+
145+
* your compiler version -- e.g., ``gcc --version``.
146+
147+
Including this information in your first e-mail to the mailing list
148+
will save a lot of time.
149+
150+
You will likely get a faster response writing to the mailing list than
151+
filing a bug in the bug tracker. Most developers check the bug
152+
tracker only periodically. If your problem has been determined to be
153+
a bug and cannot be quickly solved, you may be asked to file a bug in
154+
the tracker so the issue doesn't get lost.
155+
156+
.. _git-trouble:
157+
158+
Problems with recent git versions
159+
=================================
160+
161+
First, make sure you have a clean build and install (see :ref:`clean-install`),
162+
get the latest git update, install it and run a simple test script in debug
163+
mode::
164+
165+
rm -rf /path/to/site-packages/matplotlib*
166+
git clean -xdf
167+
git pull
168+
python -m pip install -v . > build.out
169+
python -c "from pylab import *; set_loglevel('debug'); plot(); show()" > run.out
170+
171+
and post :file:`build.out` and :file:`run.out` to the `matplotlib-devel
172+
<https://mail.python.org/mailman/listinfo/matplotlib-devel>`_
173+
mailing list (please do not post git problems to the `users list
174+
<https://mail.python.org/mailman/listinfo/matplotlib-users>`_).
175+
176+
Of course, you will want to clearly describe your problem, what you
177+
are expecting and what you are getting, but often a clean build and
178+
install will help. See also :ref:`reporting-problems`.
179+

‎galleries/users_explain/figure/backends.rst

Lines changed: 94 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,17 @@ Backends
1111
What is a backend?
1212
------------------
1313

14-
A lot of documentation on the website and in the mailing lists refers
15-
to the "backend" and many new users are confused by this term.
16-
Matplotlib targets many different use cases and output formats. Some
17-
people use Matplotlib interactively from the Python shell and have
18-
plotting windows pop up when they type commands. Some people run
19-
`Jupyter <https://jupyter.org>`_ notebooks and draw inline plots for
20-
quick data analysis. Others embed Matplotlib into graphical user
21-
interfaces like PyQt or PyGObject to build rich applications. Some
22-
people use Matplotlib in batch scripts to generate postscript images
23-
from numerical simulations, and still others run web application
24-
servers to dynamically serve up graphs.
14+
Backends are used for displaying Matplotlib figures (see :ref:`figure-intro`),
15+
on the screen, or for writing to files. A lot of documentation on the website
16+
and in the mailing lists refers to the "backend" and many new users are
17+
confused by this term. Matplotlib targets many different use cases and output
18+
formats. Some people use Matplotlib interactively from the Python shell and
19+
have plotting windows pop up when they type commands. Some people run `Jupyter
20+
<https://jupyter.org>`_ notebooks and draw inline plots for quick data
21+
analysis. Others embed Matplotlib into graphical user interfaces like PyQt or
22+
PyGObject to build rich applications. Some people use Matplotlib in batch
23+
scripts to generate postscript images from numerical simulations, and still
24+
others run web application servers to dynamically serve up graphs.
2525

2626
To support all of these use cases, Matplotlib can target different
2727
outputs, and each of these capabilities is called a backend; the
@@ -248,3 +248,86 @@ backend, use ``module://name.of.the.backend`` as the backend name, e.g.
248248
``matplotlib.use('module://name.of.the.backend')``.
249249

250250
Information for backend implementers is available at :ref:`writing_backend_interface`.
251+
252+
.. _figures_not_showing:
253+
254+
Debugging the figure windows not showing
255+
----------------------------------------
256+
257+
Sometimes things do not work as expected, usually during an install.
258+
259+
If you are using a Notebook or integrated development environment (see :ref:`notebooks-and-ides`),
260+
please consult their documentation for debugging figures not working in their
261+
environments.
262+
263+
If you are using one of Matplotlib's graphics backends (see :ref:`standalone-scripts-and-interactive-use`), make sure you know which
264+
one is being used:
265+
266+
.. code-block:: python3
267+
268+
import matplotlib
269+
270+
print(matplotlib.get_backend())
271+
272+
Try a simple plot to see if the GUI opens:
273+
274+
.. code-block:: python3
275+
276+
import matplotlib
277+
import matplotlib.pyplot as plt
278+
279+
print(matplotlib.get_backend())
280+
plt.plot((1, 4, 6))
281+
plt.show()
282+
283+
If it does not, you perhaps have an installation problem. A good step at this
284+
point is to ensure that your GUI toolkit is installed properly, taking
285+
Matplotlib out of the testing. Almost all GUI toolkits have a small test
286+
program that can be run to test basic functionality. If this test fails, try re-installing.
287+
288+
QtAgg
289+
^^^^^
290+
291+
Test ``PyQt5``:
292+
293+
.. code-block:: bash
294+
295+
python -c "from PyQt5.QtWidgets import *; app = QApplication([]); win = QMainWindow(); win.show(); app.exec()"
296+
297+
If you have ``PySide`` or ``PyQt6`` installed rather than ``PyQt5``, just change the import
298+
accordingly.
299+
300+
TkAgg
301+
^^^^^
302+
303+
Test ``tkinter``:
304+
305+
.. code-block:: bash
306+
307+
python3 -c "from tkinter import Tk; Tk().mainloop()"
308+
309+
GTK3Agg, GTK4Agg, GTK3Cairo, GTK4Cairo
310+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
311+
312+
Test ``Gtk``:
313+
314+
.. code-block:: bash
315+
316+
python3 -c "from gi.repository import Gtk; win = Gtk.Window(); win.connect('destroy', Gtk.main_quit); win.show(); Gtk.main()"
317+
318+
wxAgg
319+
^^^^^
320+
321+
Test ``wx``:
322+
323+
.. code-block:: python3
324+
325+
import wx
326+
327+
app = wx.App(False) # Create a new app, don't redirect stdout/stderr to a window.
328+
frame = wx.Frame(None, wx.ID_ANY, "Hello World") # A Frame is a top-level window.
329+
frame.Show(True) # Show the frame.
330+
app.MainLoop()
331+
332+
If the test works for your desired backend but you still cannot get Matplotlib to display a figure, then contact us (see
333+
:ref:`get-help`).

‎galleries/users_explain/figure/figure_intro.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
.. redirect-from:: /users/explain/figure
33

44
.. _figure_explanation:
5+
.. _figure-intro:
56

67
+++++++++++++++++++++++
78
Introduction to Figures
@@ -36,6 +37,8 @@ We will discuss how to create Figures in more detail below, but first it is
3637
helpful to understand how to view a Figure. This varies based on how you are
3738
using Matplotlib, and what :ref:`Backend <what-is-a-backend>` you are using.
3839

40+
.. _notebooks-and-ides:
41+
3942
Notebooks and IDEs
4043
------------------
4144

@@ -73,6 +76,8 @@ other than the default "inline" backend, you will likely need to use an ipython
7376
.. seealso::
7477
:ref:`interactive_figures`.
7578

79+
.. _standalone-scripts-and-interactive-use:
80+
7681
Standalone scripts and interactive use
7782
--------------------------------------
7883

0 commit comments

Comments
 (0)