Tumblr workflow guide

gallery-dl Tumblr Guide: Download Blogs and Posts

gallery-dl Tumblr support is easiest to use when you separate URL scope, access, and repeat-run control. This guide shows how to test a public blog, download a narrow tag or post, add cookies only when necessary, and keep the resulting archive predictable.

Blog URLsTags and searchCookiesRepeat-safe archives
Tumblr blog URL flowing through a gallery-dl test into an organized local archive
A Tumblr-specific workflow starts with a small URL test and ends with a reviewed local archive.
Quick answer

Use a public Tumblr blog, tag, post, or search URL as the input. Start with gallery-dl --simulate so you can see the extractor result without writing files, then run the same URL with a small scope and a known destination. Add browser cookies only when Tumblr requires an authenticated session, and keep an archive file when you expect to repeat the job.

URL selection

Choose the right Tumblr URL type

Begin with the smallest URL that answers your question. A post URL is useful for verifying that gallery-dl can parse a specific item. A blog URL is appropriate when you intend to follow a blog's media over time. A tag or search URL is broader and less stable because new results can appear between runs. If you paste a page copied from a mobile share sheet, remove tracking parameters only when you have confirmed that the cleaned URL still points to the same Tumblr scope.

Tumblr hosts can appear in more than one shape. A standard `tumblr.com/blog/name` link, a `name.tumblr.com` subdomain, and a post permalink may all identify the same blog, but they are not equally convenient for a test. Prefer the shortest canonical-looking form and record the original URL in your notes so you can explain a later mismatch.

Do not assume that every image visible in a theme is a downloadable post. Themes can include avatars, recommendation blocks, external embeds, or decorative assets. The extractor's result lines are the useful boundary: inspect the IDs, media URLs, and post types shown by simulation before deciding how wide the job should be.

URL scopeGood first useMain caution
Single postParser and permission checkMay contain one media item or no downloadable media
BlogA creator or topic archiveCan become a large repeat job
TagA narrow subject sampleResults change as Tumblr indexes posts
SearchExploratory discoveryLess stable and harder to reproduce
Custom subdomainA direct blog workflowConfirm the subdomain belongs to Tumblr
Start with one URL

A successful one-post simulation is stronger evidence than a large command that silently mixes theme assets, reblogs, and unrelated search results.

First run

Install and run a safe first test

Install gallery-dl with the method that matches your existing Python or package workflow. The site's install guide covers platform choices; once the executable responds to `gallery-dl --version`, keep the first Tumblr run deliberately small. A simulation prints extractor messages without saving the media, which lets you catch a wrong URL, a login wall, or an unexpectedly broad scope before creating files.

Use a command shape like the following and replace the URL with a public Tumblr target you are allowed to inspect. The output is evidence for your next decision, not a promise that every post will contain a file.

After the simulation looks correct, choose an empty test directory and run the same URL without `--simulate`. Keep the destination separate from an existing archive for the first pass. This makes it easy to compare the number of messages with the number of files and to remove the test output without touching a curated collection.

Three-step gallery-dl Tumblr workflow from URL to test to archive
A repeatable Tumblr job has three visible stages: select a URL, simulate the result, then archive a narrow sample.

Read the simulation output

Look for the extractor name, the Tumblr blog or post identifier, media URLs, and any warning about authentication. If the command prints an empty result, do not immediately add cookies or change many settings. First confirm that the URL is a supported Tumblr form, that the blog is public, and that your installed gallery-dl version is current enough for the site's response.

  • Use `--verbose` while diagnosing a new URL, then remove it for routine runs.
  • Use `--range` or an equivalent narrow scope before a full blog archive.
  • Keep a text note of the URL, date, command, and output directory.
Inspect without writing files
gallery-dl --simulate --verbose https://example.tumblr.com/
Test one post in a dedicated folder
gallery-dl -d ./tumblr-test https://example.tumblr.com/post/123456789
Limit a tag sample
gallery-dl --range 1-20 -d ./tumblr-sample https://www.tumblr.com/tagged/photography
Workflows

Download blogs, tags, posts, and search results

A blog download is the most common gallery-dl Tumblr workflow, but it should not be your default for every task. If you need a single reference image, use the post URL. If you are collecting a theme, use a tag and a small range. If you are exploring an unfamiliar topic, use search only to discover candidate posts, then convert the useful results into narrower post or blog jobs that can be repeated later.

The extractor can encounter more than photo posts. Video and audio posts may have different media behavior, text and quote posts may yield no file, and reblogs may expose metadata you do not want in a filename. Your simulation should tell you which post types appear before you write a filter. A filter built for photos alone can make a mixed blog look empty even though the extractor is working.

For a long blog, divide the job into checkpoints. Run a first range, inspect the folder, record the archive file, and only then expand. If a run stops after a network error, the archive and stable filenames let you resume without treating every earlier item as new.

A practical sequence

First validate a post. Second validate the blog or tag scope. Third decide whether you need cookies. Fourth add the output layout and archive. Fifth schedule or repeat the job only after the small sample is understandable. This sequence separates parser problems from access problems and prevents a large directory from hiding the original mistake.

  • Post URL: best for a one-item parser check.
  • Blog URL: best for a creator or collection archive.
  • Tag URL: best for a bounded topic sample.
  • Search URL: best for discovery, not as an immutable archive key.

What counts as a good result

A good result is explainable. You know which URL produced it, why the number of files is plausible, which post types were included, and where the archive was written. A command that downloads many files but cannot be repeated or audited is a risky Tumblr workflow, even if the folder looks full.

Repeatability

Control configuration, filenames, and archives

Move stable choices into the gallery-dl configuration once the test command is understood. A config can define a Tumblr directory pattern, filename fields, a download archive, and a conservative delay. Keeping these decisions in one reviewed file makes a later command shorter and reduces accidental differences between a manual run and a scheduled run.

Tumblr filenames should answer three questions: which blog produced the file, which post or media identifier is involved, and which sequence number distinguishes multiple media items. Use the filename-templates guide for keyword discovery rather than guessing a field name. If a field is absent for a post type, choose a fallback that stays readable instead of depending on an empty separator or a full caption.

An archive file is a record of processed identifiers, not a backup of the media itself. Keep it beside the job configuration, include it in your backup plan, and do not share it publicly if it contains sensitive URL data. When you change the directory or filename pattern, keep the same archive only if you still want gallery-dl to skip the same logical items.

Minimal configuration shape
{
  "extractor": {
    "tumblr": {
      "directory": ["tumblr", "{blog_name}"],
      "filename": "{id}_{num:>02}.{extension}",
      "archive": "./state/tumblr-{blog_name}.sqlite3"
    }
  }
}
Inspect available keywords
gallery-dl --list-keywords https://example.tumblr.com/
Keep the archive stable

Changing a folder name does not change the archive's identity. Decide whether the same post should remain skipped before you move files or split a blog into new destinations.

Access

Use cookies only when Tumblr requires them

Public Tumblr pages should be your first test. If a browser can see a page but gallery-dl receives an access error, the missing piece may be a session cookie, a consent state, or a site response that changed after the browser loaded it. The site's cookies helper explains how to export browser cookies locally; follow that guide and pass the file through the supported gallery-dl option rather than pasting cookie values into a command or a public issue.

Cookies do not turn a private page into a public one and they do not guarantee that a post can be archived. They expire, reflect the permissions of the account that created them, and can expose account access if copied carelessly. Store the cookie file with restrictive permissions, keep it outside a public web directory, and remove it when the test is complete.

When a cookie-enabled command fails, compare it with a public URL simulation. If the public test also fails, the problem is probably URL parsing, version, network, or rate limiting rather than authentication. This comparison keeps you from rotating credentials when the extractor simply needs an update or a slower request pace.

A cautious access checklist

Confirm the public URL first. Export only the cookies required by the browser workflow. Run a one-post simulation. Avoid committing the cookie file or placing it under the project directory. Revoke or delete the session when you no longer need it.

  • Never paste raw cookie headers into a tutorial, log, or issue.
  • Do not publish another person's authenticated content without permission.
  • Use the smallest authenticated scope that answers the task.
Control

Add filters, delays, and responsible boundaries

A Tumblr archive is easier to manage when the command expresses what you want. Use a range for a first sample, a date or post filter when the metadata supports it, and a post-type condition when mixed content is not useful. Verify each condition with simulation because a filter that matches no items can look like a broken extractor.

Respectful pacing protects both your workflow and the service. A short delay between requests, a modest range, and a stop condition are better defaults than launching several full-blog processes. If Tumblr returns a rate-limit or temporary server response, stop, keep the output and logs, and retry later with a smaller scope. Do not try to defeat a block by cycling accounts or sending aggressive parallel requests.

The technical ability to download a file is not permission to republish it. Check the creator's terms, Tumblr's policies, and the license or copyright status of the media. Keep private or sensitive material out of public archives, and record the source URL next to a local collection when provenance matters.

ControlWhy it helpsWhat to verify
Small rangeLimits the first writeThe range maps to the expected post order
Post-type filterAvoids irrelevant text or mediaSimulation shows at least one matching item
DelayReduces burst trafficThe job remains practical at the slower pace
ArchiveSkips known identifiersThe archive path is stable and backed up
Separate destinationProtects curated filesThe test folder is disposable
Recovery

Troubleshoot common Tumblr failures

Classify the failure before changing the command. A 404 or empty result can mean the URL was copied incorrectly, the blog changed its address, or the selected path is not a supported Tumblr form. A 403 or login message points toward access, consent, cookies, or a site policy response. A timeout or 429 points toward pacing, network stability, or a temporary limit. These categories need different fixes.

For a URL problem, open the page in a normal browser, copy the canonical-looking address, and retry one post with `--simulate --verbose`. For an access problem, compare a public post and an authenticated browser session, then use the cookies helper only if the comparison supports it. For a rate-limit problem, stop the process, wait, reduce the range, and avoid parallel jobs. For an unexpected file count, inspect post types, reblogs, theme assets, and filters before deleting the archive.

Keep the original error text when asking for help. Include the gallery-dl version, operating system, sanitized command, URL shape without private tokens, and whether simulation or a public URL works. Never attach cookie files or private media to a public issue.

Editorial decision flow separating Tumblr URL, access, and wait troubleshooting paths
Separate URL, access, and rate-limit failures before changing configuration or credentials.

Fast diagnostic order

Check the URL shape, then test a single post, then compare public and authenticated access, and only after that change filters or output settings. This order keeps a formatting mistake from becoming a confusing configuration experiment.

  • URL: canonical path, blog name, post ID, and redirect.
  • Access: public visibility, consent, cookies, and account scope.
  • Wait: 403/429, timeout, delay, retry window, and network path.
  • Output: destination, filename fields, archive, and duplicate count.
Questions

gallery-dl Tumblr FAQ

These answers focus on decisions that affect a repeatable Tumblr job. The general installation, configuration, cookies, and troubleshooting pages linked below provide broader examples when your problem is not Tumblr-specific.

FAQ

gallery-dl Tumblr questions

Can gallery-dl download an entire Tumblr blog?

It can process a supported public blog URL, but start with simulation and a small range. A blog may contain mixed post types, reblogs, and a large history, so use a stable destination and an archive before expanding the job.

Should I use a Tumblr blog URL or a tag URL?

Use a blog URL for a creator or collection archive, a tag URL for a bounded subject sample, and a post URL to verify one item. Search URLs are best for discovery because their results can change between runs.

Why does gallery-dl Tumblr return an empty result?

Check the URL shape, blog visibility, gallery-dl version, and simulation output first. An empty result can be a wrong path, an unsupported page state, a filter that matches nothing, or a response that now needs access handling.

Do I need cookies for Tumblr downloads?

Not for every public page. Use cookies only when a public comparison and the error message show that the browser session is required. Keep the file private, avoid committing it, and remember that cookies do not grant permission to private content.

How do I avoid downloading the same Tumblr post twice?

Configure a stable archive and keep it with the job. Reuse the same logical archive when you want known identifiers skipped, and test directory or filename changes separately so you understand what the archive is suppressing.

What should I do after a Tumblr 429 or timeout?

Stop the job, keep the log, wait, reduce the range, and add a conservative delay before retrying. Avoid parallel retries and do not rotate accounts to bypass a limit.

Authoritative references

Official Tumblr extractor sourceOfficial supported-sites documentationgallery-dl release metadata
NEXT STEP

Related gallery-dl resources