Attention

Version 3 is now the current version of MathJax. This document is for version 2.

Installing and Testing MathJax

The easiest way to use MathJax is to link directly to the MathJax distributed network service (see Using a Content Delivery Network (CDN)). In that case, there is no need to install MathJax yourself, and you can begin using MathJax right away; skip this document on installation and go directly to Configuring MathJax.

MathJax can be loaded from a public web server or privately from your hard drive or other local media. To use MathJax in either way, you will need to obtain a copy of MathJax. There are several ways to do this: via git, svn, npm, composer, bower, or via a pre-packaged archive. We recommend git or svn, as it is easier to keep your installation up to date with these tools.

Obtaining MathJax via Git

The easiest way to get MathJax and keep it up to date is to use the Git version control system to access our GitHub repository. Use the command

git clone https://github.com/mathjax/MathJax.git MathJax

to obtain and set up a copy of MathJax.

Whenever you want to update MathJax, you can now use

cd MathJax
git remote show origin

to check if there are updates to MathJax (this will print several lines of data, but the last line should tell you if your copy is up to date or out of date). If MathJax needs updating, use

cd MathJax
git pull origin

to update your copy of MathJax to the current release version. If you keep MathJax updated in this way, you will be sure that you have the latest bug fixes and new features as they become available.

This gets you the most recently released version of MathJax. Older releases are “tagged” in Git so that you can refer to them by name (which is the version number in most cases). Use

cd MathJax
git tag -l

to see all tagged versions, and use

cd MathJax
git checkout <tag_name>

to checkout the indicated version of MathJax, where <tag_name> is the name of the tagged version you want to use. For example,

git checkout 2.7.0

would get you version 2.7.0 of MathJax, even though there are newer versions of MathJax available.

Each of the main releases also has a branch in which critical updates are applied (we try hard not to patch the stable releases, but sometimes there is a crucial change that needs to be made). If you want to use the patched version of a release, then check out the branch rather than the tag. Use

cd MathJax
git branch -r

to get a list of the available branches. There are separate branches for the main releases, but with -latest appended. These contain all the patches for that particular release. You can check out one of the branches just as you would a tagged copy. For example, the branch for the 2.5 release is v2.5-latest. To get this release, use

cd MathJax
git checkout v2.5-latest

and to update it when changes occur, use

cd MathJax
git pull origin v2.5-latest

One of the branches is named develop; this branch includes all the latest changes to MathJax. Although we try to make sure this version is a stable and usable version of MathJax, it is under active development, and at times it may be less stable than the “release” version. If you want the most recent patches before they have been formally released as a new numbered version, you can check out the develop branch.

Obtaining MathJax via SVN

If you are more comfortable with the subversion source control system, you may want to use GitHub’s svn service to obtain MathJax. If you want to get the latest revision using svn, use the command

svn checkout http://github.com/mathjax/MathJax/trunk MathJax

to obtain and set up a copy of MathJax.

Whenever you want to update MathJax, you can now use

cd MathJax
svn status -u

to check if there are updates to MathJax. If MathJax needs updating, use

cd MathJax
svn update

to update your copy of MathJax to the current release version. If you keep MathJax updated in this way, you will be sure that you have the latest bug fixes and new features as they become available.

This gets you the most recently released version of MathJax. Older releases are available in “branches” named by the version number; e.g., v2.5-latest. If you prefer to use one of the older releases, then use

svn checkout https://github.com/mathjax/MathJax/branches/[name] MathJax

where [name] is replaced by the name of the branch you want to check out. The branch names can be found on the GitHub MathJax page under the branches tab.

Obtaining MathJax via an archive

Release versions of MathJax are available in archive files from the MathJax GitHub page. The current version is available via the “clone or download” button, or you can use the “releases” tab to download an archive for an older version.

Current Version: MathJax-2.7 (33.0MB)

Consult the change log for what’s new in version 2.7.

For previous versions, see the release page on GitHub or for quick access

You should download the archive of the branch corresponding to the version you need, then simply unzip it. Once the MathJax directory is unpacked, you should move it to the desired location on your server (or your hard disk, if you are using it locally rather then through a web server). One natural location is to put it at the top level of your web server’s hierarchy. That would let you refer to the main MathJax file as /MathJax/MathJax.js from within any page on your server.

If a packaged release receives any important updates, then those updates will be part of the branch for that version. To obtain the patched version, use the Branches drop down menu (at the far left of the menus within the page) to select the release branch that you want (for example v2.1-latest), and then use the green “clone or download” button toward the right of the page get the latest patched version of that release (via its “Download ZIP” link). You can also select any tagged release in the drop-down menu on the left (using the “tags” tab at the top of the list) and the “clone or download” button will download that version.

Obtaining MathJax via npm

Starting with version 2.6, it is possible to use npm to install MathJax. Assuming npm is installed on your system, just execute the following command:

npm install mathjax

Note

The distribution on npm does not contain the PNG fonts

Obtaining MathJax via Composer

Starting with version 2.5, it is possible to use Composer to install MathJax. See the Composer documentation to get started.

Obtaining MathJax via Bower

Starting with version 2.3, it is possible to use Bower to install MathJax. Assuming Bower is installed on your system, just execute the following command:

bower install MathJax

For a slim copy without PNG fonts use

bower install components/MathJax

Testing your installation

Use the HTML files in the test directory to see if your installation is working properly:

test/
    index.html          # Tests default configuration
    index-images.html   # Tests image-font fallback display
    sample.html         # Sample page with lots of pretty equations
    examples.html       # Page with links to all sample pages

Open these files in your browser to see that they appear to be working properly. If you have installed MathJax on a server, use the web address for those files rather than opening them locally. When you view the index.html file, you should see (after a few moments) a message that MathJax appears to be working. If not, you should check that the files have been transferred to the server completely, and that the permissions allow the server to access the files and folders that are part of the MathJax directory (be sure to verify the MathJax folder’s permissions as well). Checking the server logs may help locate problems with the installation.

Notes about shared installations

Typically, you want to have MathJax installed on the same server as your web pages that use MathJax. There are times, however, when that may be impractical, or when you want to use a MathJax installation at a different site. For example, a departmental server at www.math.yourcollege.edu might like to use a college-wide installation at www.yourcollege.edu rather than installing a separate copy on the departmental machine. MathJax can certainly be loaded from another server, but there is one important caveat — Firefox’s and IE9’s same-origin security policy for cross-domain scripting.

Firefox’s interpretation of the same-origin policy is more strict than most other browsers, and it affects how fonts are loaded with the @font-face CSS directive. MathJax’s HTML-CSS and CommonHTML output modes use this directive to load web-based math fonts into a page when the user doesn’t have them installed locally on their own computer. Firefox’s security policy, however, only allows this when the fonts come from the same server as the web page itself, so if you load MathJax (and hence its web fonts) from a different server, Firefox won’t be able to access those web fonts. In this case, MathJax’s HTML-CSS output mode will pause while waiting for the font to download (which will never happen); it will time out after about 5 seconds and switch to image fonts as a fallback. MathJax’s CommonHTML output mode will simply not show the correct fonts, but with no pause. Similarly, IE9 and above has a same-origin policy in its IE9 standards mode that also prevents loading remote fonts, so it exhibits this same behavior.

There is a solution to this, however, if you manage the server where MathJax is installed, and if that server is running the Apache web server. In the remote server’s MathJax/fonts/ folder, create a file called .htaccess that contains the following lines:

<FilesMatch "\.(ttf|otf|eot|woff)$">
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</FilesMatch>

and make sure the permissions allow the server to read this file. (The file’s name starts with a period, which causes it to be an “invisible” file on unix-based operating systems. Some systems, particularly those with graphical user interfaces, may not allow you to create such files, so you might need to use the command-line interface to accomplish this.)

This file should make it possible for pages at other sites to load MathJax from this server in such a way that Firefox and IE will be able to download the web-based fonts. If you want to restrict the sites that can access the web fonts, change the Access-Control-Allow-Origin line to something like:

Header set Access-Control-Allow-Origin "http://www.math.yourcollege.edu"

so that only pages at www.math.yourcollege.edu will be able to download the fonts from this site. See the open font library discussion of web-font linking for more details.

Firefox and local fonts

Firefox’s same-origin security policy affects its ability to load web-based fonts, as described above. This has implications not only to cross-domain loading of MathJax, but also to using MathJax locally from your hard disk. Firefox’s interpretation of the same-origin policy for local files is that the “same domain” for a page is the directory where that page exists, or any of its subdirectories. So if you use MathJax in a page with a file:// URL, and if MathJax is loaded from a directory other than the one containing the original page, then MathJax will not be able to access the web-based fonts in Firefox. In that case, MathJax will fall back on image fonts to display the mathematics.

In order for Firefox to be able to load the fonts properly for a local file, your MathJax installation must be in a subdirectory of the one containing the page that uses MathJax. This is an unfortunate restriction, but it is a limitiation imposed by Firefox’s security model that MathJax can not circumvent. Currently, this is not a problem for other browsers.

One solution to this problem is to install the MathJax fonts locally, so that Firefox will not have to use web-based fonts in the first place. To do that, either install the STIX fonts, or copy the fonts from MathJax/fonts/HTML-CSS/TeX/otf (or whichever of the web-based fonts in the MathJax/fonts/HTML-CSS directory you wish) into your system’s fonts directory and restart your browser.

IE9 and remote fonts

IE9’s same-origin policy affects its ability to load web-based fonts, as described above. This has implications not ony to cross-domain loading of MathJax, but also to the case where you view a local page (with a file:// URL) that accesses MathJax from a remote site such as a CDN service. In this case, IE9 does not honor the Access-Control-Allow-Origin setting of the remote server (as it would if the web page came from an http:// URL), and so it never allows the font to be accessed.

One solution to this problem is to install the MathJax fonts locally so that MathJax doesn’t have to use web-based fonts in the first place. Your best bet is to install the STIX fonts on your system.