DOCSEARCHbyAlgolia
Submit Docs

gdown Documentation

repository·main·Indexed 26 days ago

https://github.com/wkentaro/gdown

gdown is a tool and Python library for downloading public files and folders from Google Drive, designed to bypass confirmation pages for large files. It supports recursive folder downloads, exporting Google Docs, Sheets, and Slides to formats like docx, xlsx, and pdf, and provides advanced CLI options for resuming downloads, speed limits, and proxy configuration. The Python API includes functions like download(), download_folder(), and cached_download() with hash verification.

Tokens
5.1K
Snippets
9
Records
36
Agent score
89%

What's inside gdown

  2. Troubleshoot 'Permission Denied' or Throttled Downloads

    main

    Permission Denied

    Ensure the Google Drive file sharing is set to "Anyone with the link".

    Throttled Downloads

    If Google throttles the download, you can use your browser's cookies to authenticate:

    1. Export cookies.txt using a browser extension (e.g., Get cookies.txt LOCALLY).
    2. Move the file to ~/.cache/gdown/cookies.txt.
    3. Run the gdown command again.

    Connection Terminated

    Google Drive may terminate connections for large files after ~1 hour. Use the --continue flag to resume the download.

  3. Use gdown in Python

    main

    Import gdown to download files, folders, or use cached downloads with hash verification in your Python scripts.

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

  4. Use `download(skip_download=True)` to probe file metadata

    main

    When calling the download() function with skip_download=True, the function returns a GoogleDriveFileToDownload namedtuple instead of the usual file path or stream. This allows you to resolve file metadata without actually performing a download.

    For a single file, the GoogleDriveFileToDownload object contains:

    • id: The resolved Google Drive file ID.
    • path: The bare Drive filename.
    • local_path: The bare Drive filename (duplicates path when skip_download=True).

    Note that this return type is distinct from the normal str | BinaryIO returned during a standard download.

  5. Use GoogleDriveFileToDownload for probing downloads

    main
    When calling downloaders with skip_download=True, the library returns a probe result of type GoogleDriveFileToDownload. This is a tuple containing (id, path, local_path). This mode is designed to be type-distinct from normal download returns (which are str | BinaryIO), allowing Python callers and type-checkers to identify when a probe has occurred.

  6. Understand Listing entry structure

    main

    When using the --json output (Listing mode), each entry in the resulting JSON array contains:

    • url: The URL to be downloaded.
    • path: The location a file would be written to, relative to the download root. For a folder, this includes the directory structure. For a single file, this is the true Drive filename (including its real extension).

  7. Handle download errors and exceptions

    main

    When using the download() API, be prepared to catch the following exceptions:

    • ValueError: Raised if neither url nor id is provided, or if both are provided.
    • FileURLRetrievalError: Raised if the file URL cannot be retrieved from Google Drive (e.g., due to permissions) or if skip_download is used but no filename can be resolved.
    • DownloadError: Raised if the download fails (e.g., multiple .part files exist when attempting to resume).

  8. List Google Drive contents as JSON

    main

    Using the --json flag (currently in beta) allows you to list the contents of a file or folder as a JSON array on stdout instead of downloading the actual data. Each entry in the array is an object containing the url and the path.

    Note: This flag cannot be combined with the -O or --output flags. The output format is subject to change in future releases.

  9. Retrieve folder structure without downloading files

    main
    To inspect the contents and directory structure of a Google Drive folder without actually downloading the files, set the skip_download parameter to True. This returns a list of GoogleDriveFileToDownload objects which include the Google Drive id, the relative path, and the intended local_path.

  10. Resolve Google Drive filenames without downloading

    main

    To obtain the filename of a Google Drive file without performing the full download, use the download() function with the skip_download=True parameter. This is useful for metadata retrieval or preparing file paths in advance.

    Note: This requires a resolvable Google Drive file. If the filename cannot be determined, it will raise a FileURLRetrievalError.

  12. Download folders via CLI

    main

    Use the --folder flag to download an entire Google Drive folder recursively. You can also use --json with --folder to list folder contents as a JSON array of {url, path} entries for filtering.

    # Download an entire folder
gdown https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl -O /tmp/folder --folder

# List folder contents as a JSON array
gdown https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl --folder --json