Select the backend used for rendering and GUI integration. If pyplot is already imported, `~matplotlib.pyplot.switch_backend` is used to switch the backend. Parameters ---------- backend : str The backend to switch to. This can either be one of the standard
(backend, *, force=True)
| 1214 | |
| 1215 | |
| 1216 | def use(backend, *, force=True): |
| 1217 | """ |
| 1218 | Select the backend used for rendering and GUI integration. |
| 1219 | |
| 1220 | If pyplot is already imported, `~matplotlib.pyplot.switch_backend` is used |
| 1221 | to switch the backend. |
| 1222 | |
| 1223 | Parameters |
| 1224 | ---------- |
| 1225 | backend : str |
| 1226 | The backend to switch to. This can either be one of the standard |
| 1227 | backend names, which are case-insensitive: |
| 1228 | |
| 1229 | - interactive backends: |
| 1230 | GTK3Agg, GTK3Cairo, GTK4Agg, GTK4Cairo, MacOSX, nbAgg, notebook, QtAgg, |
| 1231 | QtCairo, TkAgg, TkCairo, WebAgg, WX, WXAgg, WXCairo, Qt5Agg, Qt5Cairo |
| 1232 | |
| 1233 | - non-interactive backends: |
| 1234 | agg, cairo, pdf, pgf, ps, svg, template |
| 1235 | |
| 1236 | or a string of the form: ``module://my.module.name``. |
| 1237 | |
| 1238 | notebook is a synonym for nbAgg. |
| 1239 | |
| 1240 | Switching to an interactive backend is not possible if an unrelated |
| 1241 | event loop has already been started (e.g., switching to GTK3Agg if a |
| 1242 | TkAgg window has already been opened). Switching to a non-interactive |
| 1243 | backend is always possible. |
| 1244 | |
| 1245 | force : bool, default: True |
| 1246 | If True (the default), raise an `ImportError` if the backend cannot be |
| 1247 | set up (either because it fails to import, or because an incompatible |
| 1248 | GUI interactive framework is already running); if False, silently |
| 1249 | ignore the failure. |
| 1250 | |
| 1251 | See Also |
| 1252 | -------- |
| 1253 | :ref:`backends` |
| 1254 | matplotlib.get_backend |
| 1255 | matplotlib.pyplot.switch_backend |
| 1256 | |
| 1257 | """ |
| 1258 | name = rcsetup.validate_backend(backend) |
| 1259 | # don't (prematurely) resolve the "auto" backend setting |
| 1260 | if rcParams._get_backend_or_none() == name: |
| 1261 | # Nothing to do if the requested backend is already set |
| 1262 | pass |
| 1263 | else: |
| 1264 | # if pyplot is not already imported, do not import it. Doing |
| 1265 | # so may trigger a `plt.switch_backend` to the _default_ backend |
| 1266 | # before we get a chance to change to the one the user just requested |
| 1267 | plt = sys.modules.get('matplotlib.pyplot') |
| 1268 | # if pyplot is imported, then try to change backends |
| 1269 | if plt is not None: |
| 1270 | try: |
| 1271 | # we need this import check here to re-raise if the |
| 1272 | # user does not have the libraries to support their |
| 1273 | # chosen backend installed. |
nothing calls this directly
no test coverage detected