chrome.downloads (original) (raw)

Skip to main content

chrome.downloads

Description

Use the chrome.downloads API to programmatically initiate, monitor, manipulate, and search for downloads.

Permissions

downloads

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/downloadsdirectory. For other examples and for help in viewing the source code, see Samples.

Types

BooleanDelta

Properties

DangerType

Enum

"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.

"allowlistedByPolicy"
Enterprise-related values.

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

"forceSaveToGdrive"
For use by the Secure Enterprise Browser extension. When required, Chrome will block the download to disc and download the file directly to Google Drive.

DoubleDelta

Properties

DownloadDelta

Properties

DownloadItem

Properties

DownloadOptions

Properties

DownloadQuery

Properties

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.

Enum

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

Properties

GetFileIconOptions

Properties

Properties

HttpMethod

Enum

InterruptReason

Enum

"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"

"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.

Enum

"in_progress"

"interrupted"

"complete"

StringDelta

Properties

UiOptions

Properties

Methods

acceptDanger()

chrome.downloads.acceptDanger(
  downloadId: number,
): 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

Returns

cancel()

chrome.downloads.cancel(
  downloadId: number,
): Promise

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

Parameters

Returns

download()

chrome.downloads.download(
  options: DownloadOptions,
): 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

Returns

erase()

chrome.downloads.erase(
  query: DownloadQuery,
): Promise<number[]>

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

Returns

getFileIcon()

chrome.downloads.getFileIcon(
  downloadId: number,
  options?: GetFileIconOptions,
): Promise<string | undefined>

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

Returns

open()

chrome.downloads.open(
  downloadId: number,
): Promise

Opens the downloaded file now if the DownloadItem is complete; otherwise returns an error through runtime.lastError. This method requires the "downloads.open" permission in addition to the "downloads" permission. An onChanged event fires when the item is opened for the first time. This method can only be called in response to a user gesture.

Parameters

Returns

pause()

chrome.downloads.pause(
  downloadId: number,
): 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

Returns

removeFile()

chrome.downloads.removeFile(
  downloadId: number,
): Promise

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

Parameters

Returns

resume()

chrome.downloads.resume(
  downloadId: number,
): 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

Returns

chrome.downloads.search(
  query: DownloadQuery,
): Promise<DownloadItem[]>

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

Returns

setShelfEnabled()

Deprecated since Chrome 117

chrome.downloads.setShelfEnabled(
  enabled: boolean,
): void

Use setUiOptions instead.

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

setUiOptions()

chrome.downloads.setUiOptions(
  options: UiOptions,
): Promise

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

Returns

show()

chrome.downloads.show(
  downloadId: number,
): void

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

Parameters

showDefaultFolder()

chrome.downloads.showDefaultFolder(): void

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

onCreated

chrome.downloads.onCreated.addListener(
  callback: function,
)

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

Parameters

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

onErased

chrome.downloads.onErased.addListener(
  callback: function,
)

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

Parameters

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-10 UTC.