Gdown

https://github.com/wkentaro/gdown
Admin
Gdown is a Python library designed to simplify the process of downloading files from various...
Tokens:47,192
Snippets:252
Trust Score:9.7
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Clone and set up gdown with just and uv

Source: https://github.com/wkentaro/gdown/blob/main/README.md

Run these commands from a Bash shell (e.g., Git for Windows on Windows) to clone the repositoryvolt and install dependencies with 'just setup', run tests with 'just test', and run linters with 'just lint'.

```bash
git clone https://github.com/wkentaro/gdown.git
cd gdown
just setup   # install dependencies
just test    # run tests
just lint    # run linters

```

--------------------------------

### Basic usage of gdown.download

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/download.md

Shows how to download a file from a Google Drive URL, by file ID, and from a non-Google URL. The first example prints the returned path.

```python
import gdown

# From a Google Drive URL
url = "https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"
path = gdown.download(url=url, output="fcn8s_from_caffe.npz")
print(path)  # 'fcn8s_from_caffe.npz'

# By file ID
gdown.download(id="0B9P1L--7Wd2vNm9zMTJWOGxobkU", output="output.npz")

# Non-Google URLs work too, as a curl/wget replacement
gdown.download(url="https://httpbin.org/ip", output="ip.json")
```

--------------------------------

### Resolve filenames without downloading (beta)

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/cli.md

Shows how to get file metadata as JSON using the --json flag, then pipe to jq to extract the file path. This is a beta feature.

```bash
gdown https://drive.google.com/uc?id=0B9P1L--7Wd2vU3VUVlFnbTgtS2c --json | jq -r '.[0].path'
```

--------------------------------

### Usage example: get_url_from_gdrive_confirmation() with sample HTML

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/download.md

Shows how to call get_url_from_gdrive_confirmation() with a minimal HTML snippet. The function extracts the download URL from the anchor tag and prints the unescaped URL.

```python
from gdown.download import get_url_from_gdrive_confirmation

html = """<html>
<a href="/uc?export=download&amp;id=abc&amp;confirm=t&amp;uuid=123">
</html>"""
url = get_url_from_gdrive_confirmation(html)
print(url)  # https://docs.google.com/uc?export=download&id=abc&confirm=t&uuid=123
```

--------------------------------

### gdown.download_folder

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/download_folder.md

Documentation for the gdown.download_folder function, including parameters, usage examples, and error handling.

```APIDOC
## gdown.download_folder

### Description
Downloads all files from a Google Drive folder to the local filesystem. Returns a list of local paths of the downloaded files.

### Method
Function call

### Endpoint
`gdown.download_folder(url=None, id=None, output=None, quiet=False, resume=False, retries=0, skip_download=False)`

### Parameters
- **url** (str) - Optional - URL of the Google Drive folder.
- **id** (str) - Optional - ID of the Google Drive folder.
- **output** (str) - Optional - Directory to save the files. Defaults to the current directory.
- **quiet** (bool) - Optional - Suppress output. Defaults to `False`.
- **resume** (bool) - Optional - Resume interrupted downloads. Defaults to `False`.
- **retries** (int) - Optional - Number of retries for failed downloads. Defaults to `0`.
- **skip_download** (bool) - Optional - If `True`, only list the files without downloading. Defaults to `False`.

### Request Example
```python
import gdown

url = "https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl"
paths = gdown.download_folder(url=url)
print(paths)  # list of local paths

# By ID
gdown.download_folder(id="15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl")

# Into an explicit directory, quiet, with retries
gdown.download_folder(
    url=url,
    output="/tmp/folder",
    quiet=True,
    resume=True,
    retries=3,
)
```

### Response
Returns a list of local paths (strings) of the downloaded files. If `skip_download=True`, returns a list of `GoogleDriveFileToDownload` objects.

### Error Handling
Raises `gdown.exceptions.DownloadError` if the folder cannot be retrieved or if any file fails to download.
```

--------------------------------

### extractall()

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/extractall.md

Documentation for the `gdown.extractall` function, including parameters, return value, exceptions, and usage examples.

```APIDOC
## `extractall(path: str, to: str | None = None) -> list[str]`

### Description
Safely extracts a supported archive (ZIP, TAR, TAR.GZ/TGZ, TAR.BZ2/TBZ) to a target directory, with protections against zip-slip and link/special-file attacks. Returns the absolute paths of the extracted members.

### Parameters
- `path` (str) - Required - Path of the archive file to be extracted.
- `to` (str | None) - Optional - Directory to which the archive is extracted. If `None`, the parent directory of the archive file is used.

### Returns
`list[str]` - Absolute member paths inside `to`, one per archive member (normalized via `osp.normpath` on `<member>` and joined with `to`).

### Raises
- `ValueError` - Unsupported archive format: "Could not extract '{path}' as no appropriate extractor is found". Also raised if an archive member would extract outside the target directory ("Archive member '{member}' would extract outside target directory: {to}"), and for tar on Python < 3.12 for symlink/hardlink members ("is a link, which is not allowed for security reasons") and char/block/fifo special files ("is a special file, which is not allowed for security reasons").

### Behavior Notes
- Format dispatch is by filename suffix only: `.zip` → `zipfile.ZipFile`; `.tar` → `tarfile` mode `"r"`; `.tar.gz`/`.tgz` → `"r:gz"`; `.tar.bz2`/`.tbz` → `"r:bz2"`.
- Security: every ZIP member name is normalized and checked with `_is_within_directory` (realpath prefix check) before `extractall` runs. For tar on Python >= 3.12, extraction uses the built-in `filter="data"`; on older Pythons, members are manually screened against links and special files before extraction.

### Example
```python
import gdown

paths = gdown.extractall("model.zip")
print(paths)  # ['./model/weights.bin', './model/config.json', ...]

# Extract into an explicit directory
paths = gdown.extractall("model.tgz", to="/tmp/models")
```
```

--------------------------------

### is_google_drive_url() usage examples

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/parse_url.md

Shows how to use is_google_drive_url with different URLs, returning True for Google Drive/Docs URLs and False for others.

```python
from gdown.parse_url import is_google_drive_url

is_google_drive_url("https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ")  # True
is_google_drive_url("https://docs.google.com/spreadsheets/d/1AbC/edit")                  # True
is_google_drive_url("https://httpbin.org/ip")                                            # False
```

--------------------------------

### Error handling for gdown.extractall

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/extractall.md

Error handling examples for gdown.extractall. Shows the ValueError messages for unsupported archive formats and for zip-slip attempts where a member would extract outside the target directory.

```python
import gdown

# Unsupported archive type
try:
    gdown.extractall("data.csv")
except ValueError as e:
    print(e)  # "Could not extract 'data.csv' as no appropriate extractor is found"

# Archive member escaping the target directory (zip-slip attempt)
try:
    gdown.extractall("malicious.zip", to="/tmp/safe")
except ValueError as e:
    print(e)  # "Archive member '../evil' would extract outside target directory: /tmp/safe"
```

--------------------------------

### parse_url() usage examples

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/parse_url.md

Shows how to use parse_url with different URL formats: query parameter, share link, Google Docs export link, and non-Google URL. Each call returns a tuple of file ID (or None) and a boolean.

```python
from gdown.parse_url import parse_url

# Query-parameter form
parse_url("https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ")
# -> ('1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ', True)

# Share-link form
parse_url("https://drive.google.com/file/d/0B9P1L--7Wd2vU3VUVlFnbTgtS2c/view?usp=sharing")
# -> ('0B9P1L--7Wd2vU3VUVlFnbTgtS2c', False)

# Google Docs export link
parse_url("https://docs.google.com/document/d/1AbC/edit")
# -> ('1AbC', False)

# Non-Google URL
parse_url("https://httpbin.org/ip")
# -> (None, False)
```

--------------------------------

### CLI: resume, speed limit, proxy, and timeout options

Source: https://github.com/wkentaro/gdown/blob/main/README.md

CLI options for resuming a partial download (--continue), limiting speed (--speed), routing via a proxy (--proxy), and giving up after a timeout (--timeout) with no server data.

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ --continue
```

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ --speed 10MB
```

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ --proxy http://proxy:8080
```

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ --timeout 30
```

--------------------------------

### gdown.cached_download()

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/cached_download.md

Documentation for the gdown.cached_download function, including parameters, return value, exceptions, and usage examples.

```APIDOC
## `cached_download()`

### Description
Downloads a file from a URL (Google Drive URLs are supported) and caches it locally. If the file already exists at the target path and no hash is provided, it returns the existing file immediately. When a hash is provided, it verifies the file's hash and re-downloads if necessary.

### Method
Function call

### Endpoint
`gdown.cached_download`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Function Parameters
- **`url`** (`str | None`) - Optional - URL to download. Google Drive URLs are supported.
- **`path`** (`str | None`) - Optional - Output filename. Default is derived from the URL: `url.replace("/", "-SLASH-").replace(":", "-COLON-").replace("=", "-EQUAL-").replace("?", "-QUESTION-")` joined under `cache_root`.
- **`quiet`** (`bool`) - Optional - Suppress terminal output. Default: `False`.
- **`postprocess`** (`Callable[[str], object] | None`) - Optional - Function called with the final filename after the download completes (e.g., `gdown.extractall`).
- **`hash`** (`str | None`) - Optional - Expected hash of the file in `{algorithm}:{hash_value}` format, e.g. `sha256:abcdef...`. Supported algorithms: anything in `hashlib.algorithms_guaranteed` (the docstring names md5, sha1, sha256, sha512).
- **`**kwargs`** (`Unpack[_DownloadKwargs]`) - Optional - Keyword arguments passed through to `download()`, including `cancel`. An already-set cancellation event takes precedence over a cache hit. Cancellation removes staging files and leaves the final path untouched.

### Request Example
```python
import gdown

url = "https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"

# Cache by hash; subsequent calls with the same hash are served from disk.
path = gdown.cached_download(
    url=url,
    path="output.npz",
    hash="md5:fa837a88f0c40c513d975104edf3da17",
    postprocess=gdown.extractall,  # auto-unpack archives after download
)
print(path)

# Derived cache path under ~/.cache/gdown
auto_path = gdown.cached_download(url=url, hash="md5:fa837a88f0c40c513d975104edf3da17")
```

### Response
#### Success Response
- **Returns** (`str`) - The final cached file path (`path`, or the derived default under `cache_root`).

#### Response Example
```python
"/path/to/cached/file"
```

### Error Handling
- **`ValueError`** - Raised when `path` is `None` and `url` is `None` ("url must be specified when path is not specified"); malformed `hash` (no `:` - "Hash must be in the format of {algorithm}:{hash_value}"); unsupported algorithm - "Unsupported hash algorithm: {algorithm}. Supported algorithms: {hashlib.algorithms_guaranteed}".
- **`AssertionError`** - Raised on hash mismatch ("File hash doesn't match:\nactual: {actual}\nexpected: {expected}"). Note: on a cache hit with a failed hash check, the message is printed to stderr and the file is re-downloaded instead of raising.
- **`DownloadError`** - Raised on underlying `download()` failure.
- **`DownloadCancelled`** - Raised when cancellation is requested before final-file publication. Not retried.

### Behavior notes
- **Cache check first**: if `path` exists and no `hash` is given, the file is returned immediately ("File exists: {path}"). If `path` exists and `hash` is given, `_assert_filehash` verifies the existing file; on mismatch the message is printed to stderr and the file is re-downloaded.
- **Staging + lock**: the body is downloaded to `<cache_root>/<tmp>/dl` with `hasher=` fed every byte (`download()`'s `log_messages` are customized to "Cached downloading..." / "To: {path}"). After download, the running hash is compared with `hash`; only then, under `filelock.FileLock(cache_root + "/_dl_lock")`, is the file `shutil.move`'d to the final `path`.
- **Existence is checked first** (`osp.exists(path)`), so interrupted runs keep the last fully verified file.
```

--------------------------------

### Signed-in downloads via browser cookies

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/cli.md

Shows how to use browser cookies for authenticated downloads with --cookies-from-browser, or disable cookies with --no-cookies and set a custom user agent with --user-agent.

```bash
gdown --cookies-from-browser firefox https://drive.google.com/uc?id=<file_id>
```

```bash
gdown --no-cookies https://drive.google.com/uc?id=<file_id> --user-agent "MyApp/1.0"
```

--------------------------------

### gdown.download with progress, hasher, resume, retries, timeout, cancel, and skip_download

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/download.md

Shows a single download call with a progress callback, MD5 hasher, resume, retries, and timeout. Also demonstrates cooperative cancellation via a threading.Event and probe mode with skip_download=True returning a GoogleDriveFileToDownload object.

```python
import hashlib
import threading
import gdown

# Progress tracking with hash verification
hasher = hashlib.md5()

def on_progress(bytes_so_far: int, bytes_total: int | None) -> None:
    if bytes_total is not None:
        print(f"\r{bytes_so_far / bytes_total * 100:.1f}%", end="")

path = gdown.download(
    url=url,
    output="output.npz",
    quiet=True,
    progress=on_progress,
    hasher=hasher,
    resume=True,
    retries=3,
    timeout=(5, 30),
)
assert hasher.hexdigest() == "fa837a88f0c40c513d975104edf3da17"

# Cooperative cancellation: set cancel.set() from another thread to stop
cancel = threading.Event()
try:
    gdown.download(url=url, output="output.npz", cancel=cancel)
except gdown.DownloadCancelled:
    print("cancelled; partial file kept for --continue")

# Probe mode: resolve the Google Drive filename without downloading
from gdown.download import GoogleDriveFileToDownload

result = gdown.download(url=url, skip_download=True)
assert isinstance(result, GoogleDriveFileToDownload)
print(result.id, result.path, result.local_path)
```

--------------------------------

### CLI: download folders, list contents with --json, filter by path

Source: https://github.com/wkentaro/gdown/blob/main/README.md

Download an entire folder, list its contents as JSON, or filter and download matching files. Folder URLs are detected automatically, but a bare folder ID requires --folder.

```bash
gdown https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl -O /tmp/folder
```

```bash
gdown https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl --json
```

```bash
gdown https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl --json \
  | jq -r '.[] | select(.path | test("shad")) | .url' \
  | xargs -n1 gdown
```

--------------------------------

### Python: download files and folders with gdown.download, cached_download, download_folder

Source: https://github.com/wkentaro/gdown/blob/main/README.md

Python API for downloading files by URL, file ID, share link, with cached_download for hash verification and extraction, custom progress callback, and download_folder for folders by URL or ID. The progress callback prints a percentage when total size is known.

```python
import gdown

# Download a file
url = "https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"
gdown.download(url=url, output="fcn8s_from_caffe.npz")

# Download by file ID
gdown.download(id="0B9P1L--7Wd2vNm9zMTJWOGxobkU", output="output.npz")

# Download from a share link
url = "https://drive.google.com/file/d/0B9P1L--7Wd2vNm9zMTJWOGxobkU/view?usp=sharing"
gdown.download(url=url, output="output.npz")

# Download with hash verification and caching
gdown.cached_download(
    url=url,
    path="output.npz",
    hash="md5:fa837a88f0c40c513d975104edf3da17",
    postprocess=gdown.extractall,
)

# Track download progress
def on_progress(bytes_so_far: int, bytes_total: int | None) -> None:
    if bytes_total is not None:
        print(f"\r{bytes_so_far / bytes_total * 100:.1f}%", end="")

gdown.download(url=url, output="output.npz", quiet=True, progress=on_progress)

# Download a folder
url = "https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl"
gdown.download_folder(url=url)

# Download a folder by ID
gdown.download_folder(id="15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl")
```

--------------------------------

### Download a folder by URL or ID

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/cli.md

Shows how to download a Google Drive folder using either the folder URL (auto-detected) or the --folder flag with a folder ID. The -O option sets the output directory.

```bash
gdown https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl -O /tmp/folder
```

```bash
gdown --folder 15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl
```

--------------------------------

### Define DownloadCancelled exception

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/exceptions.md

Standalone exception (not a DownloadError subclass) raised by the cancellation machinery in gdown/_cancellation.py whenever the caller-supplied cancel: threading.Event is set. Triggered before work starts, between response-header and body reads, during retry backoff, and during speed-limit waits. The CLI never sets a cancel event, so this is only reachable through the Python API.

```python
class DownloadCancelled(Exception):
    pass
```

--------------------------------

### CLI: download files by URL, ID, or share link; --json to resolve filename

Source: https://github.com/wkentaro/gdown/blob/main/README.md

Basic forms of downloading a single file via the gdown CLI: by URL, by file ID, from a share link, saving to a specific path, and resolving the filename without downloading (--json). The --json option is in beta and may change; use --quiet to silence the beta warning. The JSON output is an array of {url, path} entries.

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ
```

```bash
gdown 1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ
```

```bash
gdown 'https://drive.google.com/file/d/0B9P1L--7Wd2vU3VUVlFnbTgtS2c/view?usp=sharing'
```

```bash
gdown https://drive.google.com/uc?id=0B9P1L--7Wd2vU3VUVlFnbTgtS2c -O /tmp/spam.txt
```

```bash
gdown https://drive.google.com/uc?id=0B9P1L--7Wd2vU3VUVlFnbTgtS2c --json
```

--------------------------------

### download()

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/configuration.md

Downloads a file from Google Drive or a plain HTTP/HTTPS URL with extensive configuration options.

```APIDOC
## download(url=None, output=None, quiet=False, proxy=None, speed=None, use_cookies=True, verify=True, id=None, resume=False, format=None, user_agent=None, log_messages=None, progress=None, skip_download=False, cookies_file=None, hasher=None, timeout=None, retries=0, cancel=None)

### Description
Downloads a file from Google Drive or a plain HTTP/HTTPS URL. Supports various options for output, proxy, speed, cookies, verification, resume, format, and more.

### Parameters
- **url** (str | None) - Required (one of url/id) - Google Drive URL or plain HTTP/HTTPS URL.
- **id** (str | None) - Required (one of url/id) - Google Drive file ID.
- **output** (str | BinaryIO | None) - Optional - Filename/directory (basename appended if directory) or a writable stream.
- **quiet** (bool) - Optional - Suppress terminal output.
- **proxy** (str | None) - Optional - Proxy used for both http and https.
- **speed** (float | None) - Optional - Max bytes/second.
- **use_cookies** (bool) - Optional - Read/save the cookies file.
- **verify** (bool | str) - Optional - TLS verify or CA-bundle path.
- **resume** (bool) - Optional - Resume partials and skip completed files.
- **format** (str | None) - Optional - Docs/Sheets/Slides export format (defaults docx/xlsx/pptx).
- **user_agent** (str | None) - Optional - HTTP User-Agent (default Chrome 39 UA).
- **log_messages** (dict[str, str] | None) - Optional - Overrides for the "start" and "output" log lines.
- **progress** (Callable[[int, int | None], None] | None) - Optional - Per-chunk callback.
- **skip_download** (bool) - Optional - Probe mode; returns GoogleDriveFileToDownload.
- **cookies_file** (str | None) - Optional - Netscape cookies path; ignored unless use_cookies.
- **hasher** (hashlib._Hash | None) - Optional - Hashing stream fed every byte.
- **timeout** (float | tuple[float, float] | None) - Optional - Inter-byte wait, or (connect, read) pair; None = forever.
- **retries** (int) - Optional - Transient-failure retries per file; needs a filesystem destination; ignored under skip_download.
- **cancel** (threading.Event | None) - Optional - Cooperative cancellation event.

### Response
Returns the downloaded file path or a GoogleDriveFileToDownload object when skip_download is True.
```

--------------------------------

### Resume, retries, speed limit, proxy, timeout

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/cli.md

Shows gdown options for resuming interrupted downloads (--continue), setting retry count (--retries), limiting download speed (--speed), using a proxy (--proxy), and setting a timeout (--timeout).

```bash
gdown --continue --retries 3 https://drive.google.com/uc?id=<file_id>
```

```bash
gdown --speed 10MB --proxy http://proxy:8080 --timeout 30 <url>
```

--------------------------------

### Default User-Agent string

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/download.md

The exact User-Agent string used by download() when user_agent is None. Note that download_folder() uses a different Chrome/98 agent.

```text
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36
```

--------------------------------

### Use GoogleDriveFileToDownload with gdown.download

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/types.md

Shows how to use the GoogleDriveFileToDownload type with gdown.download when skip_download=True. It demonstrates type checking, field access, and tuple unpacking. The result is a namedtuple with id, path, and local_path fields.

```python
from gdown.download import GoogleDriveFileToDownload

result = gdown.download(url=url, skip_download=True)
assert isinstance(result, GoogleDriveFileToDownload)
print(result.id)          # e.g. '1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ'
print(result.path)        # e.g. 'fcn8s_from_caffe.npz'
print(result.local_path)  # same as path for single files
id_, path, local = result  # tuple unpacking works
```

--------------------------------

### download_folder()

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/configuration.md

Downloads a folder from Google Drive with options for output, proxy, speed, cookies, verification, resume, and more.

```APIDOC
## download_folder(url=None, id=None, output=None, quiet=False, proxy=None, speed=None, use_cookies=True, verify=True, user_agent=None, skip_download=False, resume=False, cookies_file=None, timeout=None, retries=0)

### Description
Downloads a folder from Google Drive. Supports a subset of download() options, with a different default user agent for folder listing.

### Parameters
- **url** (str | None) - Required (one of url/id) - Google Drive folder URL.
- **id** (str | None) - Required (one of url/id) - Google Drive folder ID.
- **output** (str | None) - Optional - Output folder; default = cwd + /<folder name>/ (when it ends with the path separator, <folder name>/ is appended).
- **quiet** (bool) - Optional - Suppress terminal output.
- **proxy** (str | None) - Optional - Proxy used for both http and https.
- **speed** (float | None) - Optional - Max bytes/second.
- **use_cookies** (bool) - Optional - Read/save the cookies file.
- **verify** (bool | str) - Optional - TLS verify or CA-bundle path.
- **user_agent** (str | None) - Optional - Default Chrome 98 folder-listing UA (different from file download).
- **skip_download** (bool) - Optional - Return list[GoogleDriveFileToDownload] without downloading.
- **resume** (bool) - Optional - Resume partials and skip completed files.
- **cookies_file** (str | None) - Optional - Netscape cookies path; ignored unless use_cookies.
- **timeout** (float | tuple[float, float] | None) - Optional - Inter-byte wait, or (connect, read) pair; None = forever.
- **retries** (int) - Optional - Transient-failure retries per file; needs a filesystem destination; ignored under skip_download.

### Response
Returns the output folder path or a list of GoogleDriveFileToDownload objects when skip_download is True.
```

--------------------------------

### gdown [url_or_id] [options]

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/cli.md

The main command-line entry point for gdown. It downloads a file or folder from Google Drive using a URL or ID, with various options to control output, proxy, speed, cookies, and more.

```APIDOC
## gdown [url_or_id] [options]

### Description
The `gdown` command downloads a file or folder from Google Drive. It accepts a URL or file/folder ID as the positional argument and supports various options to customize the download behavior.

### Method
CLI

### Endpoint
`gdown` (command-line tool)

### Parameters
#### Positional Arguments
- **url_or_id** (string) - Required - URL or file/folder ID to download from. If it matches `^https?://.*`, it is treated as a URL; otherwise it is treated as a plain ID.

#### Options
- **-V, --version** (flag) - Optional - Display version and package location, then exit.
- **-O, --output** (string) - Optional - Output file name/path; end with the OS path separator to create a new directory. `-O -` writes the body to stdout. Cannot be combined with `--json`.
- **-q, --quiet** (flag) - Optional - Suppress logging except errors.
- **--proxy** (string) - Optional - `<protocol://host:port>` — download using the specified proxy.
- **--speed** (size) - Optional - Download speed limit per second, e.g. `'10MB'` → 10 MB/s. Parsed by `_parse_file_size`: a number followed by `B`, `KB`, `MB`, or `GB` (powers of 1024). Invalid values raise an error.
- **--cookies** (FILE) - Optional - Netscape cookies file to read cookies from and save them to. Must be a non-empty path when passed. Default: `~/.cache/gdown/cookies.txt`.
- **--cookies-from-browser** (BROWSER) - Optional - Copy Google cookies from this browser into the cookies file. Choices: `brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale`. On failure, prints the reason and exits 1.
- **--no-cookies** (flag) - Optional - Don't read or save cookies. Cannot be combined with `--cookies` or `--cookies-from-browser`.
- **--no-check-certificate** (flag) - Optional - Don't check the server's TLS certificate (passes `verify=False`).
- **-c, --continue** (flag) - Optional - Resume getting partially-downloaded files while skipping fully downloaded ones.
- **--retries** (int) - Optional - Retry transient failures up to N times per file, resuming the current transfer. Default: `0`.
- **--folder** (flag) - Optional - Download a folder by ID (folder URLs are detected automatically). Passing it with a folder URL prints a deprecation warning.
- **--json** (flag) - Optional - (beta) List file or folder contents as a JSON array on stdout instead of downloading. Each entry is an object with `'url'` and `'path'`. Cannot be combined with `-O`/`--output`.
- **--format** (string) - Optional - Format of Google Docs, Spreadsheets and Slides. Defaults: Docs → `docx`, Spreadsheet → `xlsx`, Slides → `pptx`.
- **--user-agent** (string) - Optional - User-Agent to use for downloading files.
- **--timeout** (float) - Optional - Give up when the server sends nothing for this many seconds. Must be positive. Default: `None` (wait forever).

### Exit Codes
- **0** - Success.
- **1** - On `DownloadError`, `requests.exceptions.ProxyError`, timeout, or any other error (specific messages are printed to stderr).

### Example
```bash
gdown https://drive.google.com/uc?id=FILE_ID -O output.zip
```
```

--------------------------------

### Download by URL / ID / share link

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/cli.md

Shows basic gdown usage to download a file by its full Google Drive URL, file ID, or share link. The -O option specifies an output path.

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ
```

```bash
gdown 1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ
```

```bash
gdown -O /tmp/spam.txt https://drive.google.com/uc?id=0B9P1L--7Wd2vU3VUVlFnbTgtS2c
```

--------------------------------

### download()

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/download.md

Downloads a single file from Google Drive or any public HTTP/HTTPS URL. Accepts a Google Drive URL, a file ID, or a plain URL, and returns the local file path, a file-like object, or a GoogleDriveFileToDownload namedtuple when skip_download is True.

```APIDOC
## [FUNCTION] download()

### Description
Downloads one file from Google Drive or any public HTTP/HTTPS URL. Accepts a Google Drive URL (file ID, share link, docs/sheets/slides export), a plain file ID via `id=`, or any public HTTP(S) URL. Google Drive URLs are rewritten to `https://drive.google.com/uc?id=<file_id>` before requesting.

### Signature
```python
def download(
    url: str | None = None,
    output: str | BinaryIO | None = None,
    quiet: bool = False,
    proxy: str | None = None,
    speed: float | None = None,
    use_cookies: bool = True,
    verify: bool | str = True,
    id: str | None = None,
    resume: bool = False,
    format: str | None = None,
    user_agent: str | None = None,
    log_messages: dict[str, str] | None = None,
    progress: Callable[[int, int | None], None] | None = None,
    skip_download: bool = False,
    cookies_file: str | None = None,
    hasher: "hashlib._Hash | None" = None,
    timeout: float | tuple[float, float] | None = None,
    retries: int = 0,
    cancel: threading.Event | None = None,
) -> str | BinaryIO | GoogleDriveFileToDownload
```

### Parameters
- **url** (str | None) - Optional - The URL of the file to download. Can be a Google Drive URL or any public HTTP/HTTPS URL.
- **output** (str | BinaryIO | None) - Optional - The output file path or a file-like object to write to. If None, the file is saved to the current directory with the original filename.
- **quiet** (bool) - Optional - If True, suppress all output messages.
- **proxy** (str | None) - Optional - Proxy URL to use for the request.
- **speed** (float | None) - Optional - Maximum download speed in bytes per second.
- **use_cookies** (bool) - Optional - Whether to use cookies for authentication.
- **verify** (bool | str) - Optional - Whether to verify SSL certificates. Can be a boolean or a path to a CA bundle.
- **id** (str | None) - Optional - Google Drive file ID to download directly.
- **resume** (bool) - Optional - Whether to resume an interrupted download.
- **format** (str | None) - Optional - Export format for Google Docs/Sheets/Slides.
- **user_agent** (str | None) - Optional - User-Agent header to use.
- **log_messages** (dict[str, str] | None) - Optional - Custom log messages.
- **progress** (Callable[[int, int | None], None] | None) - Optional - Callback function for progress updates. Receives the number of bytes downloaded and the total size (or None if unknown).
- **skip_download** (bool) - Optional - If True, only probe the file and return a GoogleDriveFileToDownload namedtuple without downloading.
- **cookies_file** (str | None) - Optional - Path to a cookies file.
- **hasher** (hashlib._Hash | None) - Optional - Hash object to compute the file hash during download.
- **timeout** (float | tuple[float, float] | None) - Optional - Timeout for the request.
- **retries** (int) - Optional - Number of retries on failure.
- **cancel** (threading.Event | None) - Optional - Event to cancel the download.

### Returns
- **str** - The local file path of the downloaded file.
- **BinaryIO** - The file-like object if `output` is a file-like object.
- **GoogleDriveFileToDownload** - A namedtuple with fields `id`, `path`, and `local_path` when `skip_download` is True.

### Example
```python
import gdown

# Download a file from Google Drive by URL
url = "https://drive.google.com/uc?id=FILE_ID"
output = "file.txt"
gdown.download(url, output, quiet=False)

# Download by file ID
id = "FILE_ID"
gdown.download(id=id, output="file.txt")

# Skip download and get file info
info = gdown.download(url, skip_download=True)
print(info.id, info.path, info.local_path)
```
```

--------------------------------

### CLI: download Google Docs/Sheets/Slides with export format

Source: https://github.com/wkentaro/gdown/blob/main/README.md

Download Google Docs, Sheets, or Slides files. Default export formats: Docs → docx, Sheets → xlsx, Slides → pptx. Use --format to change, e.g., export a Slides file as PDF.

```bash
gdown "https://docs.google.com/presentation/d/15umvZKlsJ3094HNg5S4vJsIhxcFlyTeK/edit?usp=sharing"
```

```bash
gdown "https://docs.google.com/presentation/d/15umvZKlsJ3094HNg5S4vJsIhxcFlyTeK/edit" --format pdf
```

--------------------------------

### CLI: certificate, cookie, and User-Agent options

Source: https://github.com/wkentaro/gdown/blob/main/README.md

CLI options for skipping TLS verification, using browser cookies, specifying a cookie file, disabling cookies, or setting a custom User-Agent. The default cookie file for --cookies is ~/.cache/gdown/cookies.txt.

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ --no-check-certificate
```

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ --cookies-from-browser firefox
```

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ --cookies ./cookies.txt
```

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ --no-cookies
```

```bash
gdown https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ --user-agent "MyApp/1.0"
```

--------------------------------

### List GitHub issues with JSON and jq

Source: https://github.com/wkentaro/gdown/blob/main/docs/agents/issue-tracker.md

Use this command to list open issues with selected fields (number, title, body, labels, comments) formatted as JSON. The --jq expression extracts the desired fields.

```bash
gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'
```

--------------------------------

### Default User-Agent

Source: https://github.com/wkentaro/gdown/blob/main/_autodocs/api-reference/download.md

Describes the default user-agent string used by download() when user_agent is None, and the additional Accept-Encoding header when resume or retries is active.

```APIDOC
## Default User-Agent

### Description
When `user_agent` is `None`, `download()` uses a default user-agent string. When `resume` or `retries` is active, the session additionally sets `Accept-Encoding: identity` so byte offsets refer to the bytes written on disk.

### Default User-Agent String
```
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.95 Safari/537.36
```

### Notes
- `download_folder` uses a different Chrome/98 agent; see [download_folder.md](download_folder.md).
- When `resume` or `retries` is active, the session additionally sets `Accept-Encoding: identity`.
```
Tokens:
Raw