Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
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.
Java JRE installed (If you are running a 64 bit operating system, then it's recommended that you install 64 bit Java)
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 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 http://127.0.0.1:3333/ 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
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.
Install via Homebrew: Follow our detailed Homebrew installation guide, or follow quick steps below:
Install Homebrew from here
In Terminal enter
brew cask install openrefine
- 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.
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 ./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 macOS, you can add a specific entry to the Info.plist file located within the app bundle
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.