Jump to navigation Jump to search

Before you begin[edit]

If you are using Parsoid in conjunction with VisualEditor, note that they are developed in parallel and upgrades to one often require a corresponding upgrade to the other. If in doubt, please check the Extension:VisualEditor page and follow its setup instructions first.

Of course, Parsoid can be used stand-alone (to convert wikitext to HTML DOM and vice-versa) and if you don't need VisualEditor, you can ignore the above.

If you are a developer, or if you lack access to sudo apt-get because you're on shared hosting, you probably want to follow the Developer Setup instructions. This page documents setup for a typical user of Parsoid using the native software packaging for your operating system. (Although, if your preferred operating system is not listed here, you might try the developer setup instructions — good luck!)

If your shared hosting doesn't allow you to install Parsoid, you can also try this workaround: Installation on a shared host.

If you run into problems, consult the troubleshooting pages. If you'd like to contribute your problems and suggested solutions to others, we encourage you to add that information to the troubleshooting pages, in order to keep this page of typical installation instructions as clear and simple as possible.

First you will need to install Parsoid. After this is done, skip to the #Configuration section of this page in order to ensure that Parsoid can talk to your mediawiki instance.


Ubuntu / Debian[edit]

Parsoid switched package repositories on 2015-09-17. If you installed Parsoid prior to this date, you will need to follow the instructions below to add the new Parsoid repository to get updated packages. If you are installing Parsoid as a new package, follow the instructions below.
Parsoid updated its GPG key on 2016-07-27. If you installed Parsoid prior to this date, you will need to follow the instructions below to add the new Parsoid GPG key before you will get updated packages. If you are installing Parsoid as a new package, follow the instructions below.

These packages work on all architectures and with current distros: Ubuntu 14+ and Debian testing, unstable or wheezy (stable) with backports enabled. See the manual installation on Linux or Mac OS X instructions if your distribution is older & doesn't have nodejs >= v4.x available.

Import the repository gpg key: (key updated on July 27, 2016)

sudo apt install dirmngr
sudo apt-key advanced --keyserver --recv-keys 90E9F83F22250DD7

If the last command above isn't working (gpgkeys: key 90E9F83F22250DD7 can't be retrieved), you can try another key server. This one should work :

sudo apt-key advanced --keyserver --recv-keys 90E9F83F22250DD7

Add the Wikimedia repository:

  • Ubuntu
sudo apt-add-repository "deb jessie-mediawiki main"

On ubuntu 16.04 you may need to install "software-properties-common" in order to run "apt-add-repository"

apt-get install software-properties-common
  • Debian
echo "deb jessie-mediawiki main" | sudo tee /etc/apt/sources.list.d/parsoid.list


sudo apt install apt-transport-https
sudo apt update
sudo apt update && sudo apt install parsoid

Then, open the config file in /etc/mediawiki/parsoid/config.yaml and update it to reflect your API URL. See the #Configuration section below for details.


  • Modifications brought to the configuration file will only become active after restarting the service by service parsoid restart.
  • The default port used is 8142 (not 8000 so you'll need to, for example, change $wgVirtualRestConfig['modules']['parsoid']['url'] in LocalSettings.php).
  • The log file is /var/log/parsoid/parsoid.log, and is automatically rotated.

Caveats about the deb:

  • If you are on an older distribution and nodejs >= v4 is not available, see the Nodejs installation instructions. You might be able to get a recent packaged version of nodejs. If you have to install node.js from source (we recommend nave), you'll need to use the Parsoid/Developer Setup instructions.
  • Some folks report that you should also ensure that curl is installed as well: sudo apt-get install curl. Please add some more details here if you find this to be true on your setup.


Parsoid is available in AUR under aur/parsoid (release version) or aur/parsoid-git (development version). Install however you would usually install AUR packages. Enable and start the parsoid service (systemctl enable parsoid; systemctl start parsoid) and configure per below. Remember to restart the service for changes to take effect.

This installs to /usr/share/webapps/parsoid/ by default.


Parsoid is available from the Git repository.

Try creating an empty directory and checking out a copy of Parsoid:

yum install git npm
git clone --recursive
git clone
cd parsoid
npm install

This should dump everything you need into the current directory. Copy the default configuration (which configures the Parsoid server to listen at http://localhost:8000):

cp config.example.yaml config.yaml

Edit this file per #Configuration (below), then start the server with:

node bin/server.js

At this point, opening a browser to localhost:8000 should display a page with links to the Parsoid documentation on

As one final step, change your startup files (init.d) to add a task to relaunch node bin/server.js on server startup.


If you are using the MediaWiki-Vagrant virtual machine, the parsoid role sets up a working Parsoid. If you use the visualeditor role, it will enable parsoid as well.



  • Install Nodejs x86
  • Install Git x86

With nodejs you have to install the build tools (as administrator)

npm install --global --production windows-build-tools

You may need to update your npm version to avoid errors

npm -g install npm@latest

npm@next is broken. See

If your current directory is in C:\windows\system32, Perform the following command


Install parsoid

npm install parsoid

Copy the default config and configure parsoid for Windows Vista/7

copy %USERPROFILE%\node_modules\parsoid\localsettings.example.js %USERPROFILE%\node_modules\parsoid\localsettings.js

or for Windows 8+

copy %APPDATA%\npm\node_modules\parsoid\localsettings.example.js %APPDATA%\npm\node_modules\parsoid\localsettings.js

Run parsoid

C:\Users\USERNAME\node_modules\parsoid>node bin/server.js

or on Windows 10+

cd %APPDATA%\npm\node_modules\parsoid
node bin/server.js

You should open your php.ini file and uncomment the next php modules:

  • extension=php_curl.dll
  • extension=php_openssl.dll

otherwise you will get troubles with Parsoid


This is a version of Parsoid created by community. The original repository can be found at TheNets's GitHub.

Two versions are available: 0.8.1 and 0.9.0.

The images was created over Alpine image.


How to run[edit]

To start Parsoid run the command below. Just pay attention to the MediaWiki version and choose a compatible Parsoid version.

# For MediaWiki 1.28, 1.29 and 1.30
docker run -it -p 8080:80 -e PARSOID_DOMAIN_localhost=http://localhost/w/api.php thenets/parsoid:0.8.1

# For MediaWiki 1.31
docker run -it -p 8080:80 -e PARSOID_DOMAIN_localhost=http://localhost/w/api.php thenets/parsoid:0.9.0


How to add more than one domain:

docker run -it -p 8080:80 \
            -e PARSOID_DOMAIN_foobar= \
            -e PARSOID_DOMAIN_example= \
            -e PARSOID_DOMAIN_localhost=http://localhost/w/api.php \

How to expose on a specific port: (You can use arbitrary port numbers which are not already in use)

# Expose port 8081
docker run -it -p 8081:80 -e PARSOID_DOMAIN_localhost=http://localhost/w/api.php thenets/parsoid:0.8.1

# Expose port 8142
docker run -it -p 8142:80 -e PARSOID_DOMAIN_localhost=http://localhost/w/api.php thenets/parsoid:0.8.1

For more information about Docker setup, check the GitHub page.


Parsoid should be configured via edits to the static config.yaml file. If you are using an version of Parsoid older than v0.6.0, you will have to edit localsettings.js, which also allows non-static configs for the time being.

Starting with Parsoid 0.6.0, the configuration file is located here:

  • /etc/mediawiki/parsoid/config.yaml

If the api.php file for your wiki is not in the default 'http://localhost/w/api.php' edit the config.yaml file and modify the uri parameter to point to the correct location:

        - # This is the only required parameter,
          # the URL of you MediaWiki API endpoint.
          uri: ''
          # The "domain" is used for communication with Visual Editor
          # and RESTBase.  It defaults to the hostname portion of
          # the `uri` property above, but you can manually set it
          # to an arbitrary string.
          domain: ''  # optional

The uri property gives the API path to your local wiki. The domain property is optional; it defaults to the hostname used in the uri property if not explicitly set, but it can be an arbitrary string (it doesn't actually have to resolve in DNS).

If your wiki is inside a reverse proxy configuration or similar, you can set the hostname in uri to an internal hostname or IP that actually points to your wiki internal IP address, to avoid requests going to the public IP address and then routed back again to the internal server. However, be sure that your web server actually routes requests with that hostname to the wiki (if the server is configured to serve different things for multiple sites or subdomains).

For example: you have a wiki at with a public IP behind a proxy, and the actual application server is on a second internal server which only serves requests to the wiki when accessed from the hostname but not with other hostnames (because it serves various different websites). You may need to set an /etc/hosts alias of and set up your web server to have as an alias to Then you can use that hostname in the uri property.

By default, Parsoid opens a UDP socket and send each minute some metrics about the Parsoid heap to a statsD server. If you want to send instead these metrics to the logging backend (with the "trace" log level), add in config.yaml:

    type: log

localsettings.js (or settings.js) as configuration file[edit]

If you prefer to use localsettings.js as your configuration file, in the config.yaml file uncomment the localsettings path like this:

        # For backwards compatibility, and to continue to support non-static
        # configs for the time being, optionally provide a path to a
        # localsettings.js file.  See localsettings.example.js
        localsettings: ./localsettings.js

and comment mwApis, uri and domain parameters like this:

        #- # This is the only required parameter,
          # the URL of you MediaWiki API endpoint.
          #uri: 'http://localhost/w/api.php'
          # The "domain" is used for communication with Visual Editor
          # and RESTBase.  It defaults to the hostname portion of
          # the `uri` property below, but you can manually set it
          # to an arbitrary string.
          #domain: 'localhost'  # optional

In this approach the configuration file lives in one of the following locations:

  • /etc/mediawiki/parsoid/settings.js (if you have installed from our Linux packages)
  • <parsoid directory>/api/localsettings.js (if you have followed the developer setup instructions)

Most configuration options are described in the file itself. The only required edit is to update it to reflect your API URL, something like:

parsoidConfig.setMwApi({ uri: '', domain: '', prefix: 'myspecialwiki' });

The prefix is an arbitrarily-selected short string identifying your local wiki, used in log messages. The prefix is also optional, an arbitrary unique string will be generated if it is omitted. Make sure that the VisualEditor configuration uses the same "domain" and/or "prefix" values as Parsoid. (See the VisualEditor configuration instructions.)

Multiple wikis sharing the same parsoid service[edit]

If you have multiple wikis, make sure the domain string (and/or prefix if you are using localsettings.js as config file) is unique for each. Multiple wikis sharing a single host might need to explicitly set the domain property to an arbitrary unique string for each wiki.

Example of configuration in config.yaml for multiple wikis:

        - # First wiki
          uri: ''
          domain: ''  # optional
        - # If you have another wiki on a different domain
          uri: ''
          domain: ''  # optional
        - # If you have another wiki on the same domain
          uri: ''
          domain: 'wiki2'  # optional

Example of configuration in localsettings.js for multiple wikis:

parsoidConfig.setMwApi({ uri: '', domain: '', prefix: 'myspecialwiki' });
// If you have another wiki on a different domain:
parsoidConfig.setMwApi({ uri: '', domain: '', prefix: 'myotherspecialwiki' });
// If you have another wiki on the same domain:
// Note that the domain and prefix can be arbitrary, they just need to be unique to this wiki.
// (And they shouldn't contain slashes.)
parsoidConfig.setMwApi({ uri: '', domain: 'wiki2', prefix: 'wiki2' });

See Parsoid/Troubleshooting#Configuration for additional troubleshooting help.

See Parsoid/Setup/RESTBase for information on how to configure a local RESTBase instance between your local VisualEditor and local Parsoid.

The Parsoid/Setup/RESTBase/Arbitrary domains page describes advanced RESTBase setup, but it may offer additional insight about the purpose of the prefix and domain properties.