Python实用工具：gdown库入门到精通——轻松下载Google Drive文件

作者：

在

一、gdown库核心概述

1.1 用途

gdown是一款轻量级的Python第三方库，其核心用途是便捷下载Google Drive上的文件与文件夹。日常工作学习中，当我们需要从Google Drive获取公开分享的数据集、代码包、文档等资源时，直接通过浏览器下载会受网络环境、文件大小等因素限制，而gdown可以通过简单的Python代码或命令行指令，突破这些限制，高效完成下载操作，广泛适用于数据分析、机器学习、项目开发等场景中资源获取的环节。

1.2 工作原理

gdown的工作原理是解析Google Drive的分享链接，提取出文件的真实下载地址，然后借助Python的网络请求库（如requests）向该地址发送请求，最终将文件内容保存到本地。对于公开分享的Google Drive文件，其分享链接中包含唯一的文件ID，gdown通过解析该ID构建对应的API请求链接，再处理Google Drive返回的响应数据，实现文件的流式下载；对于文件夹的下载，gdown会先获取文件夹内的文件列表，再逐个进行下载并保持原有的目录结构。

1.3 优缺点

优点

操作简单：仅需几行Python代码或一条命令行指令即可完成下载，对技术小白友好。
功能实用：支持大文件下载（最大可支持几十GB的文件），且能自动处理下载过程中的断点续传（部分版本支持）。
跨平台性：可在Windows、macOS、Linux等主流操作系统上运行，与Python生态无缝兼容。

缺点

依赖网络环境：对访问Google服务的网络环境要求较高，若网络无法访问Google Drive，则无法使用该库。
不支持私有文件（无权限）：仅能下载公开分享的文件或文件夹，对于未分享的私有资源，无法直接下载。
文件夹下载有限制：下载文件夹时，若文件夹层级过深或文件数量过多，可能会出现下载速度变慢或部分文件下载失败的情况。

1.4 License类型

二、gdown库安装步骤

在使用gdown库之前，我们需要先完成安装操作。gdown的安装方式非常简单，支持pip包管理器安装和源码安装两种方式，其中pip安装是最推荐的方式，适合绝大多数用户。

2.1 pip安装（推荐）

确保你的电脑上已经安装了Python环境和pip包管理器（Python 3.4及以上版本默认自带pip），然后打开命令行终端（Windows下是CMD或PowerShell，macOS和Linux下是Terminal），输入以下命令：

pip install gdown

等待命令执行完成，若终端输出类似“Successfully installed gdown-x.x.x”的提示，说明gdown库已经安装成功。

如果你的电脑上同时安装了Python 2和Python 3，为了避免版本冲突，建议使用pip3命令安装，命令如下：

pip3 install gdown

2.2 源码安装（进阶用户）

如果你需要使用gdown的最新开发版本，或者想要对源码进行修改，可以选择从GitHub上下载源码进行安装。具体步骤如下：

打开终端，克隆gdown的GitHub仓库到本地：

git clone https://github.com/wkentaro/gdown.git

cd gdown

执行源码安装命令：

pip install .

这种安装方式可以获取到最新的功能，但可能存在一些未经过充分测试的bug，适合有一定开发经验的进阶用户。

三、gdown库基础使用教程

gdown库提供了两种使用方式：命令行使用和Python脚本调用。命令行使用适合快速下载单个文件，而Python脚本调用则适合集成到自动化项目中，实现更复杂的下载逻辑。下面我们分别对这两种方式进行详细讲解，并配合实例代码进行演示。

3.1 命令行使用方式

gdown的命令行使用语法非常简洁，核心语法格式如下：

gdown [OPTIONS] URL_OR_ID

其中，URL_OR_ID表示Google Drive文件的分享链接或文件ID，OPTIONS是可选参数，用于设置下载路径、文件名等参数。

3.1.1 下载单个文件（基础用法）

首先，我们需要获取Google Drive文件的分享链接。具体操作步骤：打开Google Drive，找到需要下载的文件，右键点击该文件，选择“分享”，然后将分享权限设置为“知道链接的人可查看”，最后复制生成的分享链接。

例如，我们有一个Google Drive文件的分享链接为：https://drive.google.com/file/d/1234567890abcdefghijklmnopqrstuvwxyz/view?usp=sharing，其中1234567890abcdefghijklmnopqrstuvwxyz就是该文件的唯一ID。

示例1：通过分享链接下载文件
在命令行中输入以下命令，即可将文件下载到当前目录：

gdown https://drive.google.com/file/d/1234567890abcdefghijklmnopqrstuvwxyz/view?usp=sharing

示例2：通过文件ID下载文件
我们也可以直接使用文件ID进行下载，这种方式可以省略链接解析的步骤，下载速度更快。命令如下：

gdown 1234567890abcdefghijklmnopqrstuvwxyz

3.1.2 指定下载路径和文件名

默认情况下，gdown会将文件下载到当前工作目录，并使用文件在Google Drive上的原名称。如果我们需要将文件保存到指定路径，或者修改文件名，可以使用-O或--output参数。

示例：指定下载路径和文件名
将文件下载到./data目录下，并命名为dataset.csv，命令如下：

gdown https://drive.google.com/file/d/1234567890abcdefghijklmnopqrstuvwxyz/view?usp=sharing -O ./data/dataset.csv

执行该命令后，文件会被保存到data文件夹中（如果data文件夹不存在，需要提前创建）。

3.1.3 下载大文件

gdown对大文件下载提供了良好的支持，无需额外配置参数，直接使用基础下载命令即可。例如，下载一个大小为10GB的数据集文件，命令如下：

gdown https://drive.google.com/file/d/0987654321zyxwvutsrqponmlkjihgfedcba/view?usp=sharing

在下载大文件时，gdown会自动采用流式下载的方式，分块获取文件内容，避免因内存不足导致下载失败。

3.2 Python脚本调用方式

对于需要将文件下载功能集成到自动化脚本中的场景，Python脚本调用gdown库是更优的选择。gdown库提供了简洁的API接口，方便我们在代码中实现灵活的下载逻辑。

3.2.1 下载单个文件（基础API）

gdown库的核心函数是gdown.download()，该函数接收文件链接或文件ID作为参数，实现文件下载。

示例1：通过链接下载文件

import gdown

# 定义Google Drive文件分享链接
url = "https://drive.google.com/file/d/1234567890abcdefghijklmnopqrstuvwxyz/view?usp=sharing"
# 下载文件到当前目录
gdown.download(url, quiet=False)

代码说明：

import gdown：导入gdown库。
url变量：存储Google Drive文件的分享链接。
gdown.download()：执行下载操作，参数quiet=False表示在终端输出下载进度信息，若设置为True则不输出任何信息。

示例2：通过文件ID下载文件

import gdown

# 定义Google Drive文件ID
file_id = "1234567890abcdefghijklmnopqrstuvwxyz"
# 构建下载链接
url = f"https://drive.google.com/uc?id={file_id}"
# 下载文件并指定保存路径和文件名
output = "./downloads/sample_file.txt"
gdown.download(url, output, quiet=False)

代码说明：

file_id变量：存储文件的唯一ID，从分享链接中提取。
url变量：通过文件ID构建标准的下载链接，格式为https://drive.google.com/uc?id={file_id}。
output变量：指定文件的保存路径和文件名，若路径中的文件夹不存在，会抛出FileNotFoundError异常，需要提前创建文件夹。

3.2.2 下载文件夹

gdown库不仅支持下载单个文件，还支持下载Google Drive上的公开文件夹。下载文件夹需要使用gdown.download_folder()函数，该函数会自动获取文件夹内的所有文件，并保持原有的目录结构。

示例：下载Google Drive文件夹

import gdown

# 定义Google Drive文件夹分享链接
folder_url = "https://drive.google.com/drive/folders/1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q?usp=sharing"
# 指定下载后的保存路径
output_folder = "./dataset_folder"
# 下载文件夹
gdown.download_folder(folder_url, output=output_folder, quiet=False)

代码说明：

folder_url变量：存储Google Drive文件夹的分享链接，获取方式与文件分享链接类似，右键点击文件夹选择“分享”，复制链接即可。
output_folder变量：指定文件夹下载后的保存路径，gdown会自动创建该文件夹（如果不存在）。
gdown.download_folder()：执行文件夹下载操作，下载完成后，output_folder目录下会包含与Google Drive文件夹相同结构的文件和子文件夹。

3.2.3 断点续传功能

在下载大文件时，可能会因为网络中断等原因导致下载失败。gdown库支持断点续传功能，通过设置resume=True参数，可以从上次中断的位置继续下载文件。

示例：断点续传下载大文件

import gdown

# 定义大文件的分享链接
large_file_url = "https://drive.google.com/file/d/0987654321zyxwvutsrqponmlkjihgfedcba/view?usp=sharing"
# 指定保存路径
output_path = "./large_files/big_dataset.zip"
# 启用断点续传功能下载文件
gdown.download(large_file_url, output_path, resume=True, quiet=False)

代码说明：

resume=True：启用断点续传功能，当文件已经下载了一部分时，再次执行该代码会从断点处继续下载，无需重新下载整个文件。
该功能适用于大文件下载场景，可以有效节省下载时间和网络流量。

3.2.4 处理下载异常

在实际使用过程中，可能会遇到网络错误、文件不存在、权限不足等异常情况。我们可以通过try-except语句捕获这些异常，提高脚本的健壮性。

示例：异常处理的文件下载脚本

import gdown
from requests.exceptions import RequestException

def download_file_from_gdrive(url, output_path):
    """
    从Google Drive下载文件，包含异常处理逻辑
    :param url: Google Drive文件分享链接
    :param output_path: 文件保存路径
    """
    try:
        gdown.download(url, output_path, quiet=False)
        print(f"文件下载成功，保存路径：{output_path}")
    except RequestException as e:
        print(f"网络请求异常，下载失败：{e}")
    except FileNotFoundError:
        print(f"保存路径不存在，请检查路径是否正确：{output_path}")
    except Exception as e:
        print(f"未知错误，下载失败：{e}")

# 调用函数下载文件
if __name__ == "__main__":
    file_url = "https://drive.google.com/file/d/1234567890abcdefghijklmnopqrstuvwxyz/view?usp=sharing"
    save_path = "./downloads/data.csv"
    download_file_from_gdrive(file_url, save_path)

代码说明：

定义download_file_from_gdrive函数，封装文件下载和异常处理逻辑。
try代码块：执行文件下载操作，并打印成功提示信息。
except RequestException：捕获网络请求相关的异常，如网络中断、无法访问Google Drive等。
except FileNotFoundError：捕获保存路径不存在的异常。
except Exception：捕获其他未知异常，避免脚本崩溃。

四、gdown库进阶应用案例

4.1 批量下载Google Drive文件

在数据分析和机器学习项目中，我们经常需要批量下载多个文件。下面我们通过一个案例，实现从Google Drive批量下载多个公开文件的功能。

案例需求
有一个文件列表，包含3个Google Drive文件的ID和对应的文件名，需要将这些文件批量下载到./batch_downloads目录下。

实现代码

import gdown
import os

# 定义文件列表：每个元素是一个元组，包含(file_id, file_name)
file_list = [
    ("1234567890abcdefghijklmnopqrstuvwxyz", "file1.csv"),
    ("0987654321zyxwvutsrqponmlkjihgfedcba", "file2.jpg"),
    ("abcdefghijklmnopqrstuvwxyz1234567890", "file3.txt")
]

# 定义保存目录
save_dir = "./batch_downloads"
# 创建保存目录（如果不存在）
if not os.path.exists(save_dir):
    os.makedirs(save_dir)

# 批量下载文件
for file_id, file_name in file_list:
    # 构建下载链接
    url = f"https://drive.google.com/uc?id={file_id}"
    # 构建保存路径
    output_path = os.path.join(save_dir, file_name)
    try:
        print(f"正在下载文件：{file_name}")
        gdown.download(url, output_path, quiet=False)
        print(f"{file_name} 下载完成！")
    except Exception as e:
        print(f"{file_name} 下载失败：{e}")

代码说明：

file_list列表：存储需要下载的文件信息，每个元组包含文件ID和文件名。
os.makedirs(save_dir)：创建保存目录，os.path.exists(save_dir)用于判断目录是否存在，避免重复创建。
循环遍历file_list：逐个构建下载链接和保存路径，执行下载操作，并通过try-except捕获异常，确保单个文件下载失败不会影响其他文件的下载。

4.2 集成到机器学习数据集下载流程

在机器学习项目中，我们经常需要从Google Drive下载公开的数据集，然后进行数据预处理和模型训练。下面我们通过一个案例，将gdown库集成到机器学习数据集的下载和加载流程中。

案例需求
下载一个存储在Google Drive上的MNIST数据集压缩包（mnist.zip），解压后加载数据并进行简单的可视化。

实现代码

import gdown
import os
import zipfile
import numpy as np
import matplotlib.pyplot as plt

# 1. 定义数据集信息
file_id = "mnist_dataset_file_id_here"
url = f"https://drive.google.com/uc?id={file_id}"
zip_path = "./mnist_dataset/mnist.zip"
extract_path = "./mnist_dataset"

# 2. 创建数据集目录
if not os.path.exists(extract_path):
    os.makedirs(extract_path)

# 3. 下载数据集压缩包
if not os.path.exists(zip_path):
    print("正在下载MNIST数据集...")
    gdown.download(url, zip_path, quiet=False)
    print("数据集下载完成！")
else:
    print("数据集压缩包已存在，跳过下载步骤")

# 4. 解压数据集
if not os.path.exists(os.path.join(extract_path, "train")):
    print("正在解压数据集...")
    with zipfile.ZipFile(zip_path, "r") as zip_ref:
        zip_ref.extractall(extract_path)
    print("数据集解压完成！")
else:
    print("数据集已解压，跳过解压步骤")

# 5. 加载并可视化数据（假设解压后的数据格式为npy文件）
train_images = np.load(os.path.join(extract_path, "train", "train_images.npy"))
train_labels = np.load(os.path.join(extract_path, "train", "train_labels.npy"))

# 可视化前5张训练图像
plt.figure(figsize=(10, 5))
for i in range(5):
    plt.subplot(1, 5, i + 1)
    plt.imshow(train_images[i], cmap="gray")
    plt.title(f"Label: {train_labels[i]}")
    plt.axis("off")
plt.show()

代码说明：

步骤1-2：定义数据集的文件ID、下载链接、保存路径和解压路径，并创建数据集目录。
步骤3：判断压缩包是否已存在，若不存在则下载，避免重复下载浪费时间。
步骤4：判断数据集是否已解压，若未解压则使用zipfile库进行解压。
步骤5：加载解压后的数据集（假设为npy格式），并使用matplotlib库可视化前5张训练图像，帮助我们快速了解数据集的内容。

五、gdown库常见问题与解决方法

5.1 问题1：网络无法访问Google Drive，下载失败

现象：执行下载命令后，终端提示“ConnectionError: HTTPSConnectionPool”或“TimeoutError”。
解决方法：

检查网络环境是否能够正常访问Google服务，若无法访问，需要配置合适的网络代理。
在Python脚本中使用代理时，可以通过设置环境变量或修改requests库的配置来实现。例如：

import os
import gdown

# 设置代理环境变量
os.environ["HTTP_PROXY"] = "http://your_proxy_address:port"
os.environ["HTTPS_PROXY"] = "https://your_proxy_address:port"

# 执行下载操作
url = "https://drive.google.com/file/d/1234567890abcdefghijklmnopqrstuvwxyz/view?usp=sharing"
gdown.download(url, quiet=False)

5.2 问题2：文件权限不足，无法下载

现象：终端提示“Permission denied”或“File not found”，但文件链接是正确的。
解决方法：

检查Google Drive文件的分享权限，确保设置为“知道链接的人可查看”，而不是“仅限特定人员”。
确认文件链接是否正确，避免因复制错误导致的权限问题。

5.3 问题3：下载文件夹时部分文件缺失

现象：下载文件夹后，发现部分文件没有被下载，或者目录结构混乱。
解决方法：

检查Google Drive文件夹的分享权限，确保文件夹内的所有子文件和子文件夹都设置了公开分享权限。
减少单次下载的文件夹大小，若文件夹内文件数量过多，可以分批次下载。
更新gdown库到最新版本，旧版本可能存在文件夹下载的bug，执行命令pip install --upgrade gdown进行升级。

六、gdown库相关资源链接

Pypi地址：https://pypi.org/project/gdown
Github地址：https://github.com/wkentaro/gdown
官方文档地址：https://gdown.readthedocs.io/en/latest/

关注我，每天分享一个实用的Python自动化工具。

实用工具

Python实用工具：gdown库入门到精通——轻松下载Google Drive文件

一、gdown库核心概述

1.1 用途

1.2 工作原理

1.3 优缺点

1.4 License类型

二、gdown库安装步骤

2.1 pip安装（推荐）

2.2 源码安装（进阶用户）

三、gdown库基础使用教程

3.1 命令行使用方式

3.1.1 下载单个文件（基础用法）

3.1.2 指定下载路径和文件名

3.1.3 下载大文件

3.2 Python脚本调用方式

3.2.1 下载单个文件（基础API）

3.2.2 下载文件夹

3.2.3 断点续传功能

3.2.4 处理下载异常

四、gdown库进阶应用案例

4.1 批量下载Google Drive文件

4.2 集成到机器学习数据集下载流程

五、gdown库常见问题与解决方法

5.1 问题1：网络无法访问Google Drive，下载失败

5.2 问题2：文件权限不足，无法下载

5.3 问题3：下载文件夹时部分文件缺失

六、gdown库相关资源链接

更多文章

Python实用工具：pandas-datareader详解与实战指南

Python实用工具：gdown库入门到精通——轻松下载Google Drive文件

Python实用工具：python-magic 零基础入门教程——文件类型检测与分析实战

Python实用工具：xmltodict库快速上手与进阶实战