Pywikibot

The Pywikibot framework is a Python library that interfaces with the MediaWiki API version 1.31 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 https://gerrit.wikimedia.org/r/pywikibot/core.git
cd core
git submodule update --init
pip install -r requirements.txt
python pwb.py <script_name>

Or to install using PyPI (excluding scripts)

pip install pywikibot
pwb <scriptname>

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')
page.save('Replacing "foo" with "bar"')  # Saves the page

Wikibase Usage

Wikibase is a flexible knowledge base software that drives Wikidata. A sample pywikibot script for getting data from Wikibase:

import pywikibot
site = pywikibot.Site('wikipedia:en')
repo = site.data_repository()  # the Wikibase repository for given site
page = repo.page_from_repository('Q91')  # create a local page for the given item
item = pywikibot.ItemPage(repo, 'Q91')  # a repository item
data = item.get()  # get all item data from repository for this item

Script example

Pywikibot provides bot classes to develop your own script easily:

import pywikibot
from pywikibot import pagegenerators
from pywikibot.bot import ExistingPageBot

class MyBot(ExistingPageBot):

    update_options = {
        'text': 'This is a test text',
        'summary': 'Bot: a bot test edit with Pywikibot.'
    }

    def treat_page(self):
        """Load the given page, do some changes, and save it."""
        text = self.current_page.text
        text += '\n' + self.opt.text
        self.put_current(text, summary=self.opt.summary)

def main(*args: str) -> None:
    """Parse command line arguments and invoke bot."""
    options = {}
    gen_factory = pagegenerators.GeneratorFactory()
    # Option parsing
    local_args = pywikibot.handle_args(args)  # global options
    local_args = gen_factory.handle_args(local_args)  # generators options
    for arg in local_args:
        opt, sep, value = arg.partition(':')
        if opt in ('-summary', '-text'):
            options[opt[1:]] = value
    MyBot(generator=gen_factory.getCombinedGenerator(), **options).run()

if __name__ == '__main__':
    main()

For more documentation on Pywikibot see our docs.

Roadmap

Release 11.10

Enable lexeme creation through LexemePage.editEntity(). See Creating Lexemesfor further information. (T442295)
Initialize LexemePagecollections for unsaved entities. (T442290)
Various performance, stability, and code quality improvements.
Serialize nested form and sense edits in page.SubEntityCollection

(T189321)
Add ignore_save_related_errors and ignore_server_errorsattributes to bot.BaseBotand use them in userPut(). (T156908)
Add support for Scribunto redirects. (T417129)
Serialize term removals and empty feature sets in page.LexemeSubEntity and LexemeForm. (T189321)
Reload page.WikibaseEntityentity state after successful saves. (T189321)
Preserve fields during data normalization in LexemePage and LexemeForm. (T189321)
Find headings followed by a multiline comment with textlib.get_regexes(‘header’) . (T209712)
Always set the comment of a page.Contribution. (T442114)
Keep sub-entity indexes of page.SubEntityCollection aligned after mutations. (T189321)
Replace recursive orchestration of site.Uploader. (T434936)
Fix APISite.interwiki_prefix() functionality. (T312699)
Normalize IPv6 addresses in user titles like MediaWiki within pywikibot.Link.parse. (T329819)
An IP range in CIDR notation is accepted as user in APISite.usercontribs() . (T362377)
The strict parameter was added to tools.is_ip_networkto ignore host bits if set to False.
Fix result of textlib.replaceCategoryLinkswithout category links.
Avoid mutating class attribute BaseBot.available_options with BaseBot.update_options. (T439883)
Update translations (i18n).
Reject nested wikilinks in file captions with textlib.FILE_LINK_REGEX. (T396721)
Speed up parsing of API ISO timestamps in Timestamp._from_iso8601() .

Deprecations

This section lists features, methods, parameters, or attributes that are deprecated and scheduled for removal in future Pywikibot releases.

Deprecated items may still work in the current release but are no longer recommended for use. Users should update their code according to the recommended alternatives.

Pywikibot follows a clear deprecation policy: features are typically deprecated in one release and removed in the third subsequent major release, remaining available for the two releases in between.

Pending removal in Pywikibot 12

9.6.0: BaseSite.languages()will be removed in favour of BaseSite.codes
9.5.0: DataSite.getPropertyType()will be removed in favour of DataSite.get_property_type()
9.3.0: page.BasePage.userNameand page.BasePage.isIpEditare deprecated in favour of user or anon attributes of page.BasePage.latest_revisionproperty
9.3.0: botflag parameter of Page.save(), Page.put() and Page.set_redirect_target()was renamed to bot
9.2.0: All parameters of Page.templatesand Page.itertemplates()must be given as keyworded arguments
9.2.0: Imports of loggingfunctions from the botmodule are deprecated and will be desupported
9.2.0: total argument in -logevents pagegenerators option is deprecated; use -limit instead (T128981)
9.0.0: The content parameter of proofreadpage.IndexPage.page_genis deprecated and will be ignored (T358635)
9.0.0: next parameter of userinterfaces.transliteration.Transliterator.transliteratewas renamed to succ
9.0.0: userinterfaces.transliteration.transliterator object was renamed to Transliterator
9.0.0: The type parameter of site.APISite.protectedpages() was renamed to protect_type
9.0.0: The all parameter of site.APISite.namespace() was renamed to all_ns
9.0.0: filter parameter of date.dhwas renamed to filter_func
9.0.0: dict parameter of data.api.OptionSetwas renamed to data
9.0.0: version.get_toolforge_hostnameis deprecated with no replacement
9.0.0: allrevisions parameter of xmlreader.XmlDumpis deprecated, use revisions instead (T340804)
9.0.0: iteritems method of data.api.Requestwill be removed in favour of items
9.0.0: SequenceOutputter.output() is deprecated in favour of the tools.formatter.SequenceOutputter.outproperty

Pending removal in Pywikibot 13

10.7.0: The old (type, value, traceback) signature in tools.collections.GeneratorWrapper.throwwill be removed in Pywikibot 13, or earlier if it is dropped from a future Python release. (T340641)
10.6.0: Family.isPublic()will be removed (T407049)
10.6.0: Family.interwiki_replacementsis deprecated; use Family.code_aliasesinstead.
Keyword argument for char parameter of Transliterator.transliterate and positional arguments for prev and succ parameters are deprecated.
10.6.0: Positional arguments of daemonize()are deprecated and must be given as keyword arguments.
10.5.0: Accessing the fallback ‘*’ keys in ‘languages’, ‘namespaces’, ‘namespacealiases’, and ‘skins’ properties of APISite.siteinfoare deprecated and will be removed.
10.5.0: The methods APISite.protection_types() and APISite.protection_levels() are deprecated. APISite.restrictionsshould be used instead.
10.4.0: Require all parameters of Site.allpages() except start to be keyword arguments.
10.4.0: Positional arguments of pywikibot.Coordinateare deprecated and must be given as keyword arguments.
10.3.0: throttle.Throttle.getDelayand throttle.Throttle.setDelayswere renamed to get_delay()and set_delays() ; the old methods will be removed (T289318)
10.3.0: throttle.Throttle.next_multiplicityattribute is unused and will be removed (T289318)
10.3.0: requestsize parameter of throttle.Throttlecall is deprecated and will be dropped (T289318)
10.3.0: textlib.to_latin_digitswill be removed in favour of textlib.to_ascii_digits, NON_LATIN_DIGITS of userinterfaces.transliteration will be removed in favour of NON_ASCII_DIGITS (T398146#10958283)
10.2.0: tools.threading.RLockis deprecated and moved to backports module. The backports.RLock.countmethod is also deprecated. For Python 3.14+ use RLock from Python library threading instead. (T395182)
10.1.0: revid and date parameters of Page.authorship() were dropped
10.0.0: last_id of comms.eventstreams.EventStreamswas renamed to last_event_id (T309380)
10.0.0: ‘millenia’ argument for precision parameter of pywikibot.WbTimeis deprecated; ‘millennium’ must be used instead
10.0.0: includeredirects parameter of pagegenerators.AllpagesPageGeneratorand pagegenerators.PrefixingPageGeneratoris deprecated and should be replaced by filterredir

Pending removal in Pywikibot 14

11.9.0: The force parameter of pywikibot.Usermethods was renamed to refresh. The old parameter name will be removed. (T433225)
11.8.0: The config.maxlag setting was renamed to write_maxlag . The old setting variable will be dropped. (T421642)
11.8.0: Public reason and comment parameters used for page-action and upload summaries were renamed to summary. The old parameter names will be removed. (T62442)
11.7.0: page.BasePage.getOldVersionis now deprecated in favour of get_revision(oldid, content=True).text. (T433799)
11.7.0: The lang parameter of the i18n.altlangfunction is positional-only. Passing lang as a keyword argument is deprecated.
11.7.0: The interface of APISite.assert_valid_iter_params() was changed. The msg_prefix parameter is now positional-only and the is_ts parameter is now keyword-only. The previous interface is deprecated.
11.6.0: The top_only parameter of APISite.usercontribs has been deprecated; use top instead (T308961)
11.5.0: family.Family.post_get_convertand family.Family.pre_put_convertfunctions are deprecated and will be removed (T431188)
11.5.0: exceptions.TimeoutError is deprecated in favour of exceptions.ApiTimeoutError
11.5.0: config``textfile_encoding`` variable will be removed; use ‘utf-8’ directly instead (T430454)
11.4.0: The signature of APISite.allusers() was changed; all parameters are keyword-only.
11.4.0: The signature of tools.open_archivewas changed. filename parameter is positional only, use_extension is keyword only.
11.0.0: The User-Agent variable script_product is deprecated; use script instead. The User-Agent variable version is deprecated; use revision instead. The User-Agent variables lang, code and family are deprecated; use site instead.
11.0.0: Positional argument for block parameter of pywikibot.async_manageris deprecated; use a keyword argument instead.
11.0.0: Keyword parameters for text_a and text_b of diff.PatchManagerare deprecated. Positional parameters for by_letter and replace_invisible are deprecated.

Release history

See https://doc.wikimedia.org/pywikibot/stable/changelog.html

Contributing

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 MediaWiki Code of Conduct.

Metadata

Release files for pywikibot 11.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pywikibot 11.10.0
File	Size	Uploaded	Provenance	Actions
pywikibot-11.10.0.tar.gz	669.7 kB	Oct 31, 2026	Without provenance	Details for pywikibot-11.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pywikibot 11.10.0
File	Interpreter	ABI	Platform	Actions Reset
pywikibot-11.10.0-py3-none-any.whl 774.2 kB Oct 31, 2026 Without provenance	Python 3	none	any	Details for pywikibot-11.10.0-py3-none-any.whl

Total release size: 1.4 MB

Release files / pywikibot-11.10.0.tar.gz

Download URL	pywikibot-11.10.0.tar.gz
Size	669.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`5e77626feddf570006f2ced015b81dfe08cea714d84818b16ab03281b45dec1b`
BLAKE2b-256 checksum How to use checksums	`ff97ab2df0af54fbbc3bf1cddc1735af438d85e830a5a32909ee001d3090bc66`
Upload date	Oct 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`

Release files / pywikibot-11.10.0-py3-none-any.whl

Download URL	pywikibot-11.10.0-py3-none-any.whl
Size	774.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2b88a0234fe53c16b796015b3de5cc67a8b53e4ab155cc2fe1fb4136b35fcfc0`
BLAKE2b-256 checksum How to use checksums	`f85227b111d0b643a49d4eaf16fa0dafdd5edf4514715728c21c71cdb89acc2a`
Upload date	Oct 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`

Security for pywikibot 11.10.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

11.10.0 This release

Oct 31, 2026 2 release files No provenance

pywikibot 11.10.0