ZotFile - Advanced PDF management for Zotero

edited July 13, 2017
NOTE: Zotfile 5 for Zotero 5 is now online and the webpage was updated with instructions how to install version 5. Just go to the zotfile webpage www.zotfile.com.

ZotFile is a Zotero plugin to manage your attachments: automatically rename, move, and attach PDFs (or other files) to Zotero items, sync PDFs from your Zotero library to your (mobile) PDF reader (e.g. an iPad, Android tablet, etc.) and extract annotations from PDF files.

See zotfile webpage for more information.

If you are using this add-on, please consider a donation through paypal. Just go to the webpage above and click on 'donate'.

Attach New Files to Zotero Items
ZotFile can rename and add the most recently modified file from the Firefox download or a user specified folder as a new attachment to the currently selected Zotero item. It renames the file using metadata from the selected Zotero item (user configurable), and stores the file as a Zotero attachment to this item (or alternatively, moves it to a custom location).

(Batch) Rename and Move Attachments based on Zotero Metadata
The user can also select any number of Zotero items and automatically rename and move all attachments of these items according to the user defined rules using metadata of the respective zotero item (batch processing).

Sync PDFs with your iPad or Android tablet
To read and annotate PDF attachments on your mobile device, zotfile can sync PDFs from your Zotero library to your (mobile) PDF reader (e.g. an iPad, Android tablet, etc.). Zotfile sends files to a location on your PC or Mac that syncs with your PDF reader App (PDF Expert, iAnnotate, GoodReader etc.), allows you to configure custom subfolders for easy access, and even extracts the annotations and highlighted text to Zotero notes when you get the files back from your tablet. For instruction, click here.

Extract Annotations from PDF Files
After highlighting and annotating pdfs on your tablet (or with the PDF reader application on your computer), ZotFile can automatically extract the highlighted text and note annotations from the pdf. The extracted text is saved in a Zotero note. Thanks to Joe Devietti, this feature is now available on all platforms based on the pdf.js library.
  • Hi,
    nice tool.
    however, I have problems when I "zotfile-rename,move and attach files" It says not able to find the files in the folder.
    I've changed the about:config to
    C:\Documents and Settings\admin\Application Data\Mozilla\Firefox\Profiles\wi2i2oeo.default\zotero
    what could be wrong? I also tried to replace "\" by "/" but no result.
  • Hi, can you be a bit more specific and tell me which preference you changed to "C:\Documents and Settings\admin\Application Data\Mozilla\Firefox\Profiles\wi2i2oeo.default\zotero"? I assume that it was extensions.zotfile.source_dir !?
    This is the directory where ZotFile looks for the most recently modified file. More specifically, ZotFile looks for files which end with pdf, doc, txt, or rtf and then selects the most recently modified. The error message you describe should usually occur when ZotFile does not find a file which has one of the mentioned endings in the source dir. Are you sure that there is one of these files in the folder you specified? If you are sure, I will further look into this issue and try to figure out why it does not work.
  • Yes, I did change the extensions.zotfile.source_dir to the default folder where zotero save pdf files:
    C:\Documents and Settings\admin\Application Data\Mozilla\Firefox\Profiles\wi2i2oeo.default\zotero
    C:\Documents and Settings\admin\Application Data\Mozilla\Firefox\Profiles\wi2i2oeo.default\zotero\storage
    I also reconfigured zotero to save it in different folder:
    And I am sure I have new pdf files in the folder.

    May I point it out: looking for the new files might be a good choice. It could make problems when I save multiple articles and then download pdf files. It could be confused and link pdf to wrong items.

    It would be great to make a full-range stand-alone application that looks into the sql database and change all filenames and relink back to sql database.

    But, nevertheless, thanks for your work.
  • Hi, there are actually no files directly in Zotero's storage folder because all the files are placed in subfolders. Since zotfile does not look for files in subfolders, it does not find any files and shows the error message.
    But I also think that this is not the right way to use zotfile. I wrote the plugin to avoid zotero's approach to store files mainly because I prefer to link attachments from an arbitrary directory and because I prefer to give them meaningful names. Both allow me to easily access these files from outside Zotero because they are stored in a certain directory (such as a Literatur folder) and because I can easily recognize them through their filename. If you want to use zotfile you should change the preference extensions.zotfile.source_dir to your download folder in Firefox. After having done this you can just download a pdf with Firefox, select an item in Zotero (the one to which the pdf should be attached) and press the zotfile bottom. zotfile will rename the pdf using metadata from the selected file, move it to the directory you have specified and attach it to the item as a linked attachment.
  • Looks like a great tool, Joscha! But after restart, I can't see the paper clip link in my zotero toolbar.

    I downloaded Zotfile into Zotero 1.5b1, restarted Firefox 3.0.6, updated about:config settings to be (source_dir= /Users/Shared/JM Downloads) (dest_dir= /Users/Shared/JM Documents/Research/Downloaded Sources). I don't have lytero. I'm running Mac OS X 10.5.6

    How can I tell if I'm running Preview 3.6?
  • Hi Joscha,
    nice tool, however, I am experiencing some problems:

    There is no zotfile (paper-clip) button in between Add note and Handglass buttons in Zotero after instalation and restart, what could go wrong?

    If I prefer to keep Zotero´s way of PDF storage,
    should I write c:\Documents and Settings\PC\Data aplikací\Mozilla\Firefox\Profiles\m6yvwmbp.default\zotero in dest_dir, please? (because Zotero is storing PDFs in another subfolders within this folder).
  • Hey,

    JM, you are fine with 1.5b1 which is a newer release then 1.5 Preview 3.6 (I will change this on the website).

    In regard to the problem with the paper-clip button somebody else had the same problem and told me that it worked after he reinstalled the plugin. So just try this and let me know whether it works for you. By the way, you should also see a zotfile entry at the button of the menu when you right click a zotero item.

    Lanius, you could use "c:\Documents and Settings..." as the dest_dir but it would still be different then the way Zotero stores pdfs. 1) Zotfile would just place the files in the folder without using the subfolder system zotero is using. 2) zotfile just creates a linked attachment which can be at any place whereas zotero uses this place to store copies of stuff (if you press add attachment and then "Store copy of file). I don't know whether this makes a difference for syncing pdf attachments (I have never tried). There might be other difference in the way Zotero treats the two types of attachments (stored copies and linked attachments).
  • Hi Joscha,
    reinstallement helped,
    version 1.5b1 works

    I will play with PDF storage folder placement and syncing...
    Many thanks,
    Best wishes
  • I have created PDFs folder within ZOTERO folder for dest_dir, it works, however, files within this folder are not synced, nor indexed...
  • Hey Lanius, I anticipated the problem with syncing because I expected that Zotero only syncs stored pdfs and not linked attachments. I guess this is an disadvantage of the linked attachment approach. The advantage (at least for myself) is that I can store the files where ever I want.
    Indexing should work though. I stopped using it because it causes Zotero to freeze for a second or so. Currently, I am not sure what to do about it. But I might look into it when I find some time in the near future.
  • Hi Joscha,

    For the moment, I am solving both problems attaching renamed PDFs from the destination folder, this way is still much more comfortable than manual renaming...

    Many thanks, Best, Lanius
  • JM
    edited March 3, 2009
    Hi Joscha,
    Reinstall did the trick. Paper clip and right-click contextual menu are both there, and work beautifully! And indexing works too. Thanks again. Never again will I wonder whether I meant to read 346723.pdf or 7223541.pdf.

  • Er, spoke too soon. After rebooting my machine and restarting Firefox, I've got no paper clip and can't access the ZotFile preferences in the Add-Ons menu (although ZotFile is visible there and appears enabled). Tried reinstalling again & restarting Firefox several times, w/ no luck. Any ideas? (Zotero 1.5b1, Firefox 3.0.6, Mac OS X 10.5.6)
  • I have a (slightly) different bug. I see the paper clip icon that others seem to have missing BUT I don't get the right-click context menu to make it all work... & pressing the paper-clip icon doesn't make it work either (So no PDF's get moved or re-named etc..). I have set up the about:config settings for my installation & tried re-installing the addon a couple of times - but - no luck. Any ideas (Zotero 1.5b1, Firefox 3.1b2, WinXP SP3) ?
  • Hi,
    JM: the problem is that I really don't know anything about the stuff which is related to placing the icon in Zotero. I just copied the code from lytero and changed what I thought should be changed. That's also the reason why lytero and zotfile do not work together. So I can't really help. Maybe there is somebody around who knows something about this and is willing to look into this stuff.
    I have one idea though (it's annoying however): You can try whether you have the same problem with a different firefox profile. If you don't, you might consider transferring your data to the new profile.
    Here are some information about profiles:

    srg.qut: Your problem seems to be different. Maybe it's related to Firefox 3.1b2. I can't tell until I am using 3.1 myself. If this is the case, I will work on the problem when 3.1 is released.
  • Hi

    There is a small bug in this software. If the filename extension is in upper case (file.PDF) it is not included.

    This can be fixed by changing line 182 of zotfile.js from

    var filetype=this.getFiletype(file.leafName);

    var filetype=this.getFiletype(file.leafName).toLowerCase();

    For those that want to do this fix themselves, the file is located under your firefox profile. On my mac the path is

    ~/Library/Application Support/Firefox/Profiles/l5auep3s.Mikko/extensions/zotfile@columbia.edu/chrome/content/zotfile/zotfile.js

  • With the proposed fix, the file name extension still stays upper case. A better fix would be to change line number 158



  • After testing this great plugin for a while I ended up accidentally attaching a wrong file several times. This can happen if you have downloaded more files after the one that you want to attach.

    One possible solution to this issue would be a confirmation dialog. This can be done by adding the following on line 240. (You also need to add the closing bracket) This could be made optional at the settings, but would be a good feature for the next release.

    if(confirm("Do you want to rename and link file \'" + lastfile_oldpath + "\' to the currently selected Zotero item?")){

  • I did some changes and now this is just the perfect plugin for my needs
    -makes filename extension lower case
    -asks for a confirmation before attaching a file
    -attaches the file as a zotero attachment instead of linked file

    The content of my modified zotfile.js can be found here


  • That's great, Mikko. Thanks!
    Do you mid if I add this stuff to zotfile? I thought about providing two further options through about:config: a) whether people want to be ask for a confirmation and b) whether they want to link or attach the file to zotero.
    Can you also point me at the changes for attaching files? Are these two lines all the changes?
    Zotero.Attachments.importFromFile(lastfile, item.itemID);

    //Delete the old file that is not longer needed
  • Feel free to use the code anyway you like.

    A diff of the original and my additions can be found at http://pastebin.com/mda4b42c The changes are also now highlighted in the code I posted http://pastebin.com/m618943b

    I did three things
    1) Added toLowerCase in the function that gets the file name extension
    2) Added a confirm dialog and enclosed the code for copying the file and creating the Zotero attachment inside an if-block
    3) Changed the linkFromFile to importFromFile and added a command to remove the extra file since importFromFile makes a copy of the original


  • edited July 12, 2012
    Hi, I have updated the plugin with Mikko's suggestions.


    The changes:

    1) confirm dialog (you can turn this of with the confirmation option)
    2) You can now decide whether you want to link or import the file (.import option). Zotfile either creates a link (.import=false) to the renamed file (which means that the file remains in the dest_dir) or imports the file so that Zotero stores a copy if it (in this case the file at dest_dir is deleted).
    3) small bug fixed
  • Nice plugin!

    Would it be possible to use journal abbreviation instead of journal (and journal if no abbreviation exist)? The idea would be to have shorter file names with the same information, and should work well in natural sciences.

    Also; white spaces in the filename elements (author, journal ect) should be replaced with _ imho - or hopefuly the option given

    Shame that import dosent work in linux... Minor flaw I can live with :-D

    Keep up the nice work!
  • I love this plugin, and would like to thank Joscha for creating it.

    Just one tiny request, please: In the renaming process, underscores are not inserted before, between, and after the words "et al". This is slightly inelegant, since underscores are used instead of spaces elsewhere, and it also messes up the directory listing (Bloggs et al comes before Bloggs_2000). Do others agree, and, if so, could it be fixed, please?

    Thanks again -- this is a great addition to Zotero!
  • I found a small bug in the plugin that causes the Zotfile button to disappear.

    On OS X and Firefox 3.1, do the following:
    1) Open firefox
    2) Open zotero
    3) From file menu, choose "open new window"
    4) Open zotero in this new window - Zotfile icon does not show

  • this is a cross-platform bug. Also true in Linux.
    (where, by the way, the import function doesn't work either (attachment never worked). Josua has tried his best, but if anyone else wants to take a shot?
  • hey,

    stervbo and Keith: I have uploaded a new version which allows you to a) use journal abbreviation ('%s' in the renameFormat option), b) replace blanks with underscores '_' (option: replace_blanks), and c) change the string which is added after the first author if the option 'add_etal=true' (option: 'etal' - default is " et al" so that the same filenames are produced as before. You can just replace this with "_et_al" and get the desired result).

    mronkko: There are several people who have reported problems with the zotfile button. Your description is very helpful because it's easy to reproduce the bug. The problem is that my knowledge about the XUL language (Firefox User Interface Language) is very limited (for the interface part (the button), I just copied the interface code from lytero). So I have no idea where the bug comes from. I would be happy if anyone is willing to help.
  • Have you tried asking Mozilla developer forums?


  • This seems great, but what I'd really like is something a little different. I already have hundreds of PDFs sitting on my HD and it would take days to import them into Zotero by finding the matching titles and re-importing them. Since almost all these files are already named with the relevant meta-data, I'd like to be able to have a plugin which attempts to match these PDFs to existing citations and then imports them to Zotero.

    A second feature I'd like is similar to what Sente can already do - where when there is no matching citation you can do a search based on data in the PDF file itself: DOI if there is one, or author/title information, and then to create a new entry at the same time as importing the PDF. (See the Sente website for short videos showing how this works.)
  • If you just add the PDFs to zotero & they can be indexed, then you can right click & choose to retrieve metadata for the pdf. It will look on Google scholar for the information.

    It is planned to expand this to use other methods of retrieving PDF metadata (such as through DOIs).
This discussion has been closed.