.. _environment-variables:

.. redirect-from:: /faq/installing_faq .. redirect-from:: /users/faq/installing_faq .. redirect-from:: /users/installing/environment_variables_faq

===================== Environment variables

.. envvar:: HOME

The user's home directory. On Linux, :envvar:~ <HOME> is shorthand for :envvar:HOME.

.. envvar:: MPLBACKEND

This optional variable can be set to choose the Matplotlib backend. See :ref:what-is-a-backend.

.. envvar:: MPLCONFIGDIR

This is the directory used to store user customizations to Matplotlib, as well as some caches to improve performance. If :envvar:MPLCONFIGDIR is not defined, :file:{HOME}/.config/matplotlib and :file:{HOME}/.cache/matplotlib are used on Linux, and :file:{HOME}/.matplotlib on other platforms, if they are writable. Otherwise, the Python standard library's tempfile.gettempdir is used to find a base directory in which the :file:matplotlib subdirectory is created.

.. envvar:: MPL_IGNORE_SYSTEM_FONTS

When this variable is set, Matplotlib will update its font cache only with its own directories. This can be used to limit subprocess usage for querying system fonts.

.. envvar:: PATH

The list of directories searched to find executable programs.

.. envvar:: PYTHONPATH

The list of directories that are added to Python's standard search list when importing packages and modules.

.. envvar:: QT_API

The Python Qt wrapper to prefer when using Qt-based backends. See :ref:the entry in the usage guide <QT_bindings> for more information.

.. _setting-linux-macos-environment-variables:

Setting environment variables in Linux and macOS

To list the current value of :envvar:PYTHONPATH, which may be empty, try::

echo $PYTHONPATH

The procedure for setting environment variables in depends on what your default shell is. Common shells include :program:bash and :program:csh. You should be able to determine which by running at the command prompt::

echo $SHELL

To create a new environment variable::

export PYTHONPATH=~/Python # bash/ksh setenv PYTHONPATH ~/Python # csh/tcsh

To prepend to an existing environment variable::

export PATH=~/bin:${PATH} # bash/ksh setenv PATH ~/bin:${PATH} # csh/tcsh

The search order may be important to you, do you want :file:~/bin to be searched first or last? To append to an existing environment variable::

export PATH=${PATH}:/bin # bash/ksh setenv PATH ${PATH}:/bin # csh/tcsh

To make your changes available in the future, add the commands to your :file:~/.bashrc or :file:~/.cshrc file.

.. _setting-windows-environment-variables:

Setting environment variables in Windows

Open the :program:Control Panel (:menuselection:Start --> Control Panel), start the :program:System program. Click the :guilabel:Advanced tab and select the :guilabel:Environment Variables button. You can edit or add to the :guilabel:User Variables.