|
| 1 | +Troubleshooting |
| 2 | +=============== |
| 3 | + |
| 4 | +.. _slow-first-plot: |
| 5 | + |
| 6 | +Slow first plot |
| 7 | +--------------- |
| 8 | + |
| 9 | +The first plot in a fresh environment can take several seconds while Matplotlib |
| 10 | +scans installed fonts and builds its font cache. You may see the message |
| 11 | +``Matplotlib is building the font cache; this may take a moment``. The time |
| 12 | +depends on the system and the installed fonts. |
| 13 | + |
| 14 | +SpatialMath imports Matplotlib's plotting interface lazily, so this cost is |
| 15 | +usually deferred until plotting is first requested. A fast ``import spatialmath`` |
| 16 | +does not mean that the font cache is already populated. If the delay recurs in |
| 17 | +each new process, check whether the cache directory is writable and persists |
| 18 | +between runs, especially in containers, CI runners and sandboxes. |
| 19 | + |
| 20 | +Find the cache directory |
| 21 | +^^^^^^^^^^^^^^^^^^^^^^^^ |
| 22 | + |
| 23 | +Use the same Python environment as your application: |
| 24 | + |
| 25 | +.. code-block:: shell |
| 26 | +
|
| 27 | + python -c "import matplotlib; print(matplotlib.get_cachedir())" |
| 28 | +
|
| 29 | +``MPLCONFIGDIR`` overrides the directory used for Matplotlib's configuration and |
| 30 | +cache. Set it **before importing Matplotlib**. If the usual directories are not |
| 31 | +writable, Matplotlib can fall back to a temporary directory, which may prevent |
| 32 | +reuse between runs. See Matplotlib's |
| 33 | +`environment variable documentation <https://matplotlib.org/stable/install/environment_variables_faq.html#envvar-MPLCONFIGDIR>`_ |
| 34 | +for platform-specific defaults. |
| 35 | + |
| 36 | +Keep and prepopulate the cache |
| 37 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 38 | + |
| 39 | +For a Linux or macOS shell, choose a persistent, writable directory and run a |
| 40 | +one-time warm-up: |
| 41 | + |
| 42 | +.. code-block:: shell |
| 43 | +
|
| 44 | + export MPLCONFIGDIR="$HOME/.cache/spatialmath-matplotlib" |
| 45 | + mkdir -p "$MPLCONFIGDIR" |
| 46 | + MPLBACKEND=Agg python -c "import matplotlib.pyplot" |
| 47 | +
|
| 48 | +Use the same ``MPLCONFIGDIR`` when running the application. The warm-up still |
| 49 | +pays the initial scan cost; retaining the cache lets later processes reuse it. |
| 50 | +``Agg`` allows this command to run without a display and is selected only for |
| 51 | +the warm-up command, so it does not change the application's plotting backend. |
| 52 | + |
| 53 | +* **Docker:** after installing Matplotlib and the image's fonts, prepopulate the |
| 54 | + cache during the image build: |
| 55 | + |
| 56 | + .. code-block:: dockerfile |
| 57 | +
|
| 58 | + RUN MPLBACKEND=Agg python -c "import matplotlib.pyplot" |
| 59 | +
|
| 60 | + The build step and application must use the same cache directory, with |
| 61 | + appropriate permissions for the runtime user. A cache built in root's home |
| 62 | + will not help an application using another user's default cache directory. |
| 63 | + A volume mounted over the populated directory also hides the built-in cache. |
| 64 | + |
| 65 | +* **CI:** restore the cache directory before the first plot or warm-up command, |
| 66 | + and save it afterwards using the CI system's cache facility. Include the |
| 67 | + operating system and Matplotlib version in the cache key, and refresh it when |
| 68 | + the installed fonts change. |
| 69 | + |
| 70 | +* **Sandboxes:** configure ``MPLCONFIGDIR`` to point to a writable directory that |
| 71 | + survives between runs, rather than a temporary directory recreated each time. |
0 commit comments