Utility 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.py settings file 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 the script name is missspelled. In directory mode it also checks package dependencies.

Run scripts with pywikibot in directory mode using:

python pwb.py <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 pwb.py -lang:de bot_tests -v

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


Convert path to absolute path, with uppercase drive letter on win32.


Check whether mandatory modules are present.

This also checks Python version when importing deptendencies from setup.py


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


True if all dependencies are installed

Return type



RuntimeError – wrong Python version found in setup.py


Validate package version and scripts version.

  • Pywikibot version must not be older than scrips version

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


Parse arguments, extract filename and run the script.

New in version 7.0: renamed from main()

pwb.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

pwb.handle_args(pwb_py, *args)[source]

Handle args and get filename.


filename, script args, local args for pwb.py

Return type



Script entry point. Print doc if necessary.

Changed in version 7.0: previous implementation was renamed to execute()


Site package entry point. Print doc if necessary.

New in version 7.0.

pwb.run_python_file(filename, args, package=None)[source]

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

  • 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 generate_family_file.py [<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 "_family.py" tail.
<dointerwiki>: predefined answer (y|n) to add multiple site codes
<verify>:      disable certificate validaton `(y|n)


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

This will create the file mywiki_family.py 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.

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

Bases: object

Family file creator object.

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

  • url – an url from where the family settings are loaded

  • name – the family name without “_family.py” tail.

  • dointerwiki – Predefined answer to add multiple site codes. Pass Y or y for yes N or n for no and E or e if you want to edit the collection of sites.

  • verify – 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.


Get wiki from base_url.


Load other site pages.


Determine site code of a family.


Main method, generate family file.


Write the family file.


Process command line arguments and generate a family file.

generate_user_files script

Script to create user-config.py.

Changed in version 7.0: moved to pywikibot.scripts folder


Ask whether the base directory is has to be changed.

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


force (bool) – Skip asking for directory change


whether user file or password file exists already

Return type

tuple of bool


Create a new user directory.


Take config sections and copy them to user-config.py.


config text of all selected sections.

Return type


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

Create a user-config.py in base_dir.

Create a user-password.py if necessary.


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

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

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

  • default_family – The default family which should be chosen.

  • default_lang – The default site code which should be chosen, if the family supports it.

  • default_username – The default username which should be chosen.


The family, site code and username

Return type

tuple of three str

pywikibot.scripts.generate_user_files.main(*args: str)[source]

Process command line arguments and generate user-config.

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


args – command line arguments

pywikibot.scripts.generate_user_files.parse_sections() list[source]

Parse sections from config.py file.

config.py will be in the pywikibot/ directory whereas generate_user_files script is in pywikibot/scripts.


a list of ConfigSection named tuples.

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

Write botpasswords to file.

shell script

Spawns an interactive Python shell and imports the pywikibot library.

The following local option is supported:

-noimport Do not import the pywikibot library. All other arguments are

ignored in this case.


python pwb.py shell [args]

If no arguments are given, the pywikibot library will not be loaded.

Changed in version 7.0: moved to pywikibot.scripts

pywikibot.scripts.shell.main(*args: str) None[source]

Script entry point.

version script

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

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

class pywikibot.scripts.version.DummyModule[source]

Bases: object

Fake module instance.

pywikibot.scripts.version.main(*args: str) None[source]

Print pywikibot version and important settings.