gdown Files

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:

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

Change it to:

python 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:

```python # 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)