Tabula Documentation

The core logic for reconstructing tables from PDFs is located in the tabula-java repository. You can incorporate it into JVM languages (Java, Scala, Clojure) via its JAR file.

There are also community-maintained bindings for other languages:

• R: tabulizer
• Node.js: tabula-js
• Python: tabula-py
• JRuby: tabula-extractor (Deprecated)

To use Tabula on Windows:

1. Download tabula-win.zip from the official site.
2. Unzip the contents and run tabula.exe.
3. A browser should automatically open to http://127.0.0.1:8080/.

Troubleshooting Encoding Errors: If you encounter org.jruby.exceptions.RaiseException: (Encoding::CompatibilityError), follow these steps:

1. Open Command Prompt.
2. cd to the directory containing tabula.exe.
3. Run chcp 65001 to change the codepage to Unicode.
4. Run tabula.exe.

You can run Tabula in a containerized environment using Docker Compose. This example uses the amazoncorretto:17 image.

1. Create a directory and enter it.
2. Download the tabula-jar package (e.g., version 1.2.1) and unzip it.
3. Create a docker-compose.yml file with the following configuration:

services:
  tabulapdf:
    image: amazoncorretto:17
    container_name: tabulapdf-app
    command: >
      java -Dfile.encoding=utf-8 -Xms256M -Xmx1024M -Dwarbler.port=8080 -Dtabula.openBrowser=false -jar /app/tabula.jar
    volumes:
      - ./tabula:/app
    ports:
      - "8080:8080"

4. Run the application with docker compose up -d.

To build a portable .zip containing a Windows .exe, follow these steps:

1. Download Launch4J 3.1.X (beta).
2. Unzip Launch4J into the Tabula repository root so that the launch4j directory is present.
3. (On 64-bit Linux) Install 32-bit libraries if necessary (e.g., sudo apt install lib32z1 lib32ncurses5).
4. Run the windows rake task.

The resulting tabula_win.zip will be located in the build directory.

WEBSERVER_VERSION=9.4.31.v20200723 MAVEN_REPO=https://repo1.maven.org/maven2 rake windows

To run Tabula in a development environment, you must use JRuby (specifically the 9000 series, e.g., JRuby 9.1.5.0).

1. Install JRuby via rvm, rbenv, or direct download.
2. Clone the repository and install dependencies using bundler and jbundle.
3. Start the development server using rackup via JRuby.

If you encounter encoding errors, set the JAVA_OPTS environment variable to -Dfile.encoding=utf-8.

The server is accessible at http://127.0.0.1:9292/.

git clone git://github.com/tabulapdf/tabula.git
cd tabula

gem install bundler -v 1.17.3
bundle install
jruby -S jbundle install

# Start the development server
jruby -G -r jbundler -S rackup

To run Tabula manually using a JAR file:

1. Download tabula-jar.zip and unzip it.
2. Open a terminal and cd into the unzipped directory.
3. Run the following command:

java -Dfile.encoding=utf-8 -Xms256M -Xmx1024M -jar tabula.jar

By default, Tabula binds to port 8080. You can change this using the warbler.port option.

If the standard rake task fails, you can manually generate the Windows executable using rake war and ant.

Note: The generated tabula.exe requires tabula.jar to be in the same directory to run.

# From the root directory
WEBSERVER_VERSION=9.4.31.v20200723 MAVEN_REPO=https://repo1.maven.org/maven2 rake war
cd launch4j
ant -f ../build.xml windows

# To package for distribution
cd build/windows
mkdir tabula
cp tabula.exe ./tabula/
cp ../tabula.jar ./tabula/
zip -r9 tabula_win.zip tabula

To use Tabula on Mac OS X:

1. Download tabula-mac.zip from the official site.
2. Unzip and open the Tabula app.
3. A browser should automatically open to http://127.0.0.1:8080/.

GateKeeper Workaround: If you see "Tabula is damaged and can't be opened":

1. Right-click on Tabula.app.
2. Select Open from the context menu.
3. Click Open in the dialog to allow the application to run.

Legacy Java Requirement: If you encounter errors regarding the Java Runtime Environment, download the "large experimental" package from the Tabula releases page, which includes its own JRE.

To compile Tabula into a portable .zip archive for Mac OS X, use the macosx rake task.

Note: The Mac version bundles Java, resulting in a larger file size (~98MB) but ensures compatibility without requiring the user to install Java separately. If you are not sharing the app and only running it locally, you can remove the codesigning block in build.xml (lines 44-53).

WEBSERVER_VERSION=9.4.31.v20200723 MAVEN_REPO=https://repo1.maven.org/maven2 rake macosx

If your Linux system has snap installed, you can install Tabula using the following command:

sudo snap install tabula

When running the Tabula development server, you can use the following environment variables to configure behavior:

• TABULA_DATA_DIR: Specifies the directory where uploaded data is stored. If not set, it defaults to the OS-dependent application data directory (e.g., ~/.tabula on Linux, ~/Library/Application Support/Tabula on Mac).
• TABULA_DEBUG: When set to 1 (or any truthy value), prints extra status data during PDF processing. Defaults to false.

TABULA_DATA_DIR="/tmp/tabula" \
TABULA_DEBUG=1 \
jruby -G -r jbundler -S rackup

You can deploy Tabula using Docker Compose. The configuration defines a web service that builds from the local context and runs the application using jruby and rackup on port 9292.

Key configuration details:

• Port Mapping: The application is accessible on host port 9292.
• Volumes:
  • The current directory is mounted to /app inside the container.
  • A named volume bundle is used for /usr/local/bundle to persist Ruby dependencies.
• Command: jruby -G -r jbundler -S rackup -p 9292 -o 0.0.0.0 config.ru

version: '3.3'
services:
  web: &web
    build:
      context: .
    command: "jruby -G -r jbundler -S rackup -p 9292 -o 0.0.0.0 config.ru"
    volumes:
      - .:/app
      - bundle:/usr/local/bundle
    ports:
      - 9292:9292

volumes:
  bundle: