gdown2
Fast, crash-safe Google Drive downloads for files, folders, and Google Workspace documents.
gdown2 is a ground-up rewrite of gdown built on
asyncio and httpx. It keeps the zero-config convenience of public Drive links while
adding a resumable transfer engine, adaptive rate limiting, recursive folder crawling,
checksum verification, three user interfaces, and a clean Python API.
Why gdown2?
The original gdown is excellent for quick scripts. It becomes fragile when you pull
multi-gigabyte checkpoints, deeply nested folders with hundreds of files, or unstable
connections that drop mid-transfer.
gdown2 was designed for those cases:
| Capability | What it means in practice |
|---|---|
| Crash-safe resume | Data is streamed to <filename>.part; completed files are promoted with an atomic os.replace. Interrupted transfers resume from the last byte. |
| Google Drive API v3 + public web | Works out of the box on public links, then transparently switches to the official API when given an API key, OAuth token, or service account. |
| Recursive folder crawling | Full BFS traversal with pagination, shortcut-cycle protection, filename sanitization, and collision handling. |
| Two-level concurrency | Parallel file downloads (--workers) plus optional multi-Range chunking for large files (--chunks). |
| Adaptive throttling | Per-host token bucket (--rate) and AIMD backoff when Google returns 429 or transient 403 responses. |
| Integrity verification | Size and MD5 checks after every transfer, with automatic retry and clean restart on corruption. |
| Workspace exports | Google Docs, Sheets, Slides, and Drawings are exported on the fly to Office, PDF, CSV, and other formats. |
| Three interfaces | Rich CLI, interactive Textual TUI, and newline-delimited JSON for automation. |
Table of contents
- Installation
- Quick start
- CLI overview
- Python API
- Authentication
- Configuration
- Reliability model
- Exit codes
- Documentation
- Development
- Project layout
- Contributing
- License
Installation
Requires Python 3.11 or newer.
From source
git clone https://github.com/moustaph97/gdown2.git
cd gdown2
pip install .
Editable development install
git clone https://github.com/moustaph97/gdown2.git
cd gdown2
pip install -e ".[dev]"
Optional service-account support
Service-account authentication requires google-auth:
pip install "gdown2[service-account]"
Verify the installation:
gdown2 --version
gdown2 --help
Quick start
1. Inspect metadata
gdown2 info "https://drive.google.com/file/d/1A2B3C4D5E6F7G8H9I0J/view?usp=sharing"
2. Preview a remote folder without downloading
gdown2 tree "https://drive.google.com/drive/folders/1FolderId_9876543210"
Dataset/
├── train/
│ ├── part-000.parquet [412.5 MB]
│ └── part-001.parquet [410.1 MB]
├── Notes.docx [export]
└── README.md [4.2 KB]
1 folders, 4 files (1 docs), total known size: 822.6 MB
3. Download a file or an entire folder
# Single file or recursive folder download.
gdown2 get "https://drive.google.com/drive/folders/1FolderId_9876543210" -o ./downloads
# Six parallel files, four Range chunks per large file, five requests per second.
gdown2 get <url-or-id> -o ./downloads --workers 6 --chunks 4 --rate 5.0
# Export Google Docs/Sheets/Slides as PDF instead of their Office default.
gdown2 get "https://docs.google.com/document/d/1DocId_1234567890abc/edit" --export-format pdf
# Flatten the remote hierarchy into one directory.
gdown2 get <folder-url> -o ./downloads --flat
# Launch the interactive three-pane TUI.
gdown2 get <folder-url> -o ./downloads --tui
# Stream machine-readable NDJSON events for CI and automation.
gdown2 get <url-or-id> -o ./downloads --json
4. Resume an interrupted session
If a transfer is interrupted by Ctrl+C, a network drop, or a Drive quota limit:
gdown2 resume ./downloads
Resume state is stored in <output>/.gdown2.state.json; partial data lives in
<filename>.part files. Run the command from the same output directory to continue
exactly where the previous session stopped.
CLI overview
| Command | Purpose |
|---|---|
gdown2 info <url-or-id> |
Resolve and display metadata for a file, folder, or document. |
gdown2 tree <folder-url-or-id> |
Crawl a remote folder and print its hierarchy without downloading. |
gdown2 get <url-or-id> [-o DIR] |
Download a file, folder, or Google Workspace document. |
gdown2 resume [DIR] |
Resume incomplete transfers recorded in a directory. |
gdown2 cache-clear |
Delete the local metadata cache. |
Common get options:
| Option | Description |
|---|---|
-o, --output PATH |
Destination directory or file path. Defaults to the current directory. |
-w, --workers N |
Maximum concurrent file transfers. |
-c, --chunks N |
Parallel HTTP Range streams per large file. |
-r, --rate RPS |
Per-host request rate limit in requests per second. |
--flat |
Flatten the remote tree into the output directory. |
--overwrite |
Overwrite existing local files. |
--skip |
Skip files that already exist locally. |
--export-format FORMAT |
Export format for Google Workspace documents (docx, xlsx, pptx, pdf, csv, txt, ...). |
--verify / --no-verify |
Enable or disable MD5 verification. |
--api-key KEY |
Use Google Drive API v3 with an API key. |
--service-account FILE |
Use a GCP service-account JSON key. |
--tui |
Launch the interactive terminal UI. |
--json |
Emit newline-delimited JSON events. |
See the full CLI reference for every command and option.
Python API
gdown2 exposes both async functions and a synchronous convenience wrapper.
import asyncio
import gdown2
def main() -> None:
# Synchronous helper for scripts and notebooks.
tasks = gdown2.download_sync(
"https://drive.google.com/file/d/1A2B3C4D5E6F7G8H9I0J/view",
output="./data",
)
print(f"Downloaded {len(tasks)} task(s)")
async def async_example() -> None:
info = await gdown2.get_info("1A2B3C4D5E6F7G8H9I0J")
print(f"Resolved: {info.name} ({info.size} bytes)")
tree = await gdown2.get_tree(
"https://drive.google.com/drive/folders/1FolderId_9876543210"
)
tasks = await gdown2.download(tree.item.id, output="./data")
print(f"Completed {sum(t.state == 'done' for t in tasks)} file(s)")
main()
asyncio.run(async_example())
For custom observers, runtime configuration, and cancellation patterns, see Python API.
Authentication
Public links work with no configuration. Providing credentials switches gdown2 from
web scraping to the official Drive API v3, which is recommended for large folders,
private files, and higher rate limits.
Credential sources can be combined with CLI flags, environment variables, and
config.toml. When more than one credential is available, the selected provider order
is:
- Service account (
--service-account/GDOWN2_SERVICE_ACCOUNT_FILE) - OAuth user file (
GDOWN2_OAUTH_FILE) - OAuth bearer token (
GDOWN2_ACCESS_TOKEN) - API key (
--api-key/GDOWN2_API_KEY/GOOGLE_API_KEY) - Anonymous public access
Environment examples:
# API key
export GDOWN2_API_KEY="AIza..."
# OAuth bearer token
export GDOWN2_ACCESS_TOKEN="ya29..."
# OAuth authorized_user JSON file
export GDOWN2_OAUTH_FILE="$HOME/.config/gdown2/authorized_user.json"
# GCP service account
export GDOWN2_SERVICE_ACCOUNT_FILE="$HOME/.config/gdown2/service_account.json"
See Configuration for the complete authentication and settings reference.
Configuration
Configuration is merged with the following precedence:
CLI flags > environment variables > config.toml > built-in defaults
Default config location: ~/.config/gdown2/config.toml (or your OS user config
directory when that path does not exist).
[download]
workers = 6
chunks_per_file = 4
rate_limit_rps = 5.0
max_retries = 5
timeout_seconds = 30.0
verify_checksums = true
existing_policy = "resume" # "resume" | "skip" | "overwrite"
export_format = "pdf"
[auth]
# Supplying credentials switches gdown2 to Drive API v3.
api_key = "AIza..."
# oauth_token_file = "~/.config/gdown2/authorized_user.json"
# service_account_file = "~/.config/gdown2/service_account.json"
Reliability model
gdown2 treats downloads as recoverable transactions rather than one-shot streams.
- Never writes directly to the final filename. Incoming bytes go to
<filename>.part. The final file appears only after verification succeeds. - Handles
206,200, and416correctly. If the server honoursRange, the transfer resumes. If it ignoresRangeand returns200, the partial file is reset instead of being corrupted. If it returns416, the existing part is verified and promoted when complete. - Protects against stale partial data. When the remote ETag changes or overwrite mode
is requested, stale
.partfiles are discarded before a new transfer starts. - Verifies before promoting. Size and MD5 checks run before the atomic rename. Checksum failures delete the corrupted part and retry from byte zero.
- Survives cancellation.
Ctrl+Cflushes resume state and leaves partial files ready forgdown2 resume. - Rejects untrusted redirects. Only HTTPS Google domains are followed during redirects and initial download URLs are validated before use.
The complete design and edge-case walkthrough is in Architecture.
Exit codes
| Code | Name | Meaning |
|---|---|---|
0 |
OK |
All requested files downloaded (or skipped) and verified. |
1 |
GENERAL_ERROR |
One or more transfers failed. |
2 |
INVALID_ARGUMENT |
Malformed URL or unrecognized Google Drive ID. |
3 |
AUTH_REQUIRED |
HTTP 401 or expired/missing credentials. |
4 |
PERMISSION_DENIED |
HTTP 403 permission error (private file or folder). |
5 |
NOT_FOUND |
HTTP 404 / 410 resource does not exist. |
6 |
QUOTA_EXCEEDED |
Per-file download quota or rate limit exhausted. |
7 |
NETWORK_ERROR |
Unrecoverable transport error or untrusted redirect. |
8 |
INTEGRITY_ERROR |
Size or MD5 checksum mismatch after retries. |
9 |
STORAGE_ERROR |
Insufficient disk space, permission error, or path traversal. |
130 |
CANCELLED |
Interrupted by the user (Ctrl+C). |
This allows shell scripts and CI jobs to distinguish transient network problems from permission or quota failures.
Documentation
- CLI reference
- Python API
- Configuration
- Architecture
- Troubleshooting
- Development guide
- Releasing and PyPI publishing
Development
# Create an isolated environment.
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
# Install with development dependencies.
pip install -e ".[dev]"
# Run the test suite.
pytest
# Lint and type-check.
ruff check .
mypy gdown2
The test suite uses respx to mock Google Drive endpoints. It covers URL parsing,
cross-platform path sanitization, tree operations, retry/AIMD policies, virus-scan
interstitials, 206/200/416 resume behaviour, rate-limit backoff, checksum
recovery, folder pagination, and shortcut cycles.
Live end-to-end tests are opt-in:
GDOWN2_E2E_URL="https://drive.google.com/file/d/<id>/view" pytest tests/e2e
See Development guide for the full workflow.
Project layout
gdown2/
├── domain/ # Pure models, URL parser, tree operations, path policy, errors
├── application/ # Resolver, crawler, planner, scheduler, worker, verifier, reporter
├── infrastructure/ # HTTP, Drive API/web adapters, auth, cache, config, storage
├── interfaces/ # Typer/Rich CLI, Textual TUI, NDJSON event writer
├── sdk.py # Public async and synchronous Python API
└── py.typed # PEP 561 typing marker
The domain layer has no network or filesystem dependencies. Application services
coordinate work through protocol interfaces, and infrastructure adapters can be replaced
without touching the engine. See Architecture for details.
Contributing
Contributions are welcome.
- Fork the repository and create a feature branch.
- Install the development dependencies with
pip install -e ".[dev]". - Add or update tests for your change.
- Run
pytest,ruff check ., andmypy gdown2. - Open a pull request with a clear description of the problem and solution.
Please keep user-facing strings, comments, and documentation in English.
License
MIT. See LICENSE.
Metadata
Release files for gdown2 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gdown2-0.2.0.tar.gz | 63.4 kB | With provenance | Details for gdown2-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gdown2-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for gdown2-0.2.0-py3-none-any.whl |
Total release size: 140.1 kB
Release files / gdown2-0.2.0.tar.gz
| Download URL | gdown2-0.2.0.tar.gz |
|---|---|
| Size | 63.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5603f57b80099c74539f73efe7d63d6a26a313a85e53368ccd53038c53fcd05d
|
|
BLAKE2b-256 checksum How to use checksums |
0e9bb06ffaad3493b40dcc4d9fe9e8a9c19f6c806a56e27f65ef6a02dc9bb485
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / gdown2-0.2.0-py3-none-any.whl
| Download URL | gdown2-0.2.0-py3-none-any.whl |
|---|---|
| Size | 76.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3571807857594551b15958a061aebadf5793dd502e7c5ab63f0feaa0c16d50c4
|
|
BLAKE2b-256 checksum How to use checksums |
07da655af5b1eed21f6c035253a728debc5087126d22dc690eab1aa9ae34240f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for gdown2 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for gdown2-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.