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
- MathJax-2.6 (34.3MB)
- MathJax-2.5 (33.0MB)
- MathJax-2.4 (32.6MB)
- MathJax-2.3 (32.9MB)
- MathJax-2.2 (17.0MB)
- MathJax-2.1 (17.1MB)
- MathJax-2.0 (17.6MB)
- MathJax-1.1a (15.4MB)
- MathJax-1.1 (16.4MB)
MathJax v1.0.1a
- To install MathJax v1.0.1a, you must download two files: MathJax-v1.0.1a.zip and MathJax-Font-Update.zip. First install the MathJax-v1.01a.zip distribution. Then replace the
MathJax/fonts/HTML-CSS/TeX/otf
directory in the resulting MathJax installation with the otf directory contained in theMathJax-Font-Update.zip
archive.
- To install MathJax v1.0.1a, you must download two files: MathJax-v1.0.1a.zip and MathJax-Font-Update.zip. First install the MathJax-v1.01a.zip distribution. Then replace the
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.
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.