gdown

Added

• Add a secretstorage installation extra for importing Chromium cookies from GNOME Keyring with pip install 'gdown[secretstorage]' or uvx --from 'gdown[secretstorage]' gdown. (#505)
• download(), download_folder(), and cached_download() accept a requests-style timeout, exposed on the command line as --timeout SECONDS, so a stalled server no longer blocks forever. (#510)
• Add opt-in --retries N and Python retries=N for automatic recovery of interrupted file and folder downloads, with bounded backoff and validated byte-range resume; --continue still controls reuse of earlier downloads. (#517)

Changed

• cached_download() verifies hash while streaming instead of reading the finished file back from disk. (#512)
• The command line reports a hit --timeout as a timeout instead of asking to file an issue. (#513)

Fixed

• Propagate progress callback exceptions unchanged instead of misreporting chunked-encoding errors as incomplete downloads. (#519)

Added

• Add --cookies-from-browser BROWSER to download as your signed-in Google account using cookies read straight from a local browser, and --cookies FILE to use a cookies file other than ~/.cache/gdown/cookies.txt. The cookies file is now written owner-only and keeps session cookies. (#494)

Changed

• Continue downloading the remaining files in a folder after individual downloads fail, then report all failures together. (#495)
• Automatically detect Google Drive folder URLs, making --folder necessary only for ambiguous bare IDs. (#496)

Fixed

• Close download sessions and streamed responses on early exits, failures, and response replacement, including single-file Listing and resumed downloads. (#499)
• Remove cached-download staging directories after success or interruption, and create the cache on demand instead of during import. (#500)
• Honor an explicitly supplied user agent for file downloads within folders while retaining the existing default user agents. (#501)
• Fix folder --json export paths and preserve export extensions for dotted Google-native filenames. (#503)
• Preserve the saved cookies file when browser cookie extraction reports an error instead of replacing working session cookies with invalid decrypted values. (#504)

Fixed

• Fixed downloads leaking HTTP sessions, progress bars, or output files when an exception interrupted a file or folder download. (#478)
• Reject incomplete response bodies instead of saving them as completed downloads. (#481)
• Normalized archive member paths returned by extractall, so ZIP and tar results use native path separators consistently. (#487)

This release adds a new --json flag for inspecting Google Drive file and folder contents without downloading them.

Highlights

• New --json flag lists the file or folder contents as a JSON array on stdout instead of downloading, so you can resolve filenames and IDs before fetching anything. It is in beta and its output format may change in a future release.

Features

• Add a --json flag that prints file or folder contents as a JSON array of {"url", "path"} entries instead of downloading. Paths use POSIX separators on all platforms, and the flag cannot be combined with -O/--output. (#460, #463)

  # Resolve a single file's name without downloading it
  filename=$(gdown "$url" --json | jq -r '.[0].path')
  
  # List every file in a folder
  gdown https://drive.google.com/drive/folders/FOLDER_ID --folder --json

• Add a skip_download parameter to download() that resolves the target filename and ID without fetching the file, returning a GoogleDriveFileToDownload. (#463)

• --json now prints a one-time beta warning to stderr, which --quiet suppresses. (#465)

Other

• Bump urllib3 from 2.6.3 to 2.7.0. (#457)
• Bump idna from 3.11 to 3.15. (#459)
• Configure agent skills for the repository (AGENTS.md, CLAUDE.md, docs/agents/). (#462)

A lot has changed since v5.2.1 back in January. 33 pull requests (109 commits) went into this release, touching nearly every part of the codebase.

Highlights

• gdown --folder / download_folder() now supports folders with more than 50 files
• download() raises DownloadError on failure instead of returning None
• New progress parameter in download()
• Path traversal vulnerability fixed in extractall() (GHSA-76hw-p97h-883f)
• All deprecated APIs from v5 have been (finally) removed
• Python 3.10+ required (3.8 and 3.9 dropped)

Most users should be able to upgrade without issues. The one change that will likely need code updates is the switch from returning None to raising DownloadError on failure.

Breaking changes

• download() and download_folder() now raise DownloadError instead of returning None (#451)

  Previously, download() and download_folder() returned None when a download failed. Now, they raise DownloadError (or its subclass FileURLRetrievalError).

  If your code looks like this:

  output = gdown.download(url, output="file.txt")
  if output is None:
      print("Download failed")

  Change it to:

  try:
      output = gdown.download(url, output="file.txt")
  except gdown.DownloadError as e:
      print(f"Download failed: {e}")

• fuzzy parameter and --fuzzy CLI flag removed (#455)

  Previously, you needed fuzzy=True (or --fuzzy) to download from Google Drive share links like https://drive.google.com/file/d/FILE_ID/view. gdown now always extracts the file ID from any Google Drive URL format. Just pass the URL directly.

• --remaining-ok flag and FolderContentsMaximumLimitError removed (#453)

  Folder downloads used to be limited to 50 files due to a Google Drive API constraint, and --remaining-ok let you proceed with a partial download. gdown now uses the embeddedfolderview endpoint, which has no file count limit. The flag and exception class are no longer needed.

• md5 parameter removed from cached_download() (#450)

  The md5 parameter was deprecated in v5. Use the hash parameter instead:

  # Before
  gdown.cached_download(url, md5="abc123")
  
  # After
  gdown.cached_download(url, hash="md5:abc123")

• --id CLI flag, md5sum(), and assert_md5sum() removed (#448, #449)

  These were deprecated in v5. Use gdown.parse_url() for URL parsing and hashlib for checksum verification.

• Python 3.8 and 3.9 are no longer supported (#423)

  gdown now requires Python 3.10 or later. Python 3.10 through 3.14 are tested in CI.

Security fixes

• Arbitrary file write via path traversal in extractall() (GHSA-76hw-p97h-883f)

  gdown.extractall() now validates that archive members stay within the target directory, preventing zip or tar archives from writing files outside the extraction path via ../ traversal, absolute paths, or symlinks. On Python 3.12+, extraction uses the data filter. (#445, #446, #447)

Features

• New progress parameter in download() for hooking into download progress (#427)
• Folder downloads now support more than 50 files via the embeddedfolderview endpoint (#453)

Bug fixes

• Detect Google Docs/Sheets/Slides via URL patterns instead of page title, fixing downloads on non-English Google accounts (#438)
• Sanitize path separators in filenames on all platforms (#437)
• Handle corrupted cookies file instead of crashing (#441)
• Fix output directory detection and filename handling on Windows (#440)
• Append correct extension for Google exports in folder downloads (#443)
• Return None instead of False from parse_url() for non-Google-Drive URLs (#434)
• Remove redundant resume check in download_folder() (#444)

Enhancements

• Type annotations on all public API functions (#430)
• py.typed marker for PEP 561 support (#436)
• Build toolchain now uses uv, ruff, ty, and hatchling with VCS versioning (#423, #424, #425)
• CI tests on Python 3.10 through 3.14 across Ubuntu, macOS, and Windows (#454)

Security

• Fix path traversal vulnerability in extractall() that allowed zip/tar archives with ../ entries to write files outside the target directory (GHSA-76hw-p97h-883f)
• Reject symlinks, hardlinks, and special files in tar archives
• Use Python 3.12+ filter="data" for safe tar extraction when available
• Sanitize filenames from HTTP responses and URLs to prevent path traversal via /, , .., and null bytes
• Sanitize root folder name in download_folder() before building directory paths

Fixes

• cached_download: Verify file hash before moving to final location instead of after (#417)
  • Previously, the hash was verified after moving to the final path, which could leave corrupted files in place if hash verification failed
• download: Fix speed limit throttling logic to use independent byte counter instead of pbar.n (#407)
  • The speed limiter now correctly tracks downloaded bytes independently from the progress bar
  • Also fixes unnecessary sleep when resuming downloads with speed limit (since pbar.n includes start_size from resumed downloads)

Chores

• Fix missing space in --output help text (#398)
• Fix concatenated string literal in extractall.py error message

🚀 Features

• Feature: preserve GDrive's last modified time when downloading #351 (Thanks @moulins)
• Feature: allow folders to be continued more usefully #288 (Thanks @achadwick)

✨ Enhancement

• Show resume progress bar from the middle #361

🐛 Fixes

• Use importlib.metadata to get the version number from the installed package #319
• BUG: Download folder with "skip_download=True" creates an output folder #321 (Thanks @o-laurent)

💬 Other

• Fix typos in README.md #323 (Thanks @amorehead)
• Run GitHub Actions on macOS, Ubuntu, and Windows #324
• Support Windows and macOS in tests #359
• Typo in arg help text #343 (Thanks @frosit)
• Trivial: Update the documentation for the output param #347 (Thanks @abouelkhair5)

---

• To connect, check my Twitter.
• To support, check Sponsoring Page.

🚀 Features

• Enable python -m gdown <URL> by renaming cli.py to __main__.py #306
• Replace md5 with hash in gdown.cached_download to support various hash algorithm #311
• Make log messages in gdown.download() customizable #312
• Add skip_download option to gdown.download_folder to return the list of files without download #317 (Thanks @o-laurent)

✨ Enhancement

• Add extra pattern to extract url from download-form returned by Google Drive for a large file #308 (Thanks @pmeier)
• Add FAQ link to error messages #318

💬 Other

• Move tests from ci.yml to test___main__.py #307

---

• For my daily development update, check my Twitter/X.
• If you'd like to support this project, check my sponsoring page.

🐛 Fixes

• Skip process only for gdrive files by breaking early #302, Thanks @hungpham3112
• Retry with canonicalized url if original url is not gdrive url #304, Thanks @pavse

---

• For my daily development update, check my Twitter/X.
• If you'd like to support this project, check my sponsoring page.

🚀 Features

• Use MozillaCookieJar instead of json to save cookies #300, Thanks @7x11x13

✨ Enhancement

• Print log message to stderr instead of stdout #297
• Simplify the message printed by assert_md5sum function #298

💬 Other

• Drop Python 2 and migrate to pyproject.toml #296
• Use line length of 88 instead of 79 #299

---

• For my daily development update, check my Twitter/X.
• If you'd like to support this project, check my sponsoring page.

NOTE: Gdown was down due to the Google Drive's change on User-Agent. Now it should be back to normal.

🐛 Fixes

• Fix User-Agent to download and add --user-agent option
  • PR: #295
  • Thanks @rmcpantoja @katzdm @alirezaAsadi2018 and many others who reported this issue. (Sorry I missed the notification for a while.)

---

• For my daily development update, check my Twitter/X.
• If you'd like to support this project, check my sponsoring page.

🚀 Features

• Raise and handle exceptions
  • PR: #260

🐛 Fixes

• Fix typo: uriginal -> original
  • PR: #264

<details> <summary>Uncategorized</summary>

</details>

If you find this project useful, please consider sponsoring its development.

🚀 Features

• Support Google Docs, Spreadsheets, and Slides with export format
  • PR: #255

% gdown https://docs.google.com/document/d/1TFYNzuZJTgNGzGmjraZ58ZVOh9_YoKeBnU-opWgXQL4/edit#heading=h.9rak0iw3abvl --fuzzy --format pdf
Downloading...
From (uriginal): https://drive.google.com/uc?id=1TFYNzuZJTgNGzGmjraZ58ZVOh9_YoKeBnU-opWgXQL4
From (redirected): https://docs.google.com/document/d/1TFYNzuZJTgNGzGmjraZ58ZVOh9_YoKeBnU-opWgXQL4/export?format=pdf
To: /Users/wkentaro/Documents/gdown/gdown.docx.pdf
26.0kB [00:00, 40.7MB/s]

% gdown https://docs.google.com/spreadsheets/d/1h6wQX7ATSJDOSWFEjHPmv_nukJzZD_zZ30Jvy6XNiTE/edit#gid=0 --fuzzy --format pdf
Downloading...
From (uriginal): https://drive.google.com/uc?id=1h6wQX7ATSJDOSWFEjHPmv_nukJzZD_zZ30Jvy6XNiTE
From (redirected): https://docs.google.com/spreadsheets/d/1h6wQX7ATSJDOSWFEjHPmv_nukJzZD_zZ30Jvy6XNiTE/export?format=pdf
To: /Users/wkentaro/Documents/gdown/gdown.xlsx.pdf
17.8kB [00:00, 24.2MB/s]

% gdown https://docs.google.com/presentation/d/13AhW1Z1GYGaiTpJ0Pr2TTXoQivb6jx-a/edit#slide=id.p1 --fuzzy --format pdf
Downloading...
From (uriginal): https://drive.google.com/uc?id=13AhW1Z1GYGaiTpJ0Pr2TTXoQivb6jx-a
From (redirected): https://docs.google.com/presentation/d/13AhW1Z1GYGaiTpJ0Pr2TTXoQivb6jx-a/export?format=pdf
To: /Users/wkentaro/Documents/gdown/gdown.pptx.pdf
12.3kB [00:00, 19.2MB/s]

• Support more url patterns in fuzzy search of file id
  • PR: #258

🐛 Fixes

• Fix hang with large files by removing re.search title for non-html responses
  • PR: #256

💬 Other

• Show original and redirected url in logging
  • PR: #257

If you find this project useful, please consider sponsoring its development.

:sparkles: Features

• Support proxy in download_folder
  • PR: https://github.com/wkentaro/gdown/pull/245

• Resolve the issues in download_folder due to the language/region (e.g., Russia, UK, etc).

What's Changed

• Fix unicode error in gdown.download_folder in https://github.com/wkentaro/gdown/pull/198

Full Changelog: https://github.com/wkentaro/gdown/compare/v4.5.0...v4.5.1

What's Changed

• Fix ci.yml for many files in directory by @wkentaro in https://github.com/wkentaro/gdown/pull/193
• Add .github/ISSUE_TEMPLATE by @wkentaro in https://github.com/wkentaro/gdown/pull/192
• Fix remaining_ok flag usage for recursive parsing by @wkentaro in https://github.com/wkentaro/gdown/pull/195
• Fix folder_name with endash (happens in the UK) by @wkentaro in https://github.com/wkentaro/gdown/pull/194
• Handle filename with slashes by @wkentaro in https://github.com/wkentaro/gdown/pull/196

Full Changelog: https://github.com/wkentaro/gdown/compare/v4.4.0...v4.5.0

• Allow users to specify a file ID without --id

• Fix the regression in v4.2.1 on Windows around tempfile.mktemp vs mkstemp. https://github.com/wkentaro/gdown/issues/153

Mitigate PermissionError after many accesses to a particular file.

Gdown v4.1 now supports --folder option! You can download files in a folder on Google Drive.

gdown --folder https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl
# gdown/gdown.pptx
# gdown/spam.txt

Gdown v4 now supports --fuzzy option! You can simply copy and paste the link from Get link on Google Drive.

Also, --continue option is added to resume downloading from a partially downloaded file.

Tips: run pip install -U gdown for upgrade.