This is an old revision of the document!
Building the Zotero Desktop App
Note: If you don't plan to make any code changes yourself, and only wish to run the latest prerelease versions of Zotero, you can just install a beta build.
Build Steps
Windows users: The following commands assume a POSIX-compliant system. To build Zotero on Windows, please follow the Windows-specific steps first.
- Make sure you have Git and Git LFS installed.
- Clone the Zotero source code:
git clone --recursive https://github.com/zotero/zotero zotero-client
- Change to the source code repo:
cd zotero-client
- Check your system for the necessary tools and install any that are missing:
app/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.
- Install Node.js modules using Node 18 or later:
npm i
- Build and run Zotero:
app/scripts/build_and_run -r
The build will be placed in the app/staging/
folder in unpackaged form.
To build Zotero for another platform, first prepare Zotero's JavaScript source by running npm run build
(or keep it prepared automatically as you make changes with npm start
) and then run app/scripts/dir_build
with the -p
flag for the desired platform (e.g., app/scripts/dir_build -p w
for Windows).
Running Your Custom Build
After you've built the client, you can continue to run it from app/staging/
or move the app directory to a location of your choosing.
For development, you'll generally want to use the build_and_run
helper script, but you can also call the launcher directly:
Mac
app/staging/Zotero.app/Contents/MacOS/zotero
Linux
app/staging/Zotero_linux-x86_64/zotero
Windows
app/staging/Zotero_win-x64/zotero.exe
Command-line Flags
You'll need to rebuild the client each time you make code changes. In most cases, you'll want to use the helper script below.
You can pass -ZoteroDebugText
or -ZoteroDebug
to the executable for real-time debug output from Zotero.debug()
, and -jsconsole
to open the Error Console. 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 102 ESR devtools by going to about:debugging
and pointing to localhost port 6100. You'll first need to enable browser chrome/add-on and remote debugging in the settings (gear icon) pane of the Firefox Web Console and pass -r
to build_and_run
or -t
to dir_build
when building Zotero. The -debugger
flag is also available in pre-built beta builds. The devtools in newer versions of Firefox won't work, so be sure to use Firefox 102 ESR in a separate Firefox profile and disable automatic updates to avoid being updated to a newer version.
Helper Script
For local development, you'll want to use the build_and_run helper script, which can automate rebuilding Zotero and starting it with debug output enabled and the error console open. Create an alias for app/scripts/build_and_run
with an appropriate name (e.g., zotero-source
), or create a shell script in your path that selects a preexisting development profile and passes on command-line parameters:
#!/bin/bash -e export ZOTERO_PROFILE="Dev" ~/zotero-client/app/scripts/build_and_run "$@"
You can then run, e.g., zotero-source -r
to rebuild Zotero with your changes and start it up.
Options:
-r Rebuild (calling `npm run build` automatically if `npm start` isn't running)
-b Skip bundled styles and translators
-d Start devtools server on port 6100
Running Zotero Plugins
Packaging
Mac
- In Keychain Access, create
build
keychain with password - Import Developer ID certificate, public key, and private key
- Set up app-specific password for Apple developer account
- Create a
config-custom.sh
file inapp/
:SIGN=1 KEYCHAIN=build KEYCHAIN_PASSWORD=<keychain password> NOTARIZATION_BUNDLE_ID=<bundle id (e.g., org.foo.App) — only used for notification emails> NOTARIZATION_USER="<username of Apple developer account>" NOTARIZATION_PASSWORD="<app-specific password for Apple developer account>" BUILD_PLATFORMS=m
Windows
- 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
) orinput
. If set totrue
(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.
- Install NSIS 3 and install the necessary plugins by running
app/win/download-nsis-plugins
. - The Windows SDK is needed for the included
signtool.exe
utility. You can uncheck all other installation options. Adjust the path inapp/config.sh
to point to the correct version of the Windows SDK.
Installation and Packaging Notes
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.
Protocol handler registration
Zotero should be registered as the system's default protocol handler for the zotero://
protocol.
File extensions and MIME types
Zotero should be registered as a handler for the following file extensions and MIME types:
File type description | File extension(s) | MIME type(s) |
---|---|---|
Research Information Systems Document | ris | application/x-research-info-systems application/x-endnote-refer text/x-research-info-systems text/application/x-research-info-systems text/ris ris |
ISI Common Export Format Document | ciw, isi | application/x-inst-for-Scientific-info |
Metadata Object Description Schema Document | mods | application/mods+xml |
Resource Description Framework Document | rdf | application/rdf+xml |
BibTeX Document | bib, bibtex | application/x-bibtex text/x-bibtex |
MARC Record | mrc, marc | application/marc |
CSL Citation Style | csl | vnd.citationstyles.style+xml |
Distribution
Distribution steps are beyond the scope of this page, but see app/scripts/build_and_deploy
for an example of the necessary steps.