Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Python MediaWiki Bot Framework

Project description

Travis Build Status AppVeyor Build Status Code coverage Maintainability Python Pywikibot release


The Pywikibot framework is a Python library that interfaces with the MediaWiki API version 1.14 or higher.

Also included are various general function scripts that can be adapted for different tasks.

For further information about the library excluding scripts see the full code documentation.

Quick start

git clone
cd core
git submodule update --init
python script_name

Or to install using PyPI (excluding scripts)

pip install -U setuptools
pip install pywikibot

Our installation guide has more details for advanced usage.

Basic Usage

If you wish to write your own script it’s very easy to get started:

import pywikibot
site = pywikibot.Site('en', 'wikipedia')  # The site we want to run our bot on
page = pywikibot.Page(site, 'Wikipedia:Sandbox')
page.text = page.text.replace('foo', 'bar')'Replacing "foo" with "bar"')  # Saves the page

For more documentation on pywikibot see our docs.

The contents of the package

pywikibot Library routines, control files and global settings
pywikibot/comms Communication layer
pywikibot/compat Package to provide compatibility with compat scripts
pywikibot/data Module with several layers for data access to wiki
pywikibot/families wiki-specific information and settings
pywikibot/tools Miscellaneous helper functions (not wiki-dependent)
pywikibot/userinterfaces GUI and terminal interface

Required external programs

It may require the following programs to function properly:

  • 7za: To extract 7z files

Release history

Current release

  • Increase the throttling delay if maxlag >> retry-after (T210606)
  • deprecate test_family: Site(‘test’, ‘test’), use wikipedia_family: Site(‘test’, ‘wikipedia’) instead (T228375, T228300)
  • Add “user_agent_description” option in
  • APISite.fromDBName works for all known dbnames (T225590, 225723, 226960)
  • remove the unimplemented “proxy” variable in
  • Make Family.langs property more robust (T226934)
  • Remove strategy family
  • Handle closed_wikis as read-only (T74674)
  • TokenWallet: login automatically
  • Add closed_wikis to Family.langs property (T225413)
  • Redirect ‘mo’ site code to ‘ro’ and remove interwiki_replacement_overrides (T225417, T89451)
  • Add support for badges on Wikibase item sitelinks (T128202)
  • Remove login.showCaptchaWindow() method
  • New parameter supplied in suggest_help function for missing dependencies
  • Remove NonMWAPISite class
  • Introduce Claim.copy and prevent adding already saved claims (T220131)
  • Fix create_short_link method after MediaWiki changes (T223865)
  • Validate proofreadpage.IndexPage contents before saving it
  • Refactor Link and introduce BaseLink (T66457)
  • Count skipped pages in BaseBot class
  • ‘actionthrottledtext’ is a retryable wikibase error (T192912)
  • Clear tokens on logout(T222508)
  • Deprecation warning: support for Python 2 will be dropped (T213287)
  • botirc.IRCBot has been dropped
  • Avoid using outdated browseragents (T222959)
  • textlib: avoid infinite execution of regex (T222671)
  • Add CSRF token in sitelogout() api call (T222508)
  • Refactor WikibasePage.get and overriding methods and improve documentation
  • Improve title patterns of WikibasePage extensions
  • Add support for property creation (T160402)
  • Bugfixes and improvements
  • Localisation updates


  • Don’t fail if the number of forms of a plural string is less than required (T99057, T219097)
  • Implement create_short_link Page method to use Extension:UrlShortener (T220876)
  • Remove wikia family file (T220921)
  • Remove deprecated
  • Changed requirements for sseclient (T219024)
  • Set optional parameter namespace to None in site.logpages (T217664)
  • Add ability to display similar scripts when misspelled (T217195)
  • Check if QueryGenerator supports namespaces (T198452)
  • Bugfixes and improvements
  • Localisation updates


  • Fix version comparison (T164163)
  • Remove pre MediaWiki 1.14 code
  • Dropped support for Python 2.7.2 and 2.7.3 (T191192)
  • Fix header regex beginning with a comment (T209712)
  • Implement Claim.__eq__ (T76615)
  • cleanup
  • Add missing Wikibase API write actions
  • Bugfixes and improvements
  • Localisation updates


  • Support python version 3.7
  • add -querypage parameter to yield pages provided by any special page (T214234)
  • Fix comparison of str, bytes and int literal
  • add generic self.querypage() to query SpecialPages
  • echo.Notification has a new event_id property as integer
  • Bugfixes and improvements
  • Localisation updates


  • Ensure “modules” parameter of ParamInfo._fetch is a set (T122763)
  • Support adding new claims with qualifiers and/or references (T112577, T170432)
  • Support LZMA and XZ compression formats
  • Update correct-ar Typo corrections in (T211492)
  • Enable MediaWiki timestamp with EventStreams (T212133)
  • Convert Timestamp.fromtimestampformat() if year, month and day are given only
  • tools.concat_options is deprecated
  • Additional ListOption subclasses ShowingListOption, MultipleChoiceList, ShowingMultipleChoiceList
  • Bugfixes and improvements
  • Localisation updates


  • Remove compat module references from autogenerated docs (T183085)
  • site.preloadpages: split pagelist in most max_ids elements (T209111)
  • Disable empty sections in cosmetic_changes for user namespace
  • Prevent touch from re-creating pages (T193833)
  • New Page.title() parameter without_brackets; also used by titletranslate (T200399)
  • Security: require requests version 2.20.0 or later (T208296)
  • Check appropriate key in Site.messages (T163661)
  • Make sure the cookie file is created with the right permissions (T206387)
  • pydot >= 1.2 is required for interwiki_graph
  • Move methods for simple claim adding/removing to WikibasePage (T113131)
  • Enable start timestamp for EventStreams (T205121)
  • Re-enable notifications (T205184)
  • Use FutureWarning for warnings intended for end users (T191192)
  • Provide new -wanted… page generators (T56557, T150222)
  • api.QueryGenerator: Handle slots during initialization (T200955, T205210)
  • Bugfixes and improvements
  • Localisation updates


  • Enable multiple streams for EventStreams (T205114)
  • Fix Wikibase aliases handling (T194512)
  • Remove cryptography support from python<=2.7.6 requirements (T203435)
  • textlib._tag_pattern: Do not mistake self-closing tags with start tag (T203568)
  • page.Link.langlinkUnsafe: Always set _namespace to a Namespace object (T203491)
  • Enable Namespace.content for mw < 1.16
  • Allow terminating the bot generator by BaseBot.stop() method (T198801)
  • Allow bot parameter in set_redirect_target
  • Do not show empty error messages (T203462)
  • Show the exception message in async mode (T203448)
  • Fix the extended user-config extraction regex (T145371)
  • Solve UnicodeDecodeError in site.getredirtarget (T126192)
  • Introduce a new APISite property: mw_version
  • Improve hash method for BasePage and Link
  • Avoid applying two uniquifying filters (T199615)
  • Fix skipping of language links in CosmeticChangesToolkit.removeEmptySections (T202629)
  • New mediawiki projects were provided
  • Bugfixes and improvements
  • Localisation updates


  • Don’t reset Bot._site to None if we have already a site object (T125046)
  • Fix the bug in cache_time when loading a CachedRequest (T202227)
  • pagegenerators._handle_recentchanges: Do not request for reversed results (T199199)
  • Use a key for filter_unique where appropriate (T199615)
  • Add exceptions for first_upper (T200357)
  • Fix usages of site.namespaces.NAMESPACE_NAME (T201969)
  • pywikibot/ Fix header regex to allow comments
  • Use ‘rvslots’ when fetching revisions on MW 1.32+ (T200955)
  • Drop the ‘2’ from PYWIKIBOT2_DIR, PYWIKIBOT2_DIR_PWB, and PYWIKIBOT2_NO_USER_CONFIG environment variables. The old names are now deprecated. The other PYWIKIBOT2_* variables which were used only for testing purposes have been renamed without deprecation. (T184674)
  • Introduce a timestamp in deprecated decorator (T106121)
  • textlib.extract_sections: Remove footer from the last section (T199751)
  • Don’t let WikidataBot crash on save related errors (T199642)
  • Allow different projects to have different L10N entries (T198889)
  • remove color highlights before fill function (T196874)
  • Fix Portuguese file namespace translation in cc (T57242)
  • textlib._create_default_regexes: Avoid using inline flags (T195538)
  • Not everything after a language link is footer (T199539)
  • code cleanups
  • New mediawiki projects were provided
  • Bugfixes and improvements
  • Localisation updates


  • Enable any LogEntry subclass for each logevent type (T199013)
  • Deprecated pagegenerators options -<logtype>log aren’t supported any longer (T199013)
  • Open RotatingFileHandler with utf-8 encoding (T188231)
  • Fix occasional failure of TestLogentries due to hidden namespace (T197506)
  • Remove multiple empty sections at once in cosmetic_changes (T196324)
  • Fix stub template position by putting it above interwiki comment (T57034)
  • Fix handling of API continuation in PropertyGenerator (T196876)
  • Use PyMySql as pure-Python MySQL client library instead of oursql, deprecate MySQLdb (T89976, T142021)
  • Ensure that BaseBot.treat is always processing a Page object (T196562, T196813)
  • Update global bot settings
  • New mediawiki projects were provided
  • Bugfixes and improvements
  • Localisation updates


  • Move main categories to top in cosmetic_changes
  • always imports pywikibot as default
  • New roundrobin_generators in tools
  • New BaseBot method “skip_page” to adjust page counting
  • Family class is made a singleton class
  • New rule ‘startcolon’ was introduced in textlib
  • BaseBot has new methods setup and teardown
  • UploadBot got a filename prefix parameter (T170123)
  • cosmetic_changes is able to remove empty sections (T140570)
  • Pywikibot is following PEP 396 versioning
  • pagegenerators AllpagesPageGenerator, CombinedPageGenerator, UnconnectedPageGenerator are deprecated
  • Some DayPageGenerator parameters has been renamed
  • unicodedata2, httpbin and Flask dependency was removed (T102461, T108068, T178864, T193383)
  • New projects were provided
  • Bugfixes and improvements
  • Documentation updates
  • Localisation updates (T194893)
  • Translation updates


  • Enable makepath and datafilepath not to create the directory
  • Use API’s retry-after value (T144023)
  • Provide startprefix parameter for Category.articles() (T74101, T143120)
  • Page.put_async() is marked as deprecated (T193494)
  • pagegenerators.RepeatingGenerator is marked as deprecated (T192229)
  • Deprecate requests-requirements.txt (T193476)
  • Bugfixes and improvements
  • New mediawiki projects were provided
  • Localisation updates


  • Deprecation warning: support for Python 2.7.2 and 2.7.3 will be dropped (T191192)
  • Dropped support for Python 2.6 (T154771)
  • Dropped support for Python 3.3 (T184508)
  • Bugfixes and improvements
  • Localisation updates


  • Bugfixes and improvements
  • Localisation updates


  • Changed requirements for requests and sseclient
  • Bugfixes and improvements
  • Localisation updates


  • Deprecation warning: support for py2.6 and py3.3 will be dropped
  • Changed requirements for cryprography, Pillow and pyOpenSSL
  • Bugfixes and improvements
  • Localisation updates


  • Maintenance script to download Wikimedia database dump
  • Option to auto-create accounts when logging in
  • Ship wikimania family file
  • Drop battlestarwiki family file
  • Bugfixes and improvements
  • Localisation updates


  • Introduce userscripts directory
  • Generator settings inside (user-)
  • BaseUnlinkBot has become part of the framework in
  • Decommission of rcstream
  • Script files added to
  • Other documentation updates
  • Bugfixes and improvements
  • Localisation updates


  • Bugfixes and improvements
  • Localisation updates


  • Implement server side event client EventStreams
  • Add thanks log support
  • new script to create hyphenated redirects
  • new script to flag new articles
  • new WbUnknown data type for Wikibase
  • Deprecate APISite.newfiles()
  • new pagegenerators filter option -titleregexnot
  • Inverse of pagegenerators -namespace option
  • Bugfixes and improvements
  • Localisation updates
  • Remove script
  • Remove anarchopedia family out of the framework
  • CODE_OF_CONDUCT included


  • Replaced the word ‘async’ with ‘asynchronous’ due to python 3.7
  • Support for Python 2.6 but higher releases are strictly recommended
  • Bugfixes and improvements
  • Localisation updates


  • First major release from master branch
  • requests package is mandatory
  • Deprecate previous 2.0 branches


  • Last stable 2.0 branch


  • Remove dependency on pYsearch
  • Desupport Python 2.6 for Pywikibot 2.0 release branch


  • Bugfixes
  • Localisation updates
  • i18n: always follow master branch


  • Bugfixes and improvements
  • Localisation updates


  • New scripts and ported from old compat branch
  • now supports wikibase
  • RecentChanges stream (rcstream) support
  • Sphinx documentation at
  • Bugfixes and improvements
  • Localisation updates


  • Bugfixes and improvements


  • Bugfixes and improvements


  • First stable release branch

1.0 rv 2007-06-19

  • BeautifulSoup becomes mandatory
  • new scripts were added
  • new family files were supported
  • some scripts were archived


Sep 26, 2005

  • First PyWikipediaBot framework release
  • scripts and libraries for standardizing content
  • tools for making minor modifications
  • script making interwiki links


Our code is maintained on Wikimedia’s Gerrit installation, learn how to get started.

Code of Conduct

The development of this software is covered by a Code of Conduct.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pywikibot, version 3.0.20190722
Filename, size File type Python version Upload date Hashes
Filename, size pywikibot-3.0.20190722.tar.gz (520.4 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page