aio-grab
Download video, audio and images from YouTube and 1,000+ other sites with one call. A friendly, typed layer over yt-dlp, gallery-dl and ffmpeg: sensible defaults, sizes before you download, clear error messages, and one progress figure.
Part of Aio, which also ships a self-hosted web app and Telegram bot built on this library.
pip install aio-grab
ffmpeg is taken from your PATH, or a static build is downloaded on first use. YouTube needs a JavaScript runtime on PATH (Node, Deno or Bun).
Command line
aio-grab https://youtu.be/dQw4w9WgXcQ # best video, up to 4K
aio-grab -q 1080 --compatible URL # 1080p H.264/AAC, plays everywhere
aio-grab -x URL # MP3, 320 kbps
aio-grab -x -f opus URL # smallest file at the same quality
aio-grab --start 1:30 --end 2:00 URL # just that clip
aio-grab --sponsorblock URL # without sponsor segments (YouTube)
aio-grab -i URL # qualities, codecs and sizes; no download
aio-grab -i --json URL # the same, machine-readable
aio-grab -a links.txt -o ~/Downloads # one link per line
aio-grab --help lists every option. --cookies, --proxy and --ffmpeg also read AIO_COOKIES_FILE,
AIO_PROXY and AIO_FFMPEG.
Library
import aio_grab
info = aio_grab.probe("https://youtu.be/dQw4w9WgXcQ")
for row in info["video"]:
print(row["label"], row["codecs"], row["size_sdr"]) # 4K ['AV1', 'VP9'] 244057213 ...
files = aio_grab.download("https://youtu.be/dQw4w9WgXcQ", "downloads", kind="audio", audio_format="mp3")
Engine
aio_grab.probe and aio_grab.download use a shared default Engine. Create your own for cookies, a proxy or a
specific ffmpeg. An Engine is thread-safe: one instance can run many downloads in parallel.
from aio_grab import Engine, EngineError, Request
engine = Engine(
cookies_file="cookies.txt", # Netscape format, for sites that need a login
proxy="http://proxy:8080",
ffmpeg="", # binary or folder; empty = PATH, else a static build
fetch_ffmpeg=True, # False: never download ffmpeg, fail instead
)
def on_progress(**update):
# Any of: status, stage, progress (0-100 or None), speed (bytes/s), eta (s), title, platform, thumbnail, duration
print(update)
try:
files = engine.download(Request("https://youtu.be/dQw4w9WgXcQ", quality="720"), "downloads", on_progress)
except EngineError as e:
print(e) # a message meant for people, e.g. "This video is private."
engine.download(..., zip_posts=True) returns one ZIP for a multi-item post instead of one file per item.
Request
Invalid combinations raise ValueError when the Request is created.
| Field | Values | Default |
|---|---|---|
url |
link to a video, track, post, short playlist or image gallery | required |
kind |
video, audio |
video |
quality |
best (up to 4K) or a maximum resolution, e.g. 1080 |
best |
codec |
best (AV1/VP9) or compatible (H.264/AAC) |
best |
hdr |
prefer HDR streams | False |
container |
mp4, mkv |
mp4 |
subtitles |
language code to embed, e.g. en, or en-orig for auto-generated |
none |
audio_format |
original, mp3, m4a, opus, flac, wav |
mp3 |
audio_bitrate |
mp3: 320 256 192 128; m4a: 256 192 128 |
highest |
sponsorblock |
cut sponsor segments (YouTube) | False |
start, end |
trim range: seconds or "[hh:]mm:ss" |
none |
precise_trim |
frame-exact cuts (re-encodes; slow above 1080p) | False |
Probe results
probe() returns a dict whose kind is:
media: one video or track.videohas one row per resolution withcodecs,fps,hdr, and the size and codec a download would get in each mode (size/codecfor HDR,size_sdr/codec_sdr,size_compatible/codec_compatible).audiodescribes the best source audio;subtitleslists the tracks.post: several items (a carousel, a multi-video tweet, a short playlist), withitemsandentries.images: a photo or gallery, withitems. Downloading it saves every image.
License
GPL-3.0-or-later. yt-dlp is Unlicense; gallery-dl (GPL-2.0) runs as a separate process.
Metadata
Release files for aio-grab 0.1.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 |
|---|---|---|---|---|
| aio_grab-0.1.0.tar.gz | 37.3 kB | With provenance | Details for aio_grab-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aio_grab-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for aio_grab-0.1.0-py3-none-any.whl |
Total release size: 73.5 kB
Release files / aio_grab-0.1.0.tar.gz
| Download URL | aio_grab-0.1.0.tar.gz |
|---|---|
| Size | 37.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ada545dd97222a6c16a61664567d941f3d0783178ec08e6f24c72a34d08150e1
|
|
BLAKE2b-256 checksum How to use checksums |
516b488360bd1eb0d46f3a3e378b75b30e806913ce29a8560ca81e9060b36018
|
| 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 10, 2026.
Transparency logRelease files / aio_grab-0.1.0-py3-none-any.whl
| Download URL | aio_grab-0.1.0-py3-none-any.whl |
|---|---|
| Size | 36.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d069a0c9f0507b94807965c0451a919b5eee65f81adbeedbe33f7ae7c07128b7
|
|
BLAKE2b-256 checksum How to use checksums |
0233e1eec0bfaf568a9e9b8daa643f4516bf1b0c36f33e9ac0ee6e3c87bb84e6
|
| 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 10, 2026.
Transparency logSecurity for aio-grab 0.1.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 aio_grab-0.1.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 10, 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.