Framework utility scripts reference#

Folder which holds framework scripts.

When uploading pywikibot to pypi the (wrapper script) and pywikibot i18n package are copied here.

Added in version 7.0.


Return __import__(*import_args) without loading user config.

Added in version 3.0.

Changed in version 7.0: moved to pywikibot.scripts

pwb wrapper script#

Wrapper script to invoke pywikibot-based scripts.

This wrapper script invokes script by its name in this search order:

  1. Scripts listed in user_script_paths list inside your user config settings file (usually in the given order. Refer External Script Path Settings.

  2. User scripts residing in scripts/userscripts (directory mode only).

  3. Scripts residing in scripts folder (directory mode only).

  4. Maintenance scripts residing in scripts/maintenance (directory mode only).

  5. Framework scripts residing in pywikibot/scripts.

This wrapper script is able to invoke scripts even if the script name is misspelled. In directory mode it also checks package dependencies.

Run scripts with pywikibot in directory mode using:

python <pwb options> <name_of_script> <options>

or run scripts with pywikibot installed as a site package using:

pwb <pwb options> <name_of_script> <options>

This wrapper script uses the package directory to store all user files, will fix up search paths so the package does not need to be installed, etc.

Currently, <pwb options> are Global options. This can be used for tests to set the default site (see T216825):

python -lang:de bot_tests -v

See also

pwb entry point

Changed in version 7.0: pwb wrapper was added to the Python site package lib.

Changed in version 7.7: pwb wrapper is able to set PYWIKIBOT_TEST_... environment variables, see Environment variables.

Changed in version 8.0: renamed to


Check whether mandatory modules are present.

This also checks Python version when importing dependencies from


script (str | None) – The script name to be checked for dependencies


True if all dependencies are installed


RuntimeError – wrong Python version found in

Return type:



Validate package version and scripts version.

  • Pywikibot version must not be older than scrips version

  • Scripts version must not be older than previous Pywikibot version due to deprecation policy


package (str)


Parse arguments, extract filename and run the script.

Added in version 7.0: renamed from main()

pywikibot.scripts.wrapper.find_alternates(filename, script_paths)[source]#

Search for similar filenames in the given script paths.


Search for the filename in the given script paths.

Changed in version 7.0: Search users_scripts_paths in config.base_dir

Changed in version 9.0: Add config.base_dir to search path

pywikibot.scripts.wrapper.handle_args(_, *args)[source]#

Handle args and get filename.

Changed in version 7.7: Catch PYWIKIBOT_TEST_... environment variables.


filename, script args, local pwb args, environment variables


args (str)

Return type:

tuple[str, list[str], list[str], list[str]]


Script entry point. Print doc if necessary.

Changed in version 7.0: previous implementation was renamed to execute()[source]#

Site package entry point. Print doc if necessary.

Added in version 7.0.

pywikibot.scripts.wrapper.run_python_file(filename, args, package=None)[source]#

Run a python file as if it were the main program on the command line.

Changed in version 7.7: Set and restore PYWIKIBOT_TEST_... environment variables.

  • filename (str) – The path to the file to execute, it need not be a .py file.

  • args (list[str]) – is the argument list to present as sys.argv, as strings.

  • package (Optional[module]) – The package of the script. Used for checks.

generate_family_file script#

This script generates a family file from a given URL.

This script must be invoked with the pwb wrapper script/code entry point.


pwb [<url>] [<name>] [<dointerwiki>] [<verify>]

Parameters are optional. They must be given consecutively but may be omitted if there is no successor parameter. The parameters are:

<url>:         an url from where the family settings are loaded
<name>:        the family name without "" tail.
<dointerwiki>: predefined answer (y|s|n) to add multiple site codes
<verify>:      disable certificate validaton `(y|n)


pwb https://www.mywiki.bogus/wiki/Main_Page mywiki

This will create the file in families folder of your base directory.

Changed in version 7.0: moved to pywikibot.scripts folder; create family files in families folder of your base directory instead of pywikibot/families.

Changed in version 8.1: [s]trict can be given for <dointerwiki> parameter to ensure that sites are from the given domain.

Changed in version 8.4: If the url scheme is missing, https will be used.

class pywikibot.scripts.generate_family_file.FamilyFileGenerator(url=None, name=None, dointerwiki=None, verify=None)[source]#

Bases: object

Family file creator object.

Parameters are optional. If not given the script asks for the values.

  • url (str | None) – an url from where the family settings are loaded

  • name (str | None) – the family name without “” tail.

  • dointerwiki (str | None) – Predefined answer to add multiple site codes. Pass Y or y for yes, S or s for strict which only includes site of the same domain (usually for Wikimedia sites), N or n for no and E or e if you want to edit the collection of sites.

  • verify (str | None) – If a certificate verification failes, you may pass Y or y to disable certificate validaton N or n to keep it enabled.


Ask for parameters if necessary.

Return type:



Get wiki from base_url.


Load other site pages.

Return type:



Determine site code of a family.

Changed in version 8.1: with [e]dit the interwiki list can be given delimited by space or comma or both. With [s]trict only sites with the same domain are collected. A [h]elp answer was added to show more information about possible answers.

Return type:



Main method, generate family file.

Return type:



Write the family file.

Return type:



Process command line arguments and generate a family file.

Return type:


generate_user_files script#

Script to create Other file names are not supported.

Changed in version 7.0: moved to pywikibot.scripts folder.

Changed in version 8.0: let user the choice which section to be copied. Also EXTERNAL EDITOR SETTINGS section can be copied.


Ask whether the base directory is has to be changed.

Only give option for directory change if or user-password already exists in the directory. This will repeat if also exists in the requested directory.


force (bool) – Skip asking for directory change


whether user file or password file exists already

Return type:

tuple[bool, bool]


Create a new user directory.

pywikibot.scripts.generate_user_files.copy_sections(force=False, default='n')[source]#

Take config sections and copy them to

Changed in version 8.0: force and default options were added.

  • force (bool) – Copy all sections if force is True

  • default (str) – Default answer for input_sections. Should be ‘a’ for all or ‘n’ for none to copy.


config text of all selected sections.

Return type:

str | None

pywikibot.scripts.generate_user_files.create_user_config(main_family, main_code, main_username, force=False)[source]#

Create a in base_dir.

Create a if necessary.

  • main_family (str)

  • main_code (str)

  • main_username (str)

  • force (bool)


Return whether the file exists and print a message if it exists.

Return type:


pywikibot.scripts.generate_user_files.get_site_and_lang(default_family='wikipedia', default_lang='en', default_username=None, force=False)[source]#

Ask the user for the family, site code and username.

  • default_family (str | None) – The default family which should be chosen.

  • default_lang (str | None) – The default site code which should be chosen, if the family supports it.

  • default_username (str | None) – The default username which should be chosen.

  • force (bool)


The family, site code and username

Return type:

tuple[str, str, str]

pywikibot.scripts.generate_user_files.input_sections(variant, sections, skip=None, force=False, default='n')[source]#

Ask for settings to copy.

Added in version 8.0.

  • variant (str) – Variant of the setting section. Either ‘framework’ or ‘scripts’

  • sections (list[_ConfigSection]) – A sections list previously read from the config file

  • skip (Callable | None) – a filter function

  • force (bool) – Force input if True

  • default (str)

Return type:



Process command line arguments and generate user-config.

If args is an empty list, sys.argv is used.


args (str) – command line arguments

Return type:



Parse sections from file. will be in the pywikibot/ directory whereas generate_user_files script is in pywikibot/scripts.


a list of _ConfigSection named tuples.

Return type:


pywikibot.scripts.generate_user_files.save_botpasswords(botpasswords, _fncpass)[source]#

Write botpasswords to file.

login script#

Script to log the bot in to a wiki account.

Suggestion is to make a special account to use for bot use only. Make sure this bot account is well known on your home wiki before using.

The following parameters are supported:

-family:FF   Log in to the LL language of the FF family.
-lang:LL     Example: -family:wiktionary -lang:fr will log you in at

-site:FF:LL  Log in to the LL language of the FF family

-all         Try to log in on all sites where a username is defined in
             user config file (

-logout      Log out of the current site. Combine with -all to log out of
             all sites, or with -family and -lang to log out of a specific

-oauth       Generate OAuth authentication information.

             .. note:: Need to copy OAuth tokens to your user config
                file manually. -logout is not compatible with -oauth.

-autocreate  Auto-create an account using unified login when necessary.

             .. note:: the global account must exist already before
                using this.

-async       Run the bot in parallel tasks

If not given as parameter, the script will ask for your username and password (password entry will be hidden), log in to your home wiki using this combination, and store the resulting cookies (containing your password hash, so keep it secured!) in a file in the data subdirectory.

All scripts in this library will be looking for this cookie file and will use the login information if it is present.

To log out, throw away the *.lwp file that is created in the data subdirectory.

Changed in version 7.4: moved to pywikibot.scripts folder

pywikibot.scripts.login.login_one_site(code, family, oauth, logout, autocreate)[source]#

Login on one site.


Process command line arguments and invoke bot.

If args is an empty list, sys.argv is used.


args (str) – command line arguments

Return type:


preload_sites script#

Script that preloads site and user info for all sites of given family.

The following parameters are supported:

-worker:<num> The number of parallel tasks to be run. Default is the

number of processors on the machine


python preload_sites [{<family>}] [-worker:{<num>}]

To force preloading, change the global expiry values to 0:

python -API_config_expiry:0 -API_uinfo_expiry:0 preload_sites [{<family>}]

or run the cache script previeously:

python cache -delete

Changed in version 7.4: script was moved to the framework scripts folder.

pywikibot.scripts.preload_sites.families_list = ['wikibooks', 'wikinews', 'wikipedia', 'wikiquote', 'wikisource', 'wikiversity', 'wikivoyage', 'wiktionary']#

supported families by this script

pywikibot.scripts.preload_sites.preload_families(families, worker)[source]#

Preload all sites of all given family files.

Changed in version 7.3: Default of worker is calculated like for Python 3.8 but preserves at least one worker for each element in families_list for better performance.

  • families (list[str] | set[str])

  • worker (int | None)

Return type:


pywikibot.scripts.preload_sites.preload_family(family, executor)[source]#

Preload all sites of a single family file.

Changed in version 9.2: use a separate worker thread for each site.

  • family (str)

  • executor (ThreadPoolExecutor)

Return type:


shell script#

Spawns an interactive Python shell and imports the pywikibot library.

To exit the shell, type ctrl-D (Linux) or ctrl-Z (Windows) or use the exit() function.

The following local option is supported:

-noimport Do not import the pywikibot library. All other arguments are
          ignored in this case.


python shell [args]

Changed in version 7.0: moved to pywikibot.scripts*args)[source]#

Script entry point.

Changed in version 8.2: exitmsg was added for code.interact().


args (str)

Return type:


version script#

Script to determine the Pywikibot version (tag, revision and date).

The following option is supported:


do not print usernames; otherwise they are printed for each registered family

Changed in version 7.0: version script was moved to the framework scripts folder

Added in version 9.1.2: the -nouser option.

class pywikibot.scripts.version.DummyModule[source]#

Bases: object

Fake module instance.


Print pywikibot version and important settings.

Changed in version 9.1.2: usernames are not printed with -nouser option.


args (str)

Return type: