e621dl is an automated script, originally by @wwyaiykycnf, which downloads images from e621.net. It can be used to create a local mirror of your favorite searches, and keep these searches up to date as new posts are uploaded.
Put very simply, when e621dl starts, it determines the following based on the config.ini file:
- Which tags you would like to avoid seeing by reading the blacklist section.
- Which searches you would like to perform by reading your search group sections.
Once it knows these things, it goes through the searches one by one, and downloads only content that matches your search request, and has passed through all specified filters.
- Download the latest executable release of e621dl.
or
- Download and install the latest release of Python 3.
- Download the latest source release of e621dl.
- Decompress the archive into any directory you would like.
- Double click the e621dl.exe icon to run the program. It will close immediately on completion.
- If you would like to read the output after the execution is complete, run the program through the command prompt in the directory that you placed the .exe file.
You must install all of this program's python dependencies for it to run properly from source. They can be installed by running the following command in your command shell: pip install [package name].
You must run your command shell with admin/sudo permissions for the installation of new packages to be successful.
The required packages for e621dl are currently:
Open your command shell in the directory you decompressed e621dl into, and run the command py e621dl.py. Depending on your system, the command py may default to Python 2. In this case you should run py -3 e621dl.py. Sometimes, your system may not recognize the py command at all. In this case you should run python3 e621dl.py. In some cases where Python 3 was the first installed version of Python, the command python e621dl.py will be used.
- The most common error that occurs when running a Python 3 program in Python 2 is SyntaxError: Missing parentheses in call to 'print'.
The first time you run e621dl, you will see the following errors:
[i] Running e621dl version 5.0.1.
[i] Getting config...
[!] No config file found.
[i] New default config file created. Please add tag groups to this file.
[✗] Error in Config File. Check error log for error details
Press Enter to continue...
These errors are normal behavior for a first run, and should not raise any alarm. e621dl is telling you that it was unable to find a config.yaml file, so a generic one was created.
Create sections in the config.yaml to specify which posts you would like to download. In the default config file, an example is provided for you. This example is replecated below. Each section will have its own directory inside the downloads folder.
searches:
cats:
tags:
- cat
- yellow_fur
dogs:
tags:
- dog
- brown_fur
The following characters are not allowed in search group names: \, :, *, ?, ", <, >, |, and as they can cause issues in windows file directories. If any of these characters are used, they will be replaced with the _ character. The / character is allowed to be used in section names, but it will be understood as a sub-directory. This may be useful to some users for organization. For example: separating Canine/Fox: and Canine/Wolf:, and separating Feline/Tiger: and Feline/Lion:
Commas should be used to separate tags and ratings, but this is not strictly enforced in current versions of e621dl.
One side effect of the workaround used to search an unlimited number tags is that you may only use up to 4 meta tags :, negative tags -, operational tags ~, or wildcard tags * per group, and they must be the first 4 items in the group. See the e621 cheatsheet for more information on these special types of tags.
| Key | Acceptable Values | Description |
|---|---|---|
| days | Integer from 1 to ∞ |
How many days into the past to check for new posts. |
| ratings | Characters s, q, and/or e |
Acceptable explicitness ratings for downloaded posts. Characters stand for safe, questionable, and explicit, respectively. |
| min_score | Integer from -∞ to ∞ | Lowest acceptable score for downloaded posts. Posts with higher scores than this number will also be downloaded. |
| tags | Nearly Anything | Tags which will be used to perform the post search. See above for restrictions |
Add any tags for posts you would like to avoid downloading to the blacklist section of the config.ini file. Meta tags :, negative tags -, operational tags ~, will potentially break the script, as they are currently not filtered out of the blacklist, so do not use them in this section. Wildcard tags * are supported in the blacklist, though it is easy for a misspelled wildcard to match an artist's name, for example, and the program will not give any errors.
The defaults section of the config.ini is the primary fallback for any missing lines in a search group. This section uses the same keys as search groups.
There is also a hard-coded secondary fallback if any lines are missing in the defaults section. They are as follows:
search_defaults:
days: 1
min_score: 0
min_fav_count: 0
allowed_ratings:
- s
Once you have added at least one group to the tags file, you should see something similar to this when you run e621dl:
[i] Running e621dl version 5.0.1.
[i] Getting config...
[i] Getting posts for search 'EXAMPLE'.
[i] Post xxxxxxx was already downloaded.
[✗] Post xxxxxxx was skipped for having a blacklisted tag.
[✗] Post xxxxxxx was skipped for having an unwanted rating.
[✗] Post xxxxxxx was skipped for having a low score.
[✗] Post xxxxxxx was skipped for having a low favorite count.
[✓] Post xxxxxxx is being downloaded.
[i] All searches complete.
Press Enter to continue...
It should be recognized that e621dl, as a script, can be scheduled to run as often as you like, keeping the your local collections always up-to-date, however, the methods for doing this are dependent on your platform, and are outside the scope of this quick-guide.
If you have any ideas on how to make this script run better, or for features you would like to see in the future, open an issue and I will try to read it as soon as possible.