0
# gdown
1

2
A Python library for downloading files and folders from Google Drive that bypasses security notices and download restrictions. Provides both command-line and Python API interfaces with support for recursive folder downloads, format conversion for Google Workspace documents, and intelligent URL parsing.
3

4
## Package Information
5

6
- **Package Name**: gdown
7
- **Language**: Python
8
- **Installation**: `pip install gdown`
9
- **Requirements**: Python 3.8+
10

11
## Core Imports
12

13
```python
14
import gdown
15
```
16

17
Common usage patterns:
18

19
```python
20
from gdown import download, cached_download, download_folder, extractall
21
```
22

23
## Basic Usage
24

25
```python
26
import gdown
27

28
# Download a single file from Google Drive
29
url = "https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"
30
output = "my_file.npz"
31
gdown.download(url, output)
32

33
# Download using file ID directly
34
file_id = "1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"
35
gdown.download(id=file_id, output=output)
36

37
# Download with fuzzy URL matching (copy-paste any Google Drive URL)
38
messy_url = "https://drive.google.com/file/d/1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ/view?usp=sharing"
39
gdown.download(messy_url, output, fuzzy=True)
40

41
# Download entire folder
42
folder_url = "https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl"
43
gdown.download_folder(folder_url, output="./my_folder")
44

45
# Cached download with integrity verification
46
gdown.cached_download(url, output, hash="sha256:abc123...")
47
```
48

49
## Architecture
50

51
gdown's design centers around three main functional areas:
52

53
- **File Downloads**: Core downloading functionality with Google Drive API handling, cookie management, and format conversion
54
- **Folder Operations**: Recursive folder parsing and batch downloading with directory structure preservation
55
- **Utilities**: Archive extraction, caching, and URL parsing helpers
56

57
The library automatically handles Google Drive's security redirects, authentication via cookies, and format conversion for Google Workspace documents (Docs/Sheets/Slides).
58

59
## Capabilities
60

61
### File Download Operations
62

63
Core file downloading with Google Drive URL parsing, security bypass, format conversion for Google Workspace documents, and progress tracking.
64

65
```python { .api }
66
def download(
67
    url=None, output=None, quiet=False, proxy=None, speed=None,
68
    use_cookies=True, verify=True, id=None, fuzzy=False, resume=False,
69
    format=None, user_agent=None, log_messages=None
70
) -> str: ...
71
```
72

73
[File Downloads](./file-downloads.md)
74

75
### Cached Downloads and Integrity
76

77
Download files with caching, hash verification, and optional post-processing for automation workflows.
78

79
```python { .api }
80
def cached_download(
81
    url=None, path=None, md5=None, quiet=False, postprocess=None,
82
    hash=None, **kwargs
83
) -> str: ...
84
```
85

86
[Caching and Integrity](./caching-integrity.md)
87

88
### Folder Operations
89

90
Recursive downloading of Google Drive folders with directory structure preservation and batch file handling.
91

92
```python { .api }
93
def download_folder(
94
    url=None, id=None, output=None, quiet=False, proxy=None, speed=None,
95
    use_cookies=True, remaining_ok=False, verify=True, user_agent=None,
96
    skip_download=False, resume=False
97
) -> Union[List[str], List[GoogleDriveFileToDownload], None]: ...
98
```
99

100
[Folder Operations](./folder-operations.md)
101

102
### Archive Utilities
103

104
Extract compressed archives with support for multiple formats.
105

106
```python { .api }
107
def extractall(path, to=None) -> List[str]: ...
108
```
109

110
[Archive Utilities](./archive-utilities.md)
111

112
## Package Metadata
113

114
```python { .api }
115
__version__: str
116
```
117

118
The current version of the gdown package, dynamically loaded from package metadata.
119

120
```python
121
import gdown
122
print(f"gdown version: {gdown.__version__}")
123
```
124

125
## Exception Types
126

127
```python { .api }
128
class FileURLRetrievalError(Exception):
129
    """Raised when unable to retrieve file URL from Google Drive."""
130
    pass
131

132
class FolderContentsMaximumLimitError(Exception):
133
    """Raised when folder contains more than 50 files."""
134
    pass
135
```
136

137
## Command Line Interface
138

139
gdown provides a command-line interface with the same functionality:
140

141
```bash
142
# Basic file download
143
gdown "https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"
144

145
# Download folder
146
gdown "https://drive.google.com/drive/folders/15uNXeRBIhVvZJIhL4yTw4IsStMhUaaxl" --folder
147

148
# Fuzzy URL matching
149
gdown --fuzzy "https://drive.google.com/file/d/1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ/view?usp=sharing"
150

151
# Resume interrupted download
152
gdown --continue "URL" -O output.zip
153

154
# Speed limiting and proxy
155
gdown --speed 1MB --proxy http://proxy:8080 "URL"
156
```