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.

Contributors

• @achadwick
• @frosit
• @amorehead
• @moulins
• @abouelkhair5
• @o-laurent

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

Contributors

• @pmeier
• @o-laurent

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

Contributors

• @pavse
• @hungpham3112

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

Contributors

• @7x11x13

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.

Contributors

• @katzdm
• @alirezaAsadi2018
• @rmcpantoja

🚀 Features

• Raise and handle exceptions
  • PR: #260

🐛 Fixes

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

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