Skip to content

cookie-setup.md

Latest commit

 

History

History
175 lines (115 loc) · 5.19 KB

cookie-setup.md

File metadata and controls

175 lines (115 loc) · 5.19 KB
Raw

Cookie setup guide

Some platforms block anonymous downloads. dwnld-any stores cookies as Netscape-format text files under ~/.config/dwnld-any/cookies/ and loads them via environment variables.

Quick reference

Platform Required? Env variable Default file
Instagram Yes YTDLP_COOKIES_INSTAGRAM ~/.config/dwnld-any/cookies/instagram.txt
YouTube Optional YTDLP_COOKIES_YOUTUBE ~/.config/dwnld-any/cookies/youtube.txt
Reddit Optional YTDLP_COOKIES_REDDIT ~/.config/dwnld-any/cookies/reddit.txt
X (Twitter) Optional YTDLP_COOKIES_X (or X_AUTH_TOKEN + X_CT0) ~/.config/dwnld-any/cookies/x.txt

Run python -m dwnld setup to see which cookies are configured.

Step 1 — Create the cookie directory

mkdir -p ~/.config/dwnld-any/cookies

Step 2 — Export cookies from your browser

Use a browser extension that exports Netscape cookie format (.txt):

  1. Install one of:

  2. Log in to the platform in that browser (instagram.com, youtube.com, etc.).

  3. Open the site, click the extension, and export cookies for that domain.

  4. Save the file to the path in the table above.

Security: Cookie files are session keys. Never commit them to git or paste them in chat. If exposed, log out everywhere and export fresh cookies.

Instagram (required)

Instagram downloads will fail without cookies.

Export

  1. Go to instagram.com and log in.
  2. Export cookies with your extension.
  3. Save as: 
    ~/.config/dwnld-any/cookies/instagram.txt

Configure

Add to ~/.zshrc or ~/.bashrc:

export YTDLP_COOKIES_INSTAGRAM=~/.config/dwnld-any/cookies/instagram.txt

Reload: source ~/.zshrc

Verify

python -m dwnld setup
# instagram row should show: ready

Minimum cookies needed

The file should include (at minimum) for .instagram.com:

  • sessionid
  • csrftoken
  • ds_user_id

YouTube (optional)

Helps when YouTube shows “Sign in to confirm you're not a bot.”

  1. Log in at youtube.com.
  2. Export cookies → save to ~/.config/dwnld-any/cookies/youtube.txt.
  3. Export: 
    export YTDLP_COOKIES_YOUTUBE=~/.config/dwnld-any/cookies/youtube.txt

Reddit (optional)

Reddit often blocks anonymous API access (HTTP 429). dwnld-any uses --impersonate chrome by default; cookies help when that is not enough.

  1. Log in at reddit.com.
  2. Export cookies → save to ~/.config/dwnld-any/cookies/reddit.txt.
  3. Export: 
    export YTDLP_COOKIES_REDDIT=~/.config/dwnld-any/cookies/reddit.txt

Note: Text-only posts have no video — only posts with embedded video can be downloaded.

X / Twitter (optional)

Public tweets usually work without cookies. Export cookies if you hit login or rate-limit errors.

Option A — cookies.txt file

  1. Log in at x.com.
  2. Export cookies → save to ~/.config/dwnld-any/cookies/x.txt.
  3. Export: 
    export YTDLP_COOKIES_X=~/.config/dwnld-any/cookies/x.txt

Option B — raw cookie values

If you already have auth_token and ct0 from your browser's dev tools (Application/Storage → Cookies → x.com), set them directly — no file export needed:

export X_AUTH_TOKEN=<your auth_token value>
export X_CT0=<your ct0 value>

Both must be set together — a lone X_AUTH_TOKEN or X_CT0 is treated as not configured. If YTDLP_COOKIES_X also points at an existing file, that file takes precedence over these raw values.

Security: the same rule as cookie files applies — set these as env vars in your own shell/session, never paste the actual token values in chat.

Step 3 — Persist env vars (recommended)

Add all exports to your shell profile:

# ~/.zshrc
export YTDLP_COOKIES_INSTAGRAM=~/.config/dwnld-any/cookies/instagram.txt
export YTDLP_COOKIES_YOUTUBE=~/.config/dwnld-any/cookies/youtube.txt
export YTDLP_COOKIES_REDDIT=~/.config/dwnld-any/cookies/reddit.txt
export YTDLP_COOKIES_X=~/.config/dwnld-any/cookies/x.txt

Or copy .env.example to .env in the repo and source it during sessions (do not commit .env).

Sharing cookies with an agent

When an agent asks for cookies:

  1. Do not paste cookie values in chat.
  2. Tell the agent the file path on your machine, e.g. ~/.config/dwnld-any/cookies/instagram.txt.
  3. Or export fresh cookies to that path and confirm the env var is set.
  4. The agent runs python -m dwnld setup to verify file_exists: true.

Troubleshooting

Symptom Fix
empty media on Instagram Re-export cookies; session may have expired
YouTube bot check Add YTDLP_COOKIES_YOUTUBE
Reddit HTTP 429 Add YTDLP_COOKIES_REDDIT or retry later
X login required Add YTDLP_COOKIES_X
File not found Check path and export in the same shell session