Douyin Downloader: why the Python CLI now defers to the Douzy desktop app for watermark-free downloads
A practical Douyin downloader for both single-item and profile batch downloads, with progress display, retries, SQLite deduplication and browser fallback support. Supports watermark-free downloads of videos, image sets, collections and music (original audio).
At a glance
- What is it?
- jiji262/douyin-downloader ships a Python CLI for Douyin and a separate desktop app, Douzy, that also covers TikTok, YouTube, Telegram and X. Douyin's request verification currently blocks most CLI downloads, which changes what the repository is good for.
- Who is it for?
- Use Douzy, the desktop app from the releases page, if you want to save Douyin videos without watermarks today, and accept that some batch and advanced features require activation. Use the Python CLI only if you need scripted profile batches, date filters or JSONL hot-board exports and can tolerate the Playwright fallback failing.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- jiji262/douyin-downloader12,644 ★ · +436
| Repository | 2026-10-07 | 2026-11-21 |
|---|---|---|
| jiji262/douyin-downloader | 12.2k | 12.6k |
436 Stars in the last 45 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Douzy desktop and the Python CLI are two separate tools in one repository
The repository holds two products with different reach. Douzy is a Windows and macOS desktop app, distributed through GitHub releases (Desktop 0.12.5 shipped on 2026-10-08, Desktop 0.12.1 on 2026-09-23). It covers Douyin, TikTok, YouTube, Telegram and X: you paste links, track downloads and browse a local archive. On Douyin it handles videos, photos, profiles and collections, plus following, subscriptions, favorites and likes. Telegram requires setup and sign-in, and X requires account cookies.
The Python CLI is the open part you can read and script. It supports Douyin only, with batch downloads, date filters, retries, download history, and optional comments, transcription and notifications. pyproject.toml calls it version 2.0.0, classifies it as Development Status 4 (Beta), and requires Python 3.9 or newer.
The split matters because the two do not behave the same today. The README sends everyday users to Douzy and lists the CLI's restrictions first, ahead of its install steps. Douzy has its own catch: platform features depend on enabled plugins or local components, and some batch and advanced features require activation.
Douyin's request verification blocks most CLI downloads
This is the fact that decides whether the CLI is useful to you. According to the README, Douyin's request verification currently blocks CLI downloads of individual videos and photos, collections, music, likes and favorites. That covers almost every mode the CLI was built for.
Profile posts are the exception, and only partly. The CLI can try a Playwright browser fallback for them, but success is not guaranteed. The README's advice when only a few profile posts come back is to keep browser_fallback.enabled set to true and headless set to false, then complete any verification yourself in the visible browser window. Even then, the current block may still stop the download.
Two common fixes do not help. The README says refreshing cookies or retrying does not get past this verification block, so a script that loops on failure only wastes time. For a user who wanted an unattended job that pulls a creator's posts every night, the consequence is direct: you need a person at the browser, and you may still get nothing.
Setting up the CLI with Playwright, Chromium and the cookie fetcher
With those limits in mind, setup takes three steps. First clone the repository and install dependencies, including Playwright and its Chromium build for the browser fallback:
git clone https://github.com/jiji262/douyin-downloader.git
cd douyin-downloader
python -m pip install -r requirements.txt
python -m pip install playwright
python -m playwright install chromiumNext copy the sample config and run the cookie fetcher. A browser opens, you sign in to Douyin, then return to the terminal and press Enter to save the cookies into config.yml. On Windows PowerShell, copy the file with Copy-Item instead of cp.
cp config.example.yml config.yml
python -m tools.cookie_fetcher --config config.ymlThen replace the sample link with a creator's profile URL and set the download scope:
link:
- https://www.douyin.com/user/YOUR_SEC_UID
path: ./Downloaded/
mode: [post]
number:
post: 10 # 0 = unlimited
increase:
post: true # skip downloaded items
redownload_missing_files: trueFinally run it:
python run.py -c config.ymlCommand-line flags adjust a run: -u appends a URL and can be repeated, -p sets the download folder, -t sets concurrent downloads and -v turns on detailed logs. When cookies expire, run the cookie fetcher command again.
How increase.post and the SQLite history decide what gets skipped
Deduplication is where the CLI shows care. Download history goes into SQLite (aiosqlite is a core dependency), and incremental runs check for non-empty primary media on disk, not just a database row.
Two settings control the behaviour. With increase.post set to true, already downloaded items are skipped. Set it to false and the CLI downloads again and overwrites files in the selected scope, which is the documented way to force a refresh; you do not need to clear the database. The same switch exists for like, mix and music. redownload_missing_files defaults to true, so a file you deleted from disk gets fetched again. With false, valid database history can still skip it.
The trap is the overwrite. Flipping increase.post to false on a folder you have edited or renamed by hand replaces files in that scope without asking. Back up first if the archive matters.
number.post caps the item count, with 0 meaning unlimited. start_time and end_time take YYYY-MM-DD dates, and the end date is included in full. video_quality defaults to highest; original tries the original upload and falls back when it is not available.
Hot board exports, keyword search and the optional REST server
Some CLI features produce data rather than media files. The hot search board and keyword search write JSONL:
python run.py --hot-board 30
python run.py --search "cats" --search-max 50The CLI can also run as a REST API server. FastAPI and uvicorn are not in requirements.txt and are installed separately:
python -m pip install fastapi uvicorn
python run.py --serve --serve-port 8000Serving over HTTP does not change what Douyin's verification lets through. The same account cookies and the same block apply, so a REST call for a single video is no more likely to succeed than the command line. Before opening port 8000 to anything beyond your own machine, read the server/ directory to see how requests are authenticated, since the server acts with your saved Douyin cookies.
Live recording saves an HLS playlist, and transcription bundles ffmpeg
Two optional features carry their own caveats. Live recording is labelled experimental, and the README is specific about its failure: HLS sources save a playlist, not a playable video. If you start a recording expecting a video file at the end, an HLS stream leaves you with a playlist instead.
Transcription has a heavier footprint than its one-line mention suggests. pyproject.toml pins imageio-ffmpeg to exactly 0.6.0 because core/audio_extraction.py uses its bundled static ffmpeg binary to pull audio tracks before uploading them to an OpenAI-compatible transcription endpoint. A comment explains the pin: 0.6.0 is the first release with a native macOS arm64 wheel. A separate transcribe extra installs openai-whisper. On the endpoint path, your audio leaves the machine for whichever OpenAI-compatible service you point it at, so check that service's terms before transcribing someone else's videos.
Comments, transcription, notifications and live recording are all configured in config.example.yml rather than through flags.
The Dockerfile leaves out the browser fallback
A Dockerfile ships at the root, based on python:3.12-slim. It installs gcc and requirements.txt, creates /app/Downloaded, declares /app/Downloaded and /app/config.yml as volumes, and runs run.py with -c config.yml by default.
What it does not install is Playwright or Chromium. Those come from separate pip and playwright commands in the Quick Start, not from requirements.txt. A container built from this file therefore has no browser fallback, and the fallback is the only route the README offers for profile posts under the current block. The fallback also wants headless set to false and a person completing verification, which a slim container cannot provide. As built, the image fits hot-board and search exports better than media downloads.
The CLI is MIT licensed. The README frames the tool as being for learning and personal data management, asks users to respect copyright, privacy and platform rules, and warns that platform changes may affect availability. The last push was on 2026-11-01, and development runs through `python -m pytest tests/` and `ruff check .` after an editable install with the dev extra.
Editorial conclusion
Use Douzy, the desktop app from the releases page, if you want to save Douyin videos without watermarks today, and accept that some batch and advanced features require activation. Use the Python CLI only if you need scripted profile batches, date filters or JSONL hot-board exports and can tolerate the Playwright fallback failing. Before writing any automation around run.py, confirm that a profile download completes with browser_fallback.enabled set to true, because the README says the current verification block may still prevent it.
Frequently asked questions
Can the douyin-downloader CLI still download single Douyin videos?
Not at the moment. The README says Douyin's request verification blocks CLI downloads of individual videos and photos, collections, music, likes and favorites, and recommends the Douzy desktop app for everyday downloads.
Which platforms does Douzy, the douyin-downloader desktop app, support?
Douzy supports Douyin, TikTok, YouTube, Telegram and X on Windows and macOS. Telegram needs setup and sign-in, X needs account cookies, and some batch and advanced features require activation.
How do I re-download files with douyin-downloader without clearing the database?
Set increase.post to false in config.yml, which downloads again and overwrites files in the selected scope. The same switch exists for like, mix and music.
What should I do when douyin-downloader cookies expire?
Run python -m tools.cookie_fetcher --config config.yml again, sign in to Douyin in the browser, and press Enter in the terminal to save the new cookies.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/jiji262-douyin-downloader)Star history chart for your README
[](https://hysenlabs.com/projects/jiji262-douyin-downloader)Was this useful?