Skip to content

Requirements and installation

Islandora Workbench is actively used on Linux, Mac, and Windows.

Requirements

The preferred method for installing Workbench is to install it within a Python virtual environment. You can use these instructions on how to install Workbench within a virtual enviroment for macOS, Linux, or Windows.

Warning

Some systems have both Python 2 and Python 3 installed. It's a good idea to check which version is used when you run python. To do this, run python --version, which will output something like "Python 2.7.17" or "Python 3.8.10". If python --version indicates you're running version 2, try running python3 --version to see if you have version 3 installed.

If you are using Drupal 8.5 or earlier, please refer to the "Using Drupal 8.5 or earlier" section below. If you are using Python 3.8, please refer to that section below.

macOS, Homebrew and pip

The preferred method for installing Islandora Workbench is now to use a virtual environment. You can use these instructions on how to install Workbench with a virtual enviroment for macOS. As of around 2024, trying to install Islandora Workbench on a Mac with Homebrew using pip will print a warning message and fail.

If you installed Workbench via Homebrew on a Mac using an alternate version of Python 3.x on your system, you may need to run Workbench by calling that Python interpreter directly. For Python 3.x installed via Homebrew, that will be at /opt/homebrew/bin/python3, so to run Workbench you would use /opt/homebrew/bin/python3 workbench while in the islandora_workbench directory.

Installing Islandora Workbench

The preferred method for installing Workbench is to install it within a Python virtual environment. You can use these instructions on how to install Workbench within a virtual enviroment for macOS, Linux, or Windows.

Installation involves two steps:

  1. if using a Python virtual environment, make sure your envrionment is set up as described on the page linked above
  2. cloning the Islandora Workbench Github repo
  3. running Python's Pip tool to install the required external Python libraries (specific commands provided above)

Step 1: cloning the Islandora Workbench Github repo

In a terminal, run:

git clone https://github.com/mjordan/islandora_workbench.git

This will create a directory named islandora_workbench where you will run the ./workbench command.

Step 2: running pip to install the required Python libraries

Note

As of May 10, 2026 (commit c0d292c), Islandora Workbench no longer uses setup.py to install its Python libraries. The directions below are up to date.

Preferred method: installing Python libraries in a virtual environment

Set up and activate your virtual environment, then run:

python -m pip install .

Alternative method: installing Python libraries in the user directory

Using virtual environments adds a little overhead to running Workbench, so if you would prefer to avoid that overhead, the preferred place to install Python libraries is in your user directory. To do this, change into the "islandora_workbench" directory created by cloning the repo, and run the following command:

python -m pip install --user .

Install Python librareis in your system Python

Warning

Only use this method after consulting with your local IT department

A less common method is to install the required Python libraries into your computer's central Python environment. To do this, omit the --user (note: you must have administrator privileges on the computer to do this):

sudo python -m pip install .

sudo is only required on Linux and Macs, on Windows you will need to run python -m pip install . as administrator.

Updating Islandora Workbench

Since Islandora Workbench is under constant development, you should update it often. Updating the Workbench source code is done in the same way regardless of how it was originally installed, but ensuring that the external Python libraries that Workbench uses are up to date is determined by how they were originally installed on your computer.

1. Updating the Islandora Workbench source code

Within the islandora_workbench directory, run the following git command:

git branch

The output of this command will list all your local git branches, but since you are likely updating the main branch, you should see * main in the list. If you see main without the leading asterisk, run the command

git checkout main

Once you are in the main branch, pull in the updates from Github:

git pull origin main

2. Updating the Python libraries

Note

All of the commands provided below end in a single period (.). This tells Pip where to look for the list of external libraries, in this case, in the current directory.

If Workbench was originally installed in a virtual environment:

  1. Within the islandora_workbench directory, ensure that your virtual environment is active by looking for (venv) at the beginning of your command prompt (additional information and examples can be found here).
  2. Run the following command: python -m pip install --upgrade .

If Workbench was originally installed using Pip's --user option:

  1. Within the islandora_workbench directory, run the following command: python -m pip install --user --upgrade .

If Workbench was originally installed in your computer's system Python:

  1. Check in with your local IT department.
  2. Within the islandora_workbench directory, run the following command: sudo python -m pip install --upgrade .

Keeping the Islandora Workbench Integration Drupal module up to date

Islandora Workbench communicates with Drupal using REST endpoints and Views. The Islandora Workbench Integration module (linked above in the "Requirements" section) ensures that the target Drupal has all required REST endpoints and Views enabled. Therefore, keeping it in sync with Islandora Workbench is important.

Workbench checks the version of the Integration module and tells you if you need to upgrade it. To upgrade the module, update its code via Git or Composer, and follow the instructions in the "Updates" section of its README.

Configuring Drupal's media URLs

Islandora Workbench uses Drupal's default form of media URLs. You should not need to do anything to allow this, since the admin setting in admin/config/media/media-settings (under "Security") that determines what form of media URLs your site uses defaults to the correct setting (unchecked):

Field machine names

If your site needs to have this option checked (so it supports URLs like /media/{id}), you will need to add the following entry to all configuration files for tasks that create or delete media:

standalone_media_url: true

Note

If you change the checkbox in Drupal's media settings admin page, be sure you clear your Drupal cache to make the new media URLs work.

Using Drupal 8.5 or earlier

When ingesting media in Drupal versions 8.5 and earlier, Islandora Workbench has two significant limitations/bugs that you should be aware of:

  • Approximately 10% of media creation attempts will likely fail. Workbench will log these failures. Additional information is available in this issue.
  • A file with a filename that already exists in Islandora will overwrite the existing file, as reported in this issue.

To avoid these issues, you need to be running Drupal version 8.6 or higher.

Warning

If you are using Drupal 8.5 or earlier, you need to use the version of Workbench tagged with drupal_8.5_and_lower (commit 542325fb6d44c2ac84a4e2965289bb9f9ed9bf68). Later versions no longer support Drupal 8.5 and earlier.

Using Python 3.8

Python 3.8 reached end of life in October 2024. If you cannot upgrade from Python 3.8, you may be interested in the Python 3.8 EOL release of Islandora Workbbench.

Using Workbench within a Docker container

If you would rather avoid installing the Python libraries required by Islandora Workbench on your computer, and you have make and Docker installed, you can build a container and run Workbench within it easily. To do so, follow these steps:

  1. Clone Islandora Workbench from Github as described above.
  2. In the islandora_workbench home directory, run make run-workbench-in-docker. This builds the container, mounts the islandora_workbench directory inside the container at /workbench, and puts you into a shell within that directory.
  3. To exit the container and shut it down, type exit, which will place you back into your islandora_workbench home directory.

If you want to rebuild the container using the most recent Workbench code, run the necessary git commands as documented in the "Updating Islandora Workbench" section above and then run make rebuild-islandora-workbench. The resulting rebuilt container will contain the most recent Islandora Workbench code.

Note

The container maps the islandora_workbench directory on your host computer to the /workbench directory within the container. This means that you can configure and run Workbench in the same way you would as if it were installed on your host computer as long as all of your configuration files and input data are relative to, or absolute in relation to, your host computer's islandora_workbencn directory.

For example, you can open a configuration file at islandora_workbench/myconfig.yml in your desktop text editor and modify it, but run Workbench within the container's /workbench directory like python workbench --config myconfig.yml --check. Same goes for values in your configuration's input_dir setting -- a value like batch_01 (which is located at islandora_workbench/batch_01 on your host computer) will be understood by Workbench running within the container as /workbench/batch_01.