chrome.downloads

Description
Use the chrome.downloads API to programmatically initiate, monitor, manipulate, and search for downloads.
Permissions
downloads
This permission triggers a warning.

Manifest

You must declare the "downloads" permission in the extension manifest to use this API.

{
  "name": "My extension",
  ...
  "permissions": [
    "downloads"
  ],
  ...
}

Examples

You can find simple examples of using the chrome.downloads API in the examples/api/downloads directory. For other examples and for help in viewing the source code, see Samples.

Summary

Types
BooleanDelta
DangerType
DoubleDelta
DownloadDelta
DownloadItem
DownloadOptions
DownloadQuery
FilenameConflictAction
FilenameSuggestion
GetFileIconOptions
HeaderNameValuePair
HttpMethod
InterruptReason
State
StringDelta
UiOptions
Methods
acceptDanger
cancel
download
erase
getFileIcon
open
pause
removeFile
resume
search
setShelfEnabled
setUiOptions
show
showDefaultFolder
Events
onChanged
onCreated
onDeterminingFilename
onErased

Types

BooleanDelta

Properties

current
boolean optional
previous
boolean optional

DangerType

file

The download's filename is suspicious.

url

The download's URL is known to be malicious.

content

The downloaded file is known to be malicious.

uncommon

The download's URL is not commonly downloaded and could be dangerous.

host

The download came from a host known to distribute malicious binaries and is likely dangerous.

unwanted

The download is potentially unwanted or unsafe. E.g. it could make changes to browser or computer settings.

safe

The download presents no known danger to the user's computer.

accepted

The user has accepted the dangerous download.

Type

"file"

"url"

"content"

"uncommon"

"host"

"unwanted"

"safe"

"accepted"

"allowlistedByPolicy"

"asyncScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"unsupportedFileType"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScaning"

, or

"accountCompromise"

DoubleDelta

Properties

current
number optional
previous
number optional

DownloadDelta

Properties

canResume
BooleanDelta optional
The change in canResume, if any.
danger
StringDelta optional
The change in danger, if any.
endTime
StringDelta optional
The change in endTime, if any.
error
StringDelta optional
The change in error, if any.
exists
BooleanDelta optional
The change in exists, if any.
fileSize
DoubleDelta optional
The change in fileSize, if any.
filename
StringDelta optional
The change in filename, if any.
finalUrl
StringDelta optional
Chrome 54+
The change in finalUrl, if any.
id
number
The id of the DownloadItem that changed.
mime
StringDelta optional
The change in mime, if any.
paused
BooleanDelta optional
The change in paused, if any.
startTime
StringDelta optional
The change in startTime, if any.
state
StringDelta optional
The change in state, if any.
totalBytes
DoubleDelta optional
The change in totalBytes, if any.
url
StringDelta optional
The change in url, if any.

DownloadItem

Properties

byExtensionId
string optional
The identifier for the extension that initiated this download if this download was initiated by an extension. Does not change once it is set.
byExtensionName
string optional
The localized name of the extension that initiated this download if this download was initiated by an extension. May change if the extension changes its name or if the user changes their locale.
bytesReceived
number
Number of bytes received so far from the host, without considering file compression.
canResume
boolean
True if the download is in progress and paused, or else if it is interrupted and can be resumed starting from where it was interrupted.
danger
DangerType
Indication of whether this download is thought to be safe or known to be suspicious.
endTime
string optional
The time when the download ended in ISO 8601 format. May be passed directly to the Date constructor: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})
error
InterruptReason optional
Why the download was interrupted. Several kinds of HTTP errors may be grouped under one of the errors beginning with SERVER_. Errors relating to the network begin with NETWORK_, errors relating to the process of writing the file to the file system begin with FILE_, and interruptions initiated by the user begin with USER_.
estimatedEndTime
string optional
Estimated time when the download will complete in ISO 8601 format. May be passed directly to the Date constructor: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})
exists
boolean
Whether the downloaded file still exists. This information may be out of date because Chrome does not automatically watch for file removal. Call search() in order to trigger the check for file existence. When the existence check completes, if the file has been deleted, then an onChanged event will fire. Note that search() does not wait for the existence check to finish before returning, so results from search() may not accurately reflect the file system. Also, search() may be called as often as necessary, but will not check for file existence any more frequently than once every 10 seconds.
fileSize
number
Number of bytes in the whole file post-decompression, or -1 if unknown.
filename
string
Absolute local path.
finalUrl
string
Chrome 54+
The absolute URL that this download is being made from, after all redirects.
id
number
An identifier that is persistent across browser sessions.
incognito
boolean
False if this download is recorded in the history, true if it is not recorded.
mime
string
The file's MIME type.
paused
boolean
True if the download has stopped reading data from the host, but kept the connection open.
referrer
string
Absolute URL.
startTime
string
The time when the download began in ISO 8601 format. May be passed directly to the Date constructor: chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})
state
State
Indicates whether the download is progressing, interrupted, or complete.
totalBytes
number
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
url
string
The absolute URL that this download initiated from, before any redirects.

DownloadOptions

Properties

body
string optional
Post body.
conflictAction
FilenameConflictAction optional
The action to take if filename already exists.
filename
string optional
A file path relative to the Downloads directory to contain the downloaded file, possibly containing subdirectories. Absolute paths, empty paths, and paths containing back-references ".." will cause an error. onDeterminingFilename allows suggesting a filename after the file's MIME type and a tentative filename have been determined.
headers
HeaderNameValuePair[] optional
Extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol. Each header is represented as a dictionary containing the keys name and either value or binaryValue, restricted to those allowed by XMLHttpRequest.
method
HttpMethod optional
The HTTP method to use if the URL uses the HTTP[S] protocol.
saveAs
boolean optional
Use a file-chooser to allow the user to select a filename regardless of whether filename is set or already exists.
url
string
The URL to download.

DownloadQuery

Properties

bytesReceived
number optional
Number of bytes received so far from the host, without considering file compression.
danger
DangerType optional
Indication of whether this download is thought to be safe or known to be suspicious.
endTime
string optional
The time when the download ended in ISO 8601 format.
endedAfter
string optional
Limits results to DownloadItem that ended after the given ms since the epoch.
endedBefore
string optional
Limits results to DownloadItem that ended before the given ms since the epoch.
error
InterruptReason optional
Why a download was interrupted.
exists
boolean optional
Whether the downloaded file exists;
fileSize
number optional
Number of bytes in the whole file post-decompression, or -1 if unknown.
filename
string optional
Absolute local path.
filenameRegex
string optional
Limits results to DownloadItem whose filename matches the given regular expression.
finalUrl
string optional
Chrome 54+
The absolute URL that this download is being made from, after all redirects.
finalUrlRegex
string optional
Chrome 54+
Limits results to DownloadItem whose finalUrl matches the given regular expression.
id
number optional
The id of the DownloadItem to query.
limit
number optional
The maximum number of matching DownloadItem returned. Defaults to 1000. Set to 0 in order to return all matching DownloadItem. See search for how to page through results.
mime
string optional
The file's MIME type.
orderBy
string[] optional
Set elements of this array to DownloadItem properties in order to sort search results. For example, setting orderBy=['startTime'] sorts the DownloadItem by their start time in ascending order. To specify descending order, prefix with a hyphen: '-startTime'.
paused
boolean optional
True if the download has stopped reading data from the host, but kept the connection open.
query
string[] optional
This array of search terms limits results to DownloadItem whose filename or url or finalUrl contain all of the search terms that do not begin with a dash '-' and none of the search terms that do begin with a dash.
startTime
string optional
The time when the download began in ISO 8601 format.
startedAfter
string optional
Limits results to DownloadItem that started after the given ms since the epoch.
startedBefore
string optional
Limits results to DownloadItem that started before the given ms since the epoch.
state
State optional
Indicates whether the download is progressing, interrupted, or complete.
totalBytes
number optional
Number of bytes in the whole file, without considering file compression, or -1 if unknown.
totalBytesGreater
number optional
Limits results to DownloadItem whose totalBytes is greater than the given integer.
totalBytesLess
number optional
Limits results to DownloadItem whose totalBytes is less than the given integer.
url
string optional
The absolute URL that this download initiated from, before any redirects.
urlRegex
string optional
Limits results to DownloadItem whose url matches the given regular expression.

FilenameConflictAction

uniquify

To avoid duplication, the filename is changed to include a counter before the filename extension.

overwrite

The existing file will be overwritten with the new file.

prompt

The user will be prompted with a file chooser dialog.

Type

"uniquify"

"overwrite"

, or

"prompt"

FilenameSuggestion

Properties

conflictAction
FilenameConflictAction optional
The action to take if filename already exists.
filename
string
The DownloadItem's new target DownloadItem.filename, as a path relative to the user's default Downloads directory, possibly containing subdirectories. Absolute paths, empty paths, and paths containing back-references ".." will be ignored. filename is ignored if there are any onDeterminingFilename listeners registered by any extensions.

GetFileIconOptions

Properties

size
16 | 32 optional
The size of the returned icon. The icon will be square with dimensions size * size pixels. The default and largest size for the icon is 32x32 pixels. The only supported sizes are 16 and 32. It is an error to specify any other size.

HeaderNameValuePair

Properties

name
string
Name of the HTTP header.
value
string
Value of the HTTP header.

HttpMethod

Type

"GET"

, or

"POST"

InterruptReason

Type

"FILE_FAILED"

"FILE_ACCESS_DENIED"

"FILE_NO_SPACE"

"FILE_NAME_TOO_LONG"

"FILE_TOO_LARGE"

"FILE_VIRUS_INFECTED"

"FILE_TRANSIENT_ERROR"

"FILE_BLOCKED"

"FILE_SECURITY_CHECK_FAILED"

"FILE_TOO_SHORT"

"FILE_HASH_MISMATCH"

"FILE_SAME_AS_SOURCE"

"NETWORK_FAILED"

"NETWORK_TIMEOUT"

"NETWORK_DISCONNECTED"

"NETWORK_SERVER_DOWN"

"NETWORK_INVALID_REQUEST"

"SERVER_FAILED"

"SERVER_NO_RANGE"

"SERVER_BAD_CONTENT"

"SERVER_UNAUTHORIZED"

"SERVER_CERT_PROBLEM"

"SERVER_FORBIDDEN"

"SERVER_UNREACHABLE"

"SERVER_CONTENT_LENGTH_MISMATCH"

"SERVER_CROSS_ORIGIN_REDIRECT"

"USER_CANCELED"

"USER_SHUTDOWN"

, or

"CRASH"

State

in_progress

The download is currently receiving data from the server.

interrupted

An error broke the connection with the file host.

complete

The download completed successfully.

Type

"in_progress"

"interrupted"

, or

"complete"

StringDelta

Properties

current
string optional
previous
string optional

UiOptions

Chrome 105+

Properties

enabled
boolean
Enable or disable the download UI.

Methods

acceptDanger


          
          
            chrome.downloads.acceptDanger(

        downloadId:
  number,

        callback?:
  function,

      
    )

Promise

Prompt the user to accept a dangerous download. Can only be called from a visible context (tab, window, or page/browser action popup). Does not automatically accept dangerous downloads. If the download is accepted, then an onChanged event will fire, otherwise nothing will happen. When all the data is fetched into a temporary file and either the download is not dangerous or the danger has been accepted, then the temporary file is renamed to the target filename, the state changes to 'complete', and onChanged fires.

Parameters

downloadId
number
The identifier for the DownloadItem.
callback
function optional
The callback parameter looks like: () => void

Returns

Promise<void>
Chrome 96+
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

cancel


          
          
            chrome.downloads.cancel(

        downloadId:
  number,

        callback?:
  function,

      
    )

Promise

Cancel a download. When callback is run, the download is cancelled, completed, interrupted or doesn't exist anymore.

Parameters

downloadId
number
The id of the download to cancel.
callback
function optional
The callback parameter looks like: () => void

Returns

Promise<void>
Chrome 96+
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

download


          
          
            chrome.downloads.download(

        options:
  DownloadOptions,

        callback?:
  function,

      
    )

Promise

Download a URL. If the URL uses the HTTP[S] protocol, then the request will include all cookies currently set for its hostname. If both filename and saveAs are specified, then the Save As dialog will be displayed, pre-populated with the specified filename. If the download started successfully, callback will be called with the new DownloadItem's downloadId. If there was an error starting the download, then callback will be called with downloadId=undefined and runtime.lastError will contain a descriptive string. The error strings are not guaranteed to remain backwards compatible between releases. Extensions must not parse it.

Parameters

options
DownloadOptions
What to download and how.
callback
function optional
The callback parameter looks like: (downloadId: number) => void
- downloadId
  number

Returns

Promise<number>
Chrome 96+
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

erase


          
          
            chrome.downloads.erase(

        query:
  DownloadQuery,

        callback?:
  function,

      
    )

Promise

Erase matching DownloadItem from history without deleting the downloaded file. An onErased event will fire for each DownloadItem that matches query, then callback will be called.

Parameters

query
DownloadQuery
callback
function optional
The callback parameter looks like: (erasedIds: number[]) => void
- erasedIds
  number[]

Returns

Promise<number[]>
Chrome 96+
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

getFileIcon


          
          
            chrome.downloads.getFileIcon(

        downloadId:
  number,

        options?:
  GetFileIconOptions,

        callback?:
  function,

      
    )

Promise

Retrieve an icon for the specified download. For new downloads, file icons are available after the onCreated event has been received. The image returned by this function while a download is in progress may be different from the image returned after the download is complete. Icon retrieval is done by querying the underlying operating system or toolkit depending on the platform. The icon that is returned will therefore depend on a number of factors including state of the download, platform, registered file types and visual theme. If a file icon cannot be determined, runtime.lastError will contain an error message.

Parameters

downloadId
number
The identifier for the download.
options
GetFileIconOptions optional
callback
function optional
The callback parameter looks like: (iconURL?: string) => void
- iconURL
  string optional

Returns

Promise<string | undefined>
Chrome 96+
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

open


          
          
            chrome.downloads.open(

        downloadId:
  number,

      
    )

Open the downloaded file now if the DownloadItem is complete; otherwise returns an error through runtime.lastError. Requires the "downloads.open" permission in addition to the "downloads" permission. An onChanged event will fire when the item is opened for the first time.

Parameters

downloadId
number
The identifier for the downloaded file.

pause


          
          
            chrome.downloads.pause(

        downloadId:
  number,

        callback?:
  function,

      
    )

Promise

Pause the download. If the request was successful the download is in a paused state. Otherwise runtime.lastError contains an error message. The request will fail if the download is not active.

Parameters

downloadId
number
The id of the download to pause.
callback
function optional
The callback parameter looks like: () => void

Returns

Promise<void>
Chrome 96+
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

removeFile


          
          
            chrome.downloads.removeFile(

        downloadId:
  number,

        callback?:
  function,

      
    )

Promise

Remove the downloaded file if it exists and the DownloadItem is complete; otherwise return an error through runtime.lastError.

Parameters

downloadId
number
callback
function optional
The callback parameter looks like: () => void

Returns

Promise<void>
Chrome 96+
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

resume


          
          
            chrome.downloads.resume(

        downloadId:
  number,

        callback?:
  function,

      
    )

Promise

Resume a paused download. If the request was successful the download is in progress and unpaused. Otherwise runtime.lastError contains an error message. The request will fail if the download is not active.

Parameters

downloadId
number
The id of the download to resume.
callback
function optional
The callback parameter looks like: () => void

Returns

Promise<void>
Chrome 96+
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

search


          
          
            chrome.downloads.search(

        query:
  DownloadQuery,

        callback?:
  function,

      
    )

Promise

Find DownloadItem. Set query to the empty object to get all DownloadItem. To get a specific DownloadItem, set only the id field. To page through a large number of items, set orderBy: ['-startTime'], set limit to the number of items per page, and set startedAfter to the startTime of the last item from the last page.

Parameters

query
DownloadQuery
callback
function optional
The callback parameter looks like: (results: DownloadItem[]) => void
- results
  DownloadItem[]

Returns

Promise<DownloadItem[]>
Chrome 96+
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

setShelfEnabled


          
          
            chrome.downloads.setShelfEnabled(

        enabled:
  boolean,

      
    )

Enable or disable the gray shelf at the bottom of every window associated with the current browser profile. The shelf will be disabled as long as at least one extension has disabled it. Enabling the shelf while at least one other extension has disabled it will return an error through runtime.lastError. Requires the "downloads.shelf" permission in addition to the "downloads" permission.

Parameters

enabled
boolean

setUiOptions


          
          
            chrome.downloads.setUiOptions(

        options:
  UiOptions,

        callback?:
  function,

      
    )

Promise Chrome 105+

Change the download UI of every window associated with the current browser profile. As long as at least one extension has set UiOptions.enabled to false, the download UI will be hidden. Setting UiOptions.enabled to true while at least one other extension has disabled it will return an error through runtime.lastError. Requires the "downloads.ui" permission in addition to the "downloads" permission.

Parameters

options
UiOptions
Encapsulate a change to the download UI.
callback
function optional
The callback parameter looks like: () => void

Returns

Promise<void>
Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

show


          
          
            chrome.downloads.show(

        downloadId:
  number,

      
    )

Show the downloaded file in its folder in a file manager.

Parameters

downloadId
number
The identifier for the downloaded file.

showDefaultFolder


          
          
            chrome.downloads.showDefaultFolder()

Show the default Downloads folder in a file manager.

Events

onChanged


          
          
            chrome.downloads.onChanged.addListener(

        callback:
  function,

      
    )

When any of a DownloadItem's properties except bytesReceived and estimatedEndTime changes, this event fires with the downloadId and an object containing the properties that changed.

Parameters

callback
function
The callback parameter looks like: (downloadDelta: DownloadDelta) => void
- downloadDelta
  DownloadDelta

onCreated


          
          
            chrome.downloads.onCreated.addListener(

        callback:
  function,

      
    )

This event fires with the DownloadItem object when a download begins.

Parameters

callback
function
The callback parameter looks like: (downloadItem: DownloadItem) => void
- downloadItem
  DownloadItem

onDeterminingFilename


          
          
            chrome.downloads.onDeterminingFilename.addListener(

        callback:
  function,

      
    )

During the filename determination process, extensions will be given the opportunity to override the target DownloadItem.filename. Each extension may not register more than one listener for this event. Each listener must call suggest exactly once, either synchronously or asynchronously. If the listener calls suggest asynchronously, then it must return true. If the listener neither calls suggest synchronously nor returns true, then suggest will be called automatically. The DownloadItem will not complete until all listeners have called suggest. Listeners may call suggest without any arguments in order to allow the download to use downloadItem.filename for its filename, or pass a suggestion object to suggest in order to override the target filename. If more than one extension overrides the filename, then the last extension installed whose listener passes a suggestion object to suggest wins. In order to avoid confusion regarding which extension will win, users should not install extensions that may conflict. If the download is initiated by download and the target filename is known before the MIME type and tentative filename have been determined, pass filename to download instead.

Parameters

callback
function
The callback parameter looks like: (downloadItem: DownloadItem, suggest: function) => void
- downloadItem
  DownloadItem
- suggest
  function
  The suggest parameter looks like: (suggestion?: FilenameSuggestion) => void
  - suggestion
    FilenameSuggestion optional

onErased


          
          
            chrome.downloads.onErased.addListener(

        callback:
  function,

      
    )

Fires with the downloadId when a download is erased from history.

Parameters

callback
function
The callback parameter looks like: (downloadId: number) => void
- downloadId
  number

chrome.downloads

# Manifest

# Examples

Summary

Types

BooleanDelta

Properties

DangerType

Type

DoubleDelta

Properties

DownloadDelta

Properties

DownloadItem

Properties

DownloadOptions

Properties

DownloadQuery

Properties

FilenameConflictAction

Type

FilenameSuggestion

Properties

GetFileIconOptions

Properties

HeaderNameValuePair

Properties

HttpMethod

Type

InterruptReason

Type

State

Type

StringDelta

Properties

UiOptions

Properties

Methods

acceptDanger

Parameters

Returns

cancel

Parameters

Returns

download

Parameters

Returns

erase

Parameters

Returns

getFileIcon

Parameters

Returns

open

Parameters

pause

Parameters

Returns

removeFile

Parameters

Returns

resume

Parameters

Returns

search

Parameters

Returns

setShelfEnabled

Parameters

setUiOptions

Parameters

Returns

show

Parameters

showDefaultFolder

Events

onChanged

Parameters

onCreated

Parameters

Manifest

Examples