or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

Files

docs

archive-utilities.mdcaching-integrity.mdfile-downloads.mdfolder-operations.mdindex.md

file-downloads.mddocs/

0
# File Download Operations
1


2
Core file downloading functionality with comprehensive Google Drive support, format conversion, and intelligent URL handling.
3


4
## Capabilities
5


6
### Primary Download Function
7


8
Downloads files from URLs with extensive Google Drive support, including security bypass, authentication, and format conversion.
9


10
```python { .api }
11
def download(
12
    url=None,
13
    output=None,
14
    quiet=False,
15
    proxy=None,
16
    speed=None,
17
    use_cookies=True,
18
    verify=True,
19
    id=None,
20
    fuzzy=False,
21
    resume=False,
22
    format=None,
23
    user_agent=None,
24
    log_messages=None
25
) -> str:
26
    """
27
    Download file from URL with Google Drive support.
28


29
    Parameters:
30
    - url (str): URL to download from. Google Drive URLs supported.
31
    - output (str): Output filename/directory. Defaults to basename of URL.
32
                   If ends with '/', treated as parent directory.
33
    - quiet (bool): Suppress terminal output. Default: False.
34
    - proxy (str): Proxy configuration in format 'protocol://host:port'.
35
    - speed (float): Download speed limit in bytes per second (e.g., 256*1024 for 256KB/s).
36
    - use_cookies (bool): Use cookies from ~/.cache/gdown/cookies.txt. Default: True.
37
    - verify (bool/str): TLS certificate verification. True/False or path to CA bundle. Default: True.
38
    - id (str): Google Drive file ID. Cannot be used with url parameter.
39
    - fuzzy (bool): Extract Google Drive file ID from any URL format. Default: False.
40
    - resume (bool): Resume interrupted downloads, skip completed files. Default: False.
41
    - format (str): Export format for Google Docs/Sheets/Slides.
42
                   Defaults: Docs='docx', Sheets='xlsx', Slides='pptx'.
43
    - user_agent (str): Custom user agent string.
44
    - log_messages (dict): Custom messages with keys 'start' and 'output'.
45


46
    Returns:
47
    str: Path to downloaded file.
48


49
    Raises:
50
    FileURLRetrievalError: When unable to retrieve download URL.
51
    ValueError: When both url and id are specified or neither.
52
    """
53
```
54


55
### Usage Examples
56


57
#### Basic File Download
58


59
```python
60
import gdown
61


62
# Download with URL
63
url = "https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"
64
output_path = gdown.download(url, "my_file.npz")
65
print(f"Downloaded to: {output_path}")
66
```
67


68
#### Download with File ID
69


70
```python
71
# Direct file ID usage
72
file_id = "1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"
73
output_path = gdown.download(id=file_id, output="my_file.npz")
74
```
75


76
#### Fuzzy URL Matching
77


78
```python
79
# Copy-paste any Google Drive URL format
80
messy_url = "https://drive.google.com/file/d/1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ/view?usp=sharing&resourcekey=0-WWs_XOSctfaY_0-sJBKRSQ"
81
gdown.download(messy_url, "output.npz", fuzzy=True)
82
```
83


84
#### Google Workspace Document Export
85


86
```python
87
# Download Google Doc as PDF
88
doc_url = "https://docs.google.com/document/d/DOCUMENT_ID/edit"
89
gdown.download(doc_url, "document.pdf", format="pdf")
90


91
# Download Google Sheet as CSV
92
sheet_url = "https://docs.google.com/spreadsheets/d/SHEET_ID/edit"
93
gdown.download(sheet_url, "data.csv", format="csv")
94


95
# Download Google Slides as PowerPoint
96
slides_url = "https://docs.google.com/presentation/d/PRESENTATION_ID/edit"
97
gdown.download(slides_url, "presentation.pptx", format="pptx")
98
```
99


100
#### Advanced Options
101


102
```python
103
# Resume interrupted download with speed limit
104
gdown.download(
105
    url="https://drive.google.com/uc?id=LARGE_FILE_ID",
106
    output="large_file.zip",
107
    resume=True,
108
    speed=1024*1024,  # 1MB/s limit
109
    proxy="http://proxy.company.com:8080"
110
)
111


112
# Download to stdout (for piping)
113
import sys
114
gdown.download(url, output=sys.stdout.buffer, quiet=True)
115
```
116


117
#### Custom Progress Messages
118


119
```python
120
# Custom logging messages
121
custom_messages = {
122
    "start": "πŸš€ Starting custom download...\n",
123
    "output": "πŸ“ Saving to: {}\n"
124
}
125


126
gdown.download(
127
    url="https://drive.google.com/uc?id=FILE_ID",
128
    output="file.zip",
129
    log_messages=custom_messages
130
)
131
```
132


133
## Error Handling
134


135
```python
136
from gdown.exceptions import FileURLRetrievalError
137


138
try:
139
    gdown.download("https://drive.google.com/uc?id=INVALID_ID", "output.zip")
140
except FileURLRetrievalError as e:
141
    print(f"Download failed: {e}")
142
    # Handle permission issues, network errors, etc.
143
```
144


145
## Supported URL Formats
146


147
The download function supports various Google Drive URL formats:
148


149
- **Direct download**: `https://drive.google.com/uc?id=FILE_ID`
150
- **File view**: `https://drive.google.com/file/d/FILE_ID/view?usp=sharing`
151
- **Document edit**: `https://docs.google.com/document/d/DOC_ID/edit`
152
- **Spreadsheet edit**: `https://docs.google.com/spreadsheets/d/SHEET_ID/edit`
153
- **Presentation edit**: `https://docs.google.com/presentation/d/PRESENTATION_ID/edit`
154
- **Non-Google URLs**: Any HTTP/HTTPS URL (functions as alternative to curl/wget)
155


156
## Configuration Files
157


158
### Cookie Management
159


160
Place cookies in `~/.cache/gdown/cookies.txt` (Mozilla/Netscape format) for authenticated downloads:
161


162
```
163
# Netscape HTTP Cookie File
164
.google.com	TRUE	/	FALSE	0	cookie_name	cookie_value
165
```
166


167
### User Agent Strings
168


169
Default user agents:
170
- **File downloads**: `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`
171
- **Custom**: Specify via `user_agent` parameter