Table of contents generated with markdown-toc

Install

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.

Requirements

  1. [[Java JRE/JDK installed Setup-JAVA]] (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

OpenRefine works best on browsers based on Webkit, such as:

We are aware of some minor rendering and performance issues on other browsers such as Firefox.

Release Version

Windows

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, make sure you back up your OpenRefine workspace. This will ensure that if problems occur, no data will be lost and you will be able to revert to a previous.

macOS

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. (for details WHY you have to do this, see Issue #2191. Note that in macOS Catalina the message shown has the additional text “macOS cannot verify that this app is free from malware”, but the reason for the message and the solution is the same)

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
  3. 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.

Obtaining server logs on Mac

Sometimes it is useful to access the OpenRefine server logs to understand the cause of an issue. Here are the steps to run OpenRefine in a terminal on MacOS:

Linux

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
  ./refine

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

Shut down: Press Ctrl-C in the shell.

Upgrade

Prepare for upgrading

  1. Backup your OpenRefine data in your workspace
  2. (Optional) Export existing OpenRefine Project(s) that you want to continue to work with after upgrade (create *.tar.gz files)

Perform the upgrade

  1. Install OpenRefine latest release
  2. Install updated extensions (RDF, etc.)
  3. Copy your previously backed up OpenRefine workspace directory back into place, following reverse of step 1.
  4. (Optional) Begin to import your OpenRefine .tar.gz Projects that you intend to work with, 1 by 1 while verifying things are OK.

Alternatives

Nightly Releases

We provide easy to install packaged snapshot releases of the latest development version of OpenRefine, which contain the latest features implemented but might also be less stable. You should backup your workspace before trying one.

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.

Running As a Server

By default (and for security reasons), Refine only listens to TCP requests coming from localhost (127.0.0.1), on port 3333 (by default). If you want to share your Refine instance with colleagues and respond to TCP requests to any IP address of the machine, run Refine like this from the command line:

./refine -i 0.0.0.0

or set this option in refine.ini:

REFINE_HOST=0.0.0.0

or set this JVM option:

-Drefine.host=0.0.0.0

On macOS, you can add a specific entry to the Info.plist file located within the app bundle (/Applications/OpenRefine.app/Contents/Info.plist):

<key>JVMOptions</key>
<array>
  <string>-Drefine.host=0.0.0.0</string>
  …
</array>

Please note that if your machine has an external IP (is exposed to the Internet), you should not do this, or should protect it behind a proxy or firewall, e.g. nginx.