Skip to content
Get packs

Guide · Open source

How to use douyin-downloader: install, configure and run

Updated · written with AI from the project's own documentation and checked against our catalogue data

douyin-downloader is an MIT-licensed Python project for downloading Douyin videos and photos without watermarks, with a command-line tool for scripts and batch jobs and a desktop app called Douzy. This guide walks through the CLI setup from the README: cloning the repository, installing Playwright with Chromium, saving sign-in cookies, and running a profile download. It also explains the current limits you should know before you start.

Douyin Downloaderjiji262/douyin-downloader · ★ 12.5k · MIT

Quick start

  1. 1Clone the repository. Run git clone on the jiji262/douyin-downloader repository and enter the folder.
  2. 2Install dependencies. Install requirements.txt with pip, then install playwright and its chromium browser.
  3. 3Copy the sample config. Copy config.example.yml to config.yml so you can edit your settings.
  4. 4Save sign-in cookies. Run the cookie fetcher, sign in to Douyin in the browser, then press Enter in the terminal.
  5. 5Set your profile link. Replace the sample link with your creator's profile URL and set number.post and increase.post.
  6. 6Run the downloader. Run python run.py -c config.yml and check the output folder.

Check whether the CLI fits your needs

The README states that the CLI supports Douyin only and that Douyin's request verification currently blocks CLI downloads of individual videos and photos, collections, music, likes, and favorites. Profile posts can try a Playwright browser fallback, but success is not guaranteed.

For everyday downloads, the README recommends the Douzy desktop app instead.

  • Requires Python 3.9+ on Windows, macOS, or Linux
  • Refreshing cookies or retrying does not fix the verification block, according to the README

Install douyin-downloader and Playwright

Clone the repository, install the Python dependencies, then install Playwright and its Chromium browser.

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 chromium

Create config.yml and sign in to Douyin

Copy the sample configuration file to config.yml. Then run the cookie fetcher, sign in to Douyin in the browser that opens, return to the terminal and press Enter to save cookies.

On Windows PowerShell, use Copy-Item instead of cp.

cp config.example.yml config.yml python -m tools.cookie_fetcher --config config.yml

Set the profile link and download options

Replace the sample link in config.yml with your creator's profile URL. The fields below limit the download to 10 posts, skip items already downloaded, and save into ./Downloaded/.

  • number.post: 0 means unlimited
  • increase.post: true skips downloaded items
  • redownload_missing_files: true downloads missing files again
  • start_time and end_time filter by date using YYYY-MM-DD
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: true

Run the download and check the options

Start a run with your config file. Run --help to see every option. Add -v for detailed logs when troubleshooting.

  • -c, --config: config file
  • -u, --url: add a URL to the config links; repeatable
  • -p, --path: download folder
  • -t, --thread: concurrent downloads
  • -v, --verbose: detailed logs
python run.py -c config.yml

Troubleshoot common problems

If cookies expire, run the cookie fetcher again. If you get only a few profile posts, the README suggests keeping browser_fallback.enabled set to true and headless set to false, then completing any verification yourself in the browser. The verification block may still prevent downloads.

  • Expired cookies: rerun python -m tools.cookie_fetcher --config config.yml
  • Missing posts: check browser_fallback settings and complete verification manually
  • Need details: run with -v
python run.py -c config.yml -v

What people use it for

  • Archiving a creator's public Douyin posts for personal reference using a profile URL
  • Scripting repeat profile downloads with a date range set in config.yml
  • Keeping a local record of downloads so already-saved items are skipped on later runs
  • Exploring hot search boards or keyword search results as JSONL with --hot-board or --search

Frequently asked questions

Is douyin-downloader free to use?

The project is released under the MIT License, as stated in the README and LICENSE file. The README asks users to respect copyright, privacy, and platform rules.

What are the requirements for douyin-downloader?

The README lists Python 3.9+ on Windows, macOS, or Linux, plus Playwright with Chromium, which the install steps set up. You also need a Douyin sign-in so the tool can save cookies.

Why does douyin-downloader fail for single videos?

The README says Douyin's request verification currently blocks CLI downloads of individual videos and photos, collections, music, likes, and favorites. Refreshing cookies or retrying does not fix this, so the README recommends the Douzy desktop app.

Does douyin-downloader remove watermarks?

The project description says it downloads Douyin videos and photos without watermarks. Success for CLI downloads depends on the current verification block described in the README.

What are alternatives to douyin-downloader?

The comparable projects listed are yt-dlp, gallery-dl, and TikTok-Api. The README's own alternative for everyday use is the Douzy desktop app, which also covers TikTok, YouTube, Telegram, and X.

Why are only a few profile posts downloading?

The README's FAQ suggests keeping browser_fallback.enabled set to true and headless set to false, then completing any verification in the browser. It also warns that the verification block may still prevent downloads.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

douyin-downloader suits people comfortable with Python and terminal setup who want scripted downloads of a creator's public posts for personal archiving. If you need reliable downloads of single videos, collections, music, or likes, or you want a simple interface, pick the Douzy desktop app or another tool, since the README says the CLI is currently blocked for many of those cases.

Install options & downloads