Skip to main content

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. video has one row per resolution with codecs, fps, hdr, and the size and codec a download would get in each mode (size/codec for HDR, size_sdr/codec_sdr, size_compatible/codec_compatible). audio describes the best source audio; subtitles lists the tracks.
  • post: several items (a carousel, a multi-video tweet, a short playlist), with items and entries.
  • images: a photo or gallery, with items. 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)

Source distribution for aio-grab 0.1.0
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)

Table of built distributions (wheels) for aio-grab 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page