NOTE: All references to whitelist/blacklist are deprecated, and will be replaced with allowlist/blocklist in 5.0
The mirror filter configuration settings are in the same configuration file as the mirror settings. There are different configuration sections for the different plugin types.
Filtering Plugin package lists need to use the Raw PyPI Name (non PEP503 normalized) in order to get filtered.
E.g. to Blocklist ACMPlus you’d need to
use that exact casing in
A PR would be welcome fixing the normalization but it’s an invasive PR
The plugins setting is a list of plugins to enable.
Example (enable all installed filter plugins):
Explicitly enabling plugins is now mandatory for activating plugins
They will do nothing without activation
Also, enabling will get plugin’s defaults if not configured in their respective sections.
[plugins] enabled = all
Example (only enable specific plugins):
[plugins] enabled = allowlist_project blocklist_project ...
allowlist / blocklist filtering settings¶
The blocklist / allowlist settings are in configuration sections named [blocklist] and [allowlist] these section provides settings to indicate packages, projects and releases that should / should not be mirrored from PyPI.
This is useful to avoid syncing broken or malicious packages.
The packages setting is a list of python pep440 version specifier of packages to not be mirrored. Enable version specifier filtering for blocklist and allowlist packages through enabling the ‘blocklist_release’ and ‘allowlist_release’ plugins, respectively.
Any packages matching the version specifier for blocklist packages will not be downloaded. Any packages not matching the version specifier for allowlist packages will not be downloaded.
[plugins] enabled = blocklist_project blocklist_release allowlist_project allowlist_release [blocklist] packages = example1 example2>=1.4.2,<1.9,!=1.5.*,!=1.6.* [allowlist] packages = black==18.5 ptr
Packages and release files may be selected by filtering on specific metadata value.
General form of configuration entries is:
[filter_some_metadata] tag:tag:path.to.object = matcha matchb
requirements files Filtering¶
Packages and releases might be given as requirements.txt files
if requirements_path is missing it is assumed to be system root folder (‘/’)
[plugins] enabled = project_requirements project_requirements_pinned [allowlist] requirements_path = /my_folder requirements = requirements.txt
Project Regex Matching¶
Filter projects to be synced based on regex matches against their raw metadata entries straight from parsed downloaded json.
[regex_project_metadata] not-null:info.classifiers = .*Programming Language :: Python :: 2.*
Valid tags are
not-null, with default of
All metadata provided by json is available, including
releases, etc. headings.
Release File Regex Matching¶
Filter release files to be downloaded for projects based on regex matches against the stored metadata entries for each release file.
[regex_release_file_metadata] any:release_file.packagetype = sdist bdist_wheel
Valid tags are the same as for projects.
Metadata available to match consists of
release_file top level structures, with
containing the package-wide inthe fo,
release containing the version of the release and
release_file the metadata
for an individual file for that release.
Bandersnatch includes a plugin to filter our pre-releases of packages. To enable this plugin simply add
prerelease_release to the enabled plugins list.
[plugins] enabled = prerelease_release
Advanced users who would like finer control over which packages and releases to filter can use the regex Bandersnatch plugin.
This plugin allows arbitrary regular expressions to be defined in the configuration, any package name or release version that matches will not be downloaded.
The plugin can be activated for packages and releases separately. For example to activate the project regex filter simply add it to the configuration as before:
[plugins] enabled = regex_project
If you’d like to filter releases using the regex filter use
The regex plugin requires an extra section in the config to define the actual patterns to used for filtering:
[filter_regex] packages = .+-evil$ releases = .+alpha\d$
Note the same
filter_regex section may include a
packages and a
releases entry with any number of regular expressions.
Platform-specific binaries filtering¶
This filter allows advanced users not interesting in Windows/macOS/Linux specific binaries to not mirror the corresponding files.
[plugins] enabled = exclude_platform [blocklist] platforms = windows
Available platforms are:
Keep only latest releases¶
You can also keep only the latest releases based on greatest Version numbers.
[plugins] enabled = latest_release [latest_release] keep = 3
By default, the plugin does not filter out any release. You have to add the
You should be aware that it can break requirements. Prereleases are also kept.