VisualEditor Setup Guide

VisualEditor is MediaWiki's built-in rich-text editing interface. It allows editors to create and edit wiki pages in a WYSIWYG environment — formatting text, inserting links, adding tables and images — without needing to know wikitext markup. For organisations deploying a wiki whose editors are not developers or technical writers, enabling VisualEditor is one of the most effective ways to lower the barrier to contribution.

This guide covers everything needed to enable and configure VisualEditor on a current MediaWiki installation: what the extension requires, step-by-step setup instructions, configuration options for common deployment scenarios, and a troubleshooting reference for the errors that appear most frequently.

This guide assumes a working MediaWiki 1.35 or later installation. If you need to set up MediaWiki from scratch first, see "How to Install MediaWiki on Ubuntu Server".

What VisualEditor Is and How It Works

VisualEditor is a JavaScript-based rich-text editor that presents a rendered view of a wiki page and allows it to be edited directly, rather than requiring the editor to work with wikitext markup in a plain text field. It is developed by the Wikimedia Foundation and is used on Wikipedia and all Wikimedia sites.

Behind the scenes, VisualEditor communicates with Parsoid — a library that converts back and forth between MediaWiki's wikitext format and the structured HTML that VisualEditor displays. When an editor opens a page in VisualEditor, Parsoid converts the stored wikitext into HTML for display. When the editor saves, Parsoid converts the modified HTML back into wikitext for storage.

An important clarification about Parsoid versions. A significant amount of outdated documentation on the internet describes installing a separate Node.js-based Parsoid service alongside MediaWiki. That approach applied to the old JavaScript version of Parsoid, which reached end-of-life in September 2021 and is no longer used. Since MediaWiki 1.35, Parsoid has been bundled directly with MediaWiki as a PHP library (wikimedia/parsoid via Composer), and VisualEditor communicates with it internally through MediaWiki's own REST API endpoint (rest.php).^[1] Node.js is not required for VisualEditor on any current MediaWiki installation.

Requirements

VisualEditor Requirements
Requirement	Detail
MediaWiki version	1.35 or later. VisualEditor is bundled with the MediaWiki tarball from 1.35 onward and does not need to be downloaded separately.
PHP extension: curl	Required. The bundled Parsoid REST service uses curl for internal requests. Install `php-curl` if not already present.
PHP extension: zlib	Required for compressed communication with the Parsoid service.
Short URLs	Strongly recommended. VisualEditor uses MediaWiki's REST API at `/rest.php` (or the short-URL equivalent). Clean URL rewriting improves reliability, particularly when editing subpages.
Skin compatibility	Officially supported with Vector, Vector 2022, MonoBook, and Minerva Neue. Other skins may work but are not officially tested.

Step 1: Confirm php-curl Is Installed

VisualEditor's internal communication with the bundled Parsoid service depends on the PHP curl extension. Confirm it is present:

php -i | grep curl

If curl is not listed, install it:

sudo apt install php-curl

Restart Apache after installing:

sudo systemctl restart apache2

Confirm it is now available:

php -i | grep curl

Step 2: Enable the VisualEditor Extension

VisualEditor is already present in the extensions/VisualEditor/ directory of any MediaWiki 1.35+ installation. It does not need to be downloaded. Open LocalSettings.php and add the following line to load the extension:

wfLoadExtension( 'VisualEditor' );

This line alone enables VisualEditor, but it makes the editor available as an opt-in feature that individual users can choose in their preferences. The configuration steps below control whether it is enabled by default, who can access it, and in which namespaces it appears.

Step 3: Enable VisualEditor by Default for All Users

Without additional configuration, VisualEditor is available but not enabled by default — users have to activate it in their preferences. For most organisational wiki deployments, enabling it by default for everyone is the practical choice.

Enable VisualEditor by default for all users:

$wgDefaultUserOptions['visualeditor-enable'] = 1;

Optionally, prevent users from disabling it in their preferences:

$wgHiddenPrefs[] = 'visualeditor-enable';

Set VisualEditor as the default editor that opens when a user clicks the Edit tab (rather than presenting it as a secondary option):

$wgDefaultUserOptions['visualeditor-editor'] = 'visualeditor';

Step 4: Enable the 2017 Wikitext Editor Alongside VisualEditor

MediaWiki includes a modern wikitext editor — sometimes called the 2017 wikitext editor — that uses the same editing interface as VisualEditor but displays wikitext markup rather than rendered output. Enabling both allows editors to switch between visual and source editing from the same tab without losing their in-progress changes.

Enable the wikitext editor mode:

$wgVisualEditorEnableWikitext = true;

Make the 2017 wikitext editor the default wikitext experience:

$wgDefaultUserOptions['visualeditor-newwikitext'] = 1;

Step 5: Configure Available Namespaces

By default on current MediaWiki versions, VisualEditor is enabled for the Main, User, File, and Category namespaces and all content namespaces. It is not enabled by default for Talk, Project, Help, or other namespaces.^[2]

To add or remove namespaces from VisualEditor's scope, use the $wgVisualEditorAvailableNamespaces setting. The following example adds the Project namespace and explicitly disables VisualEditor in the Talk namespace:

$wgVisualEditorAvailableNamespaces = [
    NS_MAIN => true,
    NS_USER => true,
    NS_PROJECT => true,
    NS_TALK => false,
    "_merge_strategy" => "array_plus"
];

The "_merge_strategy" => "array_plus" entry instructs MediaWiki to merge this array with the defaults rather than replacing them entirely, preserving any namespace settings not explicitly listed here.

For custom namespaces, use the numeric namespace ID instead of the constant name. The namespace ID for any custom namespace can be found by looking at the source of the Special:AllPages dropdown, or it is defined in LocalSettings.php where the custom namespace was declared.

Step 6: Configure the Single Edit Tab (Optional)

By default, MediaWiki shows separate edit tabs: one for VisualEditor and one for wikitext source editing. Some organisations prefer a single Edit tab that opens the last editor the user used, similar to the Wikipedia editing experience.

Enable a single edit tab:

$wgVisualEditorUseSingleEditTab = true;

Set the preference so the single tab defaults to VisualEditor:

$wgDefaultUserOptions['visualeditor-tabs'] = 'prefer-ve';

Step 7: Configure VisualEditor for a Private Wiki

On a wiki that requires users to log in before reading (configured with $wgGroupPermissions['*']['read'] = false;), VisualEditor's internal communication with the Parsoid REST service needs to forward the user's login cookie, since Parsoid makes its own request to the wiki's API and would otherwise be treated as an unauthenticated visitor.

Enable cookie forwarding for private wikis:

$wgVisualEditorParsoidForwardCookies = true;

Without this setting on a private wiki, VisualEditor will open pages for editing but will fail to load existing content correctly — the Parsoid service will be unable to fetch the page it needs to convert because it lacks authentication.

Step 8: Verify the Installation

After saving the changes to LocalSettings.php, open any content page on the wiki and confirm that:

The Edit tab opens VisualEditor rather than the plain wikitext editor (if you set it as the default in Step 3).
An existing page can be opened for editing and the content displays correctly in the visual editing environment.
A test edit can be saved successfully.
The wikitext editing option is accessible by clicking the pencil icon in the toolbar and selecting "Edit source" (or the equivalent tab, depending on skin and configuration).

If any of these steps fail, consult the Troubleshooting section below.

Configuration Reference

VisualEditor LocalSettings.php Configuration Reference
Setting	Effect	Typical Value
`wfLoadExtension( 'VisualEditor' );`	Loads the extension. Required. Without this line nothing else works.	Required
`$wgDefaultUserOptions['visualeditor-enable']`	Enables VisualEditor by default for all users. Set to `1` to enable, `0` to disable (opt-in only).	`1`
`$wgHiddenPrefs[] = 'visualeditor-enable';`	Removes the VisualEditor on/off toggle from user preferences, preventing users from disabling it.	Optional
`$wgDefaultUserOptions['visualeditor-editor']`	Controls which editor opens by default on the Edit tab. `"visualeditor"` for VE, `"wikitext"` for source.	`"visualeditor"`
`$wgVisualEditorEnableWikitext`	Enables the 2017 wikitext editor mode within the VisualEditor interface.	`true`
`$wgVisualEditorUseSingleEditTab`	Collapses VisualEditor and wikitext into a single Edit tab.	`true` or `false`
`$wgVisualEditorAvailableNamespaces`	Array controlling which namespaces VisualEditor is active in.	Namespace constants or IDs mapped to `true` or `false`
`$wgVisualEditorParsoidForwardCookies`	Forwards the user's login cookie from VisualEditor to the internal Parsoid service. Required for private wikis.	`true` on private wikis
`$wgDefaultUserOptions['visualeditor-newwikitext']`	Sets the 2017 wikitext editor as the default wikitext editing experience.	`1`

Best Practices

Enable VisualEditor and the 2017 wikitext editor together rather than VisualEditor alone, so that editors who prefer or need to work in wikitext markup still have a modern, supported editing interface. Set VisualEditor as the default and use $wgHiddenPrefs to prevent users from disabling it on wikis where editor consistency matters — mixed wiki deployments where some editors use wikitext and others use VisualEditor can produce inconsistently formatted pages over time. Test the configuration on a staging environment before deploying to a production wiki, particularly after any MediaWiki version upgrade, since VisualEditor's behaviour can be affected by changes to the REST API in new releases. On private wikis, always set $wgVisualEditorParsoidForwardCookies = true; — it is easy to miss during initial setup and causes confusing partial failures where VisualEditor opens correctly but page content doesn't load. Keep the php-curl extension updated alongside PHP itself, since version mismatches between PHP and its extensions are an occasional source of silent failures in the Parsoid communication.

Common Mistakes

The most frequent mistake on current MediaWiki installations is adding the old Node.js Parsoid configuration ($wgVirtualRestConfig['modules']['parsoid']) copied from outdated tutorials. On MediaWiki 1.35+, this line tells MediaWiki to connect to an external Parsoid service that no longer exists, which overrides the working internal PHP Parsoid and breaks VisualEditor completely. If this line is present in LocalSettings.php, it should be removed entirely. The second most common mistake is enabling VisualEditor without installing or confirming php-curl is present, which causes the internal REST API calls to fail silently. Not setting $wgVisualEditorParsoidForwardCookies = true; on a private wiki is a third common omission — it produces an error that looks like a server configuration problem but is simply a missing authentication forwarding setting. Finally, adding VisualEditor to namespaces that contain only templates or other technical wikitext is generally counterproductive — VisualEditor is not well suited to template pages, and enabling it there can lead editors to accidentally corrupt template syntax through the visual editing interface.

Troubleshooting

Common VisualEditor Errors and Fixes
Error	Most Likely Cause	Fix
"Error contacting the Parsoid/RESTBase server: http-request-error"	Old `$wgVirtualRestConfig['modules']['parsoid']` entry still in LocalSettings.php, pointing to a Node.js service that no longer exists	Remove the entire `$wgVirtualRestConfig['modules']['parsoid']` block from LocalSettings.php; on MW 1.35+ the internal Parsoid library is used automatically
"Error contacting the Parsoid/RESTBase server: http-bad-status"	The internal REST API endpoint (`rest.php`) is not accessible, often due to a web server configuration issue	Confirm that `rest.php` is accessible directly in the browser at `yourdomain.com/rest.php`; check Apache/Nginx rewrite rules if using short URLs
VisualEditor toolbar loads but page content is blank	Private wiki without cookie forwarding enabled	Add `$wgVisualEditorParsoidForwardCookies = true;` to LocalSettings.php
Edit tab does not appear at all	Extension not loaded, or skin incompatibility	Confirm `wfLoadExtension( 'VisualEditor' );` is present in LocalSettings.php; confirm the active skin is Vector, Vector 2022, MonoBook, or Minerva Neue
VisualEditor loads but saves fail with a PHP error	Missing or mismatched `php-curl` or `php-zlib` extension	grep curl and `php -i \| grep zlib` to confirm both are present; install if missing
VisualEditor works in the Main namespace but not in a custom namespace	Custom namespace not added to `$wgVisualEditorAvailableNamespaces`	Add the custom namespace ID mapped to `true` in the `$wgVisualEditorAvailableNamespaces` array
Wikitext editor no longer accessible after enabling VisualEditor	`$wgHiddenPrefs[] = 'visualeditor-enable';` set without also enabling the 2017 wikitext mode	Add `$wgVisualEditorEnableWikitext = true;` to ensure source editing remains accessible

Frequently Asked Questions

Does MediaWiki VisualEditor require Node.js?

Not on MediaWiki 1.35 or later. The old JavaScript-based Parsoid service that required Node.js reached end-of-life in September 2021. Since MediaWiki 1.35, Parsoid is bundled directly with MediaWiki as a PHP library and operates internally. Any tutorial or guide that instructs you to install a separate Node.js Parsoid service is describing the old, obsolete setup.

Can VisualEditor and wikitext editing be used side by side?

Yes, and this is the recommended configuration for most wikis. Setting $wgVisualEditorEnableWikitext = true; enables the 2017 wikitext editor, which lets editors switch between visual and source editing from within the same interface without losing in-progress changes.

Will VisualEditor work with a custom skin?

VisualEditor is officially tested with Vector, Vector 2022, MonoBook, and Minerva Neue. It may work with other skins that implement the required HTML structure, but may require adjustments to stylesheets to render correctly. Custom skins that deviate significantly from the standard MediaWiki skin structure may need additional development work to be compatible.

Why does VisualEditor show a blank page when editing on a private wiki?

On a wiki that restricts anonymous reading ($wgGroupPermissions['*']['read'] = false;), the internal Parsoid service makes its own request to the wiki's API to fetch page content for conversion. Without cookie forwarding enabled, this request is treated as unauthenticated and denied. Setting $wgVisualEditorParsoidForwardCookies = true; resolves this.

Can anonymous users use VisualEditor?

Yes, unless specifically restricted. Anonymous users can use VisualEditor on pages they have permission to edit. If the wiki is configured to prevent anonymous editing ($wgGroupPermissions['*']['edit'] = false;), anonymous users will not be able to edit at all, regardless of VisualEditor being enabled.

Does enabling VisualEditor affect how wikitext is stored?

No. Regardless of which editor a user employs to write content, the content is stored in the database as wikitext. VisualEditor converts to and from wikitext transparently on every save, and the stored format is identical to content written in the wikitext editor.

What should I do if VisualEditor stopped working after a MediaWiki upgrade?

Check Special:Version to confirm the VisualEditor extension version matches the current MediaWiki release branch. After a major version upgrade, clear the cache:

php maintenance/run.php rebuildLocalisationCache

Also check whether any leftover $wgVirtualRestConfig entries from a previous installation are still present in LocalSettings.php — these are a common source of failures after upgrades from older MediaWiki versions.

Conclusion

VisualEditor is bundled with every MediaWiki installation since 1.35 and requires only a few lines of configuration to enable. The common points of confusion — outdated Node.js Parsoid documentation, missing php-curl, and cookie forwarding omissions on private wikis — account for the majority of real-world setup problems. Getting the extension working correctly is primarily a matter of applying the current configuration approach and removing any legacy settings that may have been carried over from older tutorials.

Once in place, VisualEditor meaningfully lowers the editing barrier for non-technical contributors, which is one of the strongest arguments for deploying MediaWiki for collaborative internal documentation in the first place.

For help enabling and configuring VisualEditor as part of a new deployment or an upgrade to an existing wiki, see SolidWiki's MediaWiki Development Services page.

References

↑ MediaWiki.org, "Parsoid", https://www.mediawiki.org/wiki/Parsoid
↑ MediaWiki.org, "Extension: VisualEditor", https://www.mediawiki.org/wiki/Extension:VisualEditor

External Links

[1] MediaWiki.org, "Parsoid", https://www.mediawiki.org/wiki/Parsoid

[2] MediaWiki.org, "Extension: VisualEditor", https://www.mediawiki.org/wiki/Extension:VisualEditor

[1]

[2]