Note: The following commands assume a POSIX-compliant system. On Windows, first install Cygwin, install Git through Cygwin, and then run the following commands in the Cygwin terminal.

For historical reasons, several separate build processes are currently required to build the Zotero client. An included helper script, dir_build, can automate the process of creating a client build from an unpacked local Zotero git repository. We plan to optimize the build process further after Zotero 4.0 is discontinued.

1. Clone the Zotero source code, Zotero XPI build scripts, and standalone client build scripts:

   git clone --recursive https://github.com/zotero/zotero zotero-client
   git clone --recursive https://github.com/zotero/zotero-build
   git clone --recursive https://github.com/zotero/zotero-standalone-build

2. Change to the source code repo and install Node.js modules:

   cd zotero-client
   npm i

3. Run the JS build process (Babel, etc.):

   npm run build

   This will compile source files into a build/ directory.

4. Change to the zotero-standalone-build directory and check your system for the necessary tools:

   cd ../zotero-standalone-build
   scripts/check_requirements

   This script checks all requirements for the official Zotero distribution system. If you're only creating a custom build, you only need the build requirements listed at the top, not the distribution requirements.

5. Download the Firefox runtime for the desired platform(s) (m=Mac, w=Windows, l=Linux):

   ./fetch_xulrunner.sh -p m

   This will download Firefox runtime files to the xulrunner/ subdirectory and modify them for use with Zotero.
   
   Note: Due to the way Firefox is packaged, fetch_xulrunner.sh can retrieve Mac builds only on macOS.

6. Build Zotero:

   scripts/dir_build

   This creates a build for the current platform from the Zotero git repository you cloned to ../zotero-client (using the current branch and code). You can pass -p to create a build for another platform.

Your desired build should now be available in the staging/ subdirectory in unpackaged form.

Distribution steps are beyond the scope of this page, but see scripts/build_and_deploy for an example of the necessary steps.

After you've built the client, you can run it via the GUI or from the command line:

staging/Zotero.app/Contents/MacOS/zotero

staging/Zotero_linux-x86_64/zotero

staging/Zotero_win32/zotero.exe

You'll need to rebuild the client each time you make code changes by running npm run build in zotero-client followed by scripts/dir_build in zotero-standalone-build. For rapid iteration, we recommend combining these commands into a separate script. (We plan to optimize this process in the future.)

You can pass -ZoteroDebugText or -ZoteroDebug to the executable for real-time debug output. If you're working on something that doesn't require styles or translators, the -ZoteroSkipBundledFiles flag can speed up startup time after rebuilding. A -debugger flag will run the Mozilla devtools server, which you can connect to from the Firefox devtools on port 6100.

• Build requirements as indicated by scripts/check_requirements
• Unicode NSIS and install the following (Unicode!) plugins by copying the .dll files to NSIS\Unicode\Plugins folder
  • AppAssocReg, ApplicationID, InvokeShellVerb, ShellLink, and UAC
  • To install all at once, cd to the plugins folder and run the following commands:

    wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/AppAssocReg.dll
    wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/ApplicationID.dll
    wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/InvokeShellVerb.dll
    wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/ShellLink.dll
    wget https://github.com/mozilla/gecko-dev/raw/master/other-licenses/nsis/Plugins/UAC.dll

• The Windows SDK is needed for the included signtool.exe utility. Only the main Windows SDK component is required. If you experience errors with the installer, try uninstalling Microsoft Visual C++ 2010 Redistributable from your computer first.

1. Verify that git is set to check out files without modifying line endings.

   $ git config --global core.autocrlf
   

   The response should be either empty (meaning false) or input. If set to true (as it may be if you selected the default option while installing the Windows version of git), change this with the following command:

   git config --global core.autocrlf false

   See the git manual for details on this setting.

2. After checking out the zotero-standalone-build repository as explained above, adjust the paths in config.sh to point to the correct executables of NSIS and the Windows SDK. You might want to set SIGN=1 to 0, to stop getting error messages.
3. See scripts/dir_build for the individual commands to run. Omit the -s flag when calling ./build.sh to create the installer package.

Note: These instructions are not applicable on macOS, which handles protocol handler and MIME type registration through the bundled Info.plist file. Additionally, they are only applicable on Windows if for some reason you want to run Zotero without running the installer.

Zotero should be registered as the system's default protocol handler for the zotero:// protocol.

Zotero should be registered as a handler for the following file extensions and MIME types: