Install Apache CouchDB on Windows with the MSI installer, complete the single-node setup, verify it with a test document, and fix the common startup and login errors.
Apache CouchDB installs on Windows from an MSI package: download the Windows (x64) installer from couchdb.apache.org, run it, install to a path without spaces such as C:\CouchDB, create an admin account when asked, and let it install the Windows service. Then finish the single-node setup, which the installer does not do for you.
To check that the server is answering, open PowerShell and run:
The version shown will be whichever 3.x release you installed. The rest of this page goes through each step, the setup that has to follow, and the problems people most often hit.
Before you install
You need a 64-bit Windows machine and an administrator account.
The CouchDB documentation lists .NET Framework 3.5 as a prerequisite on Windows 8, 8.1 and 10. It is an optional Windows feature. If it is missing, enable it from an elevated PowerShell window:
If an older CouchDB is installed, back up etc\local.ini and the data folder from its installation directory, then uninstall it. The documentation advises against installing over a previous version, because different releases bundle different Erlang runtimes.
Decide on an admin user name and password. CouchDB 3 does not run without an admin account. The old "admin party" mode, in which everyone was an administrator until you created one, was removed in 3.0.
Run the installer
Go to https://couchdb.apache.org/ and download the Windows (x64) package from the download section. It is an .msi file named after the version.
Run the file and accept the licence.
Installation folder: choose a path with no spaces, for example C:\CouchDB. Do not install under C:\Program Files. The documentation is explicit about this.
Admin account: enter the admin user name and password you chose.
Leave the option to install CouchDB as a Windows service selected, so that it starts with Windows.
Finish the wizard. The installer may ask for a reboot if it had to update the Visual C++ runtime.
Unattended install
The MSI accepts properties on the command line, which is useful for scripts and for build agents. From an elevated prompt, with the real file name:
Add APPLICATIONFOLDER="D:\CouchDB" to change the target folder, and /l* log.txt to write an installer log when something fails.
Finish the single-node setup
At this point CouchDB is running, but the installation is not complete. A node has to be told whether it is a standalone server or part of a cluster, and it needs its system databases.
Open Fauxton, CouchDB's web interface, at:
http://127.0.0.1:5984/_utils#setup
Log in with the admin account, choose the single-node option, confirm the credentials and bind address, and submit. Fauxton creates the system databases for you.
You can do the same from PowerShell by creating the databases yourself:
curl.exe -X PUT -u admin:ChangeThisPassword http://127.0.0.1:5984/_users
curl.exe -X PUT -u admin:ChangeThisPassword http://127.0.0.1:5984/_replicator
curl.exe -X PUT -u admin:ChangeThisPassword http://127.0.0.1:5984/_global_changes
Each returns {"ok":true}. The third is needed only if you plan to use the global changes feed.
Two notes on the commands. In Windows PowerShell, curl on its own is an alias for Invoke-WebRequest, which takes different arguments, so always type curl.exe. And Fauxton replaced the older Futon interface in CouchDB 2.0; guides that tell you to open Futon from the Start menu predate that.
Verify with a database and a document
Fauxton has a built-in check on its Verify page (http://127.0.0.1:5984/_utils#verifyinstall). To test from the command line instead, create a database and store a document. Invoke-RestMethod avoids the quoting problems that JSON bodies cause with curl.exe in PowerShell:
The _rev value is the document's revision. To update or delete a document you must send its current revision; if it has changed in the meantime CouchDB answers 409 Conflict. That is how CouchDB handles concurrent writes.
Manage the service and configuration
The installer registers a Windows service. Check and restart it from an elevated PowerShell window:
Shipped defaults. Do not edit; upgrades overwrite it.
etc\local.ini
Your settings. Overrides default.ini.
data\
Database and index files.
var\log\
Log files.
By default CouchDB listens on port 5984 on 127.0.0.1 only, so it is reachable from the same machine and nowhere else. To accept connections from other machines, edit etc\local.ini:
[chttpd]bind_address = 0.0.0.0port = 5984
Restart the service, then allow the port through Windows Firewall:
Do this only on a trusted network. CouchDB speaks plain HTTP on 5984, so credentials cross the network unencrypted unless you put a TLS reverse proxy in front of it or enable its HTTPS listener.
Settings can also be changed at runtime through Fauxton's Configuration page or the /_node/_local/_config API. Those changes are persisted to the local configuration file, so they survive a restart.
Troubleshooting
{"error":"unauthorized","reason":"You are not a server admin."}
The request needs admin credentials and did not carry any, or they were wrong. Creating databases is an admin operation. Since CouchDB 3.0, new databases are also readable only by admins until you change their security settings.
{"error":"file_exists","reason":"The database could not be created, the file already exists."}
The database is already there. It is safe to ignore when you rerun the setup commands.
The log repeats a notice that the _users database does not exist.
The single-node setup was skipped. Create the system databases as shown above.
The service does not start, or stops immediately.
Check the newest file in the log folder. The usual causes are an installation path that contains spaces, another program already using port 5984, or a syntax error in local.ini. To see what holds the port:
You forgot the admin password.
Stop the service, open etc\local.ini, and under [admins] replace the hashed value with a new plain-text password, for example admin = NewPassword. Start the service. CouchDB hashes the value on startup.
The browser shows a blank or broken Fauxton page.
Use http://127.0.0.1:5984/_utils/ in a current browser and clear the cache for that address after an upgrade.
Upgrade and uninstall
To upgrade, back up etc\local.ini and the data folder, uninstall the old version, install the new one to the same folder, and restore your local.ini settings if the installer replaced them.
To uninstall, use Settings > Apps > Installed apps, or run the installer package with /x:
