Skip to content

Installation Instructions

Katrin Leinweber edited this page Aug 19, 2019 · 6 revisions

How to install and run Refine

OpenRefine is a desktop application in that you download it, install it, and run it on your own computer. However, unlike most other desktop applications, it runs as a small web server on your own computer and you point your web browser at that web server in order to use Refine. So, think of Refine as a personal and private web application.


  1. Java JRE installed (If you are running a 64 bit operating system, then it's recommended that you install 64 bit Java)

  2. A Supported OS: Windows, Linux, macOS

NOTE: On Windows we do NOT support Cygwin, MSYS2, or Git Bash for running OpenRefine, instead just use Windows Terminal

Release Version

  • OpenRefine requires you to have a working Java JRE, otherwise you will not be able to start OpenRefine. (the commmand window will just open and close quickly after you double click on OpenRefine.exe)
  • Download OpenRefine here.
  • Install it as detailed below for your operating system
  • As long as OpenRefine is running, you can point your browser at to use it, and you can even use it in several browser tabs and windows.
  • If you're running a proxy or get a BindException, you can change the IP configuration with -i and -p, see Running & Configuration below, or use refine -help for options.


Install: Once you have downloaded the .zip file, uncompress it into a folder wherever you want (such as in C:\Open-Refine).

Run: Run the .exe file in that folder. You should see the Command window in which OpenRefine runs. By default, the Command window has a black background and text in monospace font in it.

Shut down: When you need to shut down OpenRefine, switch to that Command window, and press Ctrl-C. Wait until there's a message that says the shutdown is complete. That window might close automatically, or you can close it yourself. If you get asked, "Terminate all batch processes? Y/N", just press Y.

Upgrading: If you upgrade to a new version of OpenRefine, you may need to update your workspace (update reconciliation links, for example). Remove your workspace.json file located at a data storage location. This file will be regenerated when OpenRefine starts.


Install via Disk Image: Once you have downloaded the .dmg file, open it, and drag the OpenRefine icon into the Applications folder icon (just like you would normally install Mac applications). If you get a message saying "Open Refine can't be opened because it is from an unidentified developer" you will need to open System Preferences and go to "Security and Privacy" and the General tab. Here you will see a message indicating that "OpenRefine was blocked from opening because it is not from an identified developer". Click the "Open Anyway" button to complete the OpenRefine installation.

screenshot 2019-01-07 at 12 21 37

Install via Homebrew: Follow our detailed Homebrew installation guide, or follow quick steps below:

  1. Install Homebrew from here

  2. In Terminal enter

  brew cask install openrefine
  1. Then find OpenRefine in your Applications folder.

Run: To launch OpenRefine, go to the Applications folder and double click the OpenRefine app. You'll see the OpenRefine app appear in your dock.

Shut down: You can switch to the OpenRefine app (clicking on its icon in the dock) and invoke its Quit command.

See also: Cannot install on Mac OS X 10.8 (Mountain Lion) - "Google Refine" is damaged and can't be opened. You should move it to the Trash

If you use Yosemite you will need to install Java for OS X 2014-001 first.


Install / Run: Once you have downloaded the tar.gz file, open a shell and type

  tar xzf openrefine-linux-2.7.tar.gz
  cd openrefine-2.7

This will start OpenRefine and open your browser to its starting page.

Shut down: Press Ctrl-C in the shell.

Running & Configuration

By default (and for security reasons) Refine only listens to TCP requests coming from localhost ( on port 3333). If you want to respond to TCP requests coming to any IP address the machine has, run refine like this from the command line:

  ./refine -i

On macOS, you can add a specific entry to the Info.plist file located within the app bundle



Development Version

If you want to try the very latest developments in OpenRefine, you can try installing the current development version. The development version hasn't had the same level of testing that the release version has, but we generally try to keep it in good shape. It will have bug fixes which are not yet available in the release version, but may also have new bugs as well.

The installation process for the Development version is more complex as the software has not been prepared for general distribution.

HOME > Users

Clone this wiki locally
You can’t perform that action at this time.