Installation Instructions

Thomas Morrell edited this page Apr 19, 2017 · 31 revisions
Clone this wiki locally

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.

Requirements

Java JRE installed

Release Version

  1. 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)
  2. Download OpenRefine here.
  3. Install it as detailed below for your operating system (Windows, macOS, Linux).
  4. As long as OpenRefine is running, you can point your browser at http://127.0.0.1:3333/ to use it, and you can even use it in several browser tabs and windows.
  5. 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.

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.

Install the Release Version on

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

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

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

1. Install Homebrew from here

2. In Terminal enter

  brew tap caskroom/versions
  brew cask install openrefine-dev

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.

Linux

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

  tar xzf google-refine.tar.gz
  cd google-refine
  ./refine

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 (127.0.0.1 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 0.0.0.0

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

  <string>-Drefine.host=0.0.0.0</string>