Command not found
Confirm the pip environment or package-manager path, then open a new shell. On Windows, py -m gallery_dl --version can distinguish a working Python package from a missing launcher.
py -m gallery_dl --versiongallery-dl Troubleshooting
Use gallery-dl troubleshooting to separate installation, unsupported URL, authentication, configuration, site response, and local storage failures before changing several settings.
DIAGNOSTIC WIZARD
Diagnose a gallery-dl error
Select the closest symptom and environment. The wizard returns a short, ordered test plan instead of a long list of unrelated fixes.
Run the same public URL with --config-ignore --simulate first. If the result changes, isolate config, URL recognition, cookies, output, or rate limits one layer at a time.
ONE VARIABLE AT A TIME
Start gallery-dl Troubleshooting with a Clean Test
Begin with gallery-dl --version. This proves which executable your shell can find and gives a version for documentation or issue searches. Next select one small, reproducible URL and run --config-ignore --simulate. That removes download writes and most local defaults from the test. Use -E if you need to see which extractor claims the URL.
Only after the extractor is recognized should you add cookies for content your account can view. Add destination, archive, filters, metadata, and ZIP behavior after authentication works. This order prevents a filename expression, stale archive, locked browser database, or unwritable folder from being mistaken for a site-support failure.
Confirm executable
gallery-dl --versionClean extraction test
gallery-dl --config-ignore --simulate "URL"Identify extractor
gallery-dl --config-ignore -E "URL"Inspect config paths
gallery-dl --config-status
READ THE STATUS IN CONTEXT
Fix gallery-dl 403, 404, and authentication errors
A 401 usually points to missing or expired authentication. A 403 means the server understood the request but refused it; possible causes include missing cookies, access policy, rate limiting, a challenge, regional behavior, or extractor changes. A 404 can mean the item was removed, the account is private, the copied URL is not canonical, or the site deliberately hides unavailable content behind a not-found response.
Confirm the URL in a normal browser and check whether login is required. If authorized content is visible, test local browser cookies. Do not repeatedly retry a refused endpoint or attempt to bypass access controls. Check the current upstream supported-sites notes and recent official issues, but redact private URLs, cookies, usernames, headers, and local paths before sharing diagnostics.
| Symptom | Likely layer | First safe check |
|---|---|---|
| 401 or login redirect | Authentication | Verify session in the selected browser profile |
| 403 Forbidden | Auth, policy, rate, or extractor | Stop retries; compare public and cookie simulation |
| 404 Not Found | URL, deletion, privacy, or extractor | Open the canonical URL in a normal browser |
| No extractor found | Unsupported URL pattern | Check supported sites and try the canonical page URL |
| Zero files | Wrong URL capability or filter | Remove filters and inspect with -K and -E |
CHECK YOUR MACHINE
Fix PATH, config, filename, and disk errors
When the shell says gallery-dl is not recognized or command not found, the executable is not on that shell's PATH or a different installation context is active. Run it through Python's module form when installed with pip, restart the terminal after PATH changes, and avoid installing the same command through several package managers unless you know which one wins.
Config parse errors occur before extraction and usually come from invalid JSON. Validate double quotes, commas, and escaped Windows paths. Permission and filename errors happen during output preparation. Try a short writable destination, keep filenames conservative, and check free space before large jobs. gallery-dl does not need a special low-disk stop option to justify monitoring storage at the operating-system level.
Config or output failure
Compare with --config-ignore, then test a simple writable destination. Reintroduce the config one key at a time after valid JSON is confirmed.
gallery-dl --config-ignore --destination "./test-output" --simulate "URL"
UPDATE CLEANLY
Update gallery-dl and prepare a safe bug report
Update through the same channel used for installation: pip, standalone executable, Homebrew, Chocolatey, Scoop, Snap, or another package source. Confirm the version afterward because an older executable elsewhere on PATH may still be running. Package-manager releases can lag behind PyPI, so compare versions before assuming an update command failed.
A useful report contains the gallery-dl version, operating system, a public reproducible URL when lawful, the smallest command that triggers the issue, and redacted error output. State whether --config-ignore changes the result and whether browser cookies are required. Search existing upstream issues first. Never publish raw cookies, authorization headers, private media URLs, full local usernames, or secret config values.
- Reproduce with the smallest public URL and --config-ignore --simulate.
- Record gallery-dl version, operating system, and installation method.
- State the expected result and the actual error exactly.
- Redact cookies, tokens, private URLs, account IDs, and filesystem usernames.
- Mention whether the URL works in the same signed-in browser profile.
- Link an existing upstream issue when the symptoms match.
Respect site and content rules
Troubleshooting should restore ordinary authorized access, not bypass paywalls, access controls, regional restrictions, rate limits, or account permissions.
PRESERVE A BASELINE
gallery-dl troubleshooting starts with one clean test
gallery-dl troubleshooting starts with one clean test that you can repeat after every change. Record the resolved executable, version, canonical public URL, and result of --config-ignore --simulate. Then change only one layer: URL form, authentication, config, destination, or filter. A stable baseline makes gallery-dl troubleshooting faster because each comparison has a clear meaning.
Keep a short, secret-free incident note for recurring jobs. Include the error category, time, installation channel, and whether a normal browser could open the URL. Do not include cookies, tokens, private links, or identifying local paths. If gallery-dl troubleshooting reaches an upstream report, this compact evidence helps maintainers reproduce the extractor behavior without exposing your account.
FAQ
gallery-dl troubleshooting FAQ
Why is gallery-dl not working on Windows?
Confirm which executable is on PATH with gallery-dl --version, then run a small --config-ignore --simulate test. This separates a Windows installation or PATH issue from URL, extractor, cookie, or config problems.
How do I fix gallery-dl 403 Forbidden?
Stop repeated requests, confirm normal browser access, test authorized local cookies, update gallery-dl, and compare a config-free simulation. A 403 may also reflect policy or rate limits.
Why does gallery-dl show an unsupported URL error?
The domain or URL pattern may not be supported, or the copied link may not be canonical. Check the supported-sites list, try the public post, profile, album, or gallery URL, and run -E before changing authentication settings.
How do I know whether config causes the error?
Run the same URL with --config-ignore --simulate. If the result changes, reduce the config to a minimal valid file and restore keys gradually.
Why does updating gallery-dl not change the version?
A different executable may be earlier on PATH, or your package source may lag. Check the installation channel and the resolved executable.
What should I remove during gallery-dl troubleshooting?
gallery-dl troubleshooting starts with one clean test, but any shared log must redact cookies, tokens, authorization headers, private URLs, account identifiers, email addresses, and identifying local paths.
Authoritative references
NEXT STEP