This is an old revision of the document!
File Renaming
Zotero automatically renames PDFs and other files saved to your library based on the bibliographic details of the parent item (title, author, etc.), freeing you from having to sort through piles of randomly named files or manually rename each new file to your preferred format.
Renaming Behavior
Zotero always renames files saved from the web (via the Zotero Connector, Add Item by Identifier, or Find Available PDF).
By default, Zotero will also rename stored files that you add to items as the first child attachment as well as files for which it successfully retrieves metadata. You can disable this by unchecking “Automatically rename attachment files using parent metadata” in the General pane of the Zotero settings. If an item already has an attachment, additional files will not be automatically renamed, so as to avoid changing the filenames of supplementary materials.
Linked files are not automatically renamed by default, but you can enable “Rename linked files” from the General pane of the Zotero settings to apply renaming to those as well.
Attachment Title vs. Filename
Attachments have two separate names: the attachment title shown in the items list and the filename of the file on disk.
The parent item row already displays metadata such as the title and authors, and since files are generally renamed using that same metadata, Zotero doesn't show the filename directly in the items list. Instead, it uses simpler, less-distracting attachment titles such as “PDF” or “EPUB” for the first file of a given type or includes additional information about the source of the file (e.g., “ScienceDirect Full Text PDF” for a file saved from ScienceDirect, or “Accepted Version” or “Submitted Version” for open-access files). Subsequent files added to an item from the filesystem will still get titles named after the filename (without the file extension), since those are likely to be supplementary files and the filename may be informative.
You can view and change the title and filename by clicking on the attachment and looking in the item pane.
Note: Prior to Zotero 7, the attachment title was set to the filename when manually running Rename File from Parent Metadata, which was a bug. People who were using ZotFile or who were unnecessarily running Rename File from Parent Metadata on every attachment (despite files already being automatically renamed) might be used to seeing filenames in the items list, but we'd encourage people to give the new behavior a try.
Customizing the Filename Format
By default, Zotero names files after the parent item's creator (1–2 authors or editors), year, and title:
Lee et al. - 2023 - The First Room-Temperature Ambient-Pressure Superconductor.pdf
While Zotero has always renamed files automatically, Zotero 7, currently in beta, introduces a new, powerful syntax for customizing filenames. The default format can be customized from the General pane of the Zotero settings.
This is the default template string:
{{ firstCreator suffix=" - " }}{{ year suffix=" - " }}{{ title truncate="100" }}
The following variables and parameters are supported:
Variables
Variable | Description |
---|---|
authors | Parent item's principal creators (depending on the item type these are authors or artists but not editors or other contributors). |
editors | Parent item's editors. |
creators | All parent item's creators. |
firstCreator | Parent item's creator (1–2 authors or editors). |
itemType | Parent item type. |
year | Year, extracted from parent item's date field. |
Any item field | Complete list of fields can be found at the bottom of this page. |
If a variable value starts or ends with a space, which is likely to happen when used in conjunction with the truncate
parameter, these spaces are removed from the filename.
Parameters
Parameter | Variables | Default Value | Description |
---|---|---|---|
truncate | All | Truncates variable value at fixed number of characters, e.g, {{ title truncate="20" }} will be replaced with the first 20 characters of parent item's title. Truncation happens after every other parameter has been applied, except for prefix , suffix and case . |
|
prefix | All | Prepends variable with given character(s), e.g., {{ title prefix="title" }} will be replaced by the word “title” followed by parent item's title. If variable is empty (e.g., item's parent has empty title), entire statement, including prefix, is ignored. |
|
suffix | All | Appends given character(s) at the end of a variable with, e.g., {{ title suffix="!" }} will be replaced by parent item's title followed by an exclamation mark. If variable is empty (e.g., item's parent has empty title), entire statement, including suffix, is ignored. |
|
case | All | Converts case of a variable, following values are accepted: upper , lower , sentence , title , hyphen , snake , camel . E.g., {{ title case="snake" }} will result in title_written_like_this in the file name. |
|
max | authors , editors , creators | Limits number of creators to use, e.g., {{ editors max="1" }} will be replaced with first editor of parent's item. |
|
name | authors , editors , creators | family | Customizes how creator name appears in the filename, with the following accepted options: family-given will use full name of the creator, beginning with family (last) name of the creator, given-family also uses full name but inverts the order, and options given and family will only use part of the parent item's creator's name. |
name-part-separator | authors , editors , creators | (single space character) | Defines what characters to use to separate given and family name, especially useful when combined with initialize . |
join | authors , editors , creators | , | Defines what characters to use to separate consecutive creators. |
initialize | authors , editors , creators | Enables use of initials for part or whole of creators name, with the following accepted options: full will use initials for the entire name, given and family will only use initials for that part of the name. Order of name parts is controlled by name parameter and only parts included by name parameter can be converted to initials. E.g. {{ authors name="given-family" initialize="given" }} will be replaced by a comma-separated list of authors, where each author's given name is replaced with an initial, followed by a dot and a space (e.g. J. Smith, D. Jones ). |
|
initialize-with | authors , editors , creators | . | Controls what character is appended to the initial, if name part was initialized. |
localize | itemType | Whether to use localized value of the item type variable, e.g., {{ itemType localize="true" }} will be replaced by parent item's type spelled in the language Zotero is using. |
Examples
A year of publication, followed by a hyphen-separated list of authors, followed by a title truncated at 30 characters:
Template: {{ year suffix="-" }}{{ authors name="family-given" initialize="given" initialize="-" join="-" suffix="-" case="hyphen" }}{{ title truncate="30" case="hyphen" }}
Filename: 2023-lee-sukbae-kim-ji-hoon-kwon-young-wan-the-first-room-temperature-amb.pdf
Anything not included inside a {{
bracket is copied to the filename literally:
Template: {{ itemType localize="true" }} from {{ year }} by {{ authors max="1" name="given-family" initialize="given" }}
Filename: Preprint from 2023 by S. Lee.pdf
Templates also support conditionals, certain part of the template can be included or excluded using a combination of if
, elseif
, else
. Condition must end with endif
. Template below will use DOI for journal articles and preprints, ISBN for books and title for any other item type:
{{ if itemType == "book" }}{{ISBN}}{{ elseif itemType == "preprint" }}{{ DOI }}{{ elseif itemType == "journalArticle" }}{{ DOI }}{{ else }}{{ title }}{{ endif }}
Complete List of Fields
abstractNote
accessDate
applicationNumber
archive
archiveID
archiveLocation
artworkMedium
artworkSize
assignee
audioFileType
audioRecordingFormat
billNumber
blogTitle
bookTitle
callNumber
caseName
citationKey
code
codeNumber
codePages
codeVolume
committee
company
conferenceName
country
court
date
dateDecided
dateEnacted
dictionaryTitle
distributor
docketNumber
documentNumber
DOI
edition
encyclopediaTitle
episodeNumber
extra
filingDate
firstPage
format
forumTitle
genre
history
identifier
institution
interviewMedium
ISBN
ISSN
issue
issueDate
issuingAuthority
journalAbbreviation
label
language
legalStatus
legislativeBody
letterType
libraryCatalog
manuscriptType
mapType
meetingName
nameOfAct
network
numPages
number
numberOfVolumes
organization
pages
patentNumber
place
postType
presentationType
priorityNumbers
proceedingsTitle
programTitle
programmingLanguage
publicLawNumber
publicationTitle
publisher
references
reportNumber
reportType
reporter
reporterVolume
repository
repositoryLocation
rights
runningTime
scale
section
series
seriesNumber
seriesText
seriesTitle
session
shortTitle
status
studio
subject
system
thesisType
title
type
university
url
versionNumber
videoRecordingFormat
volume
websiteTitle
websiteType