pwb-wrapper-for-simpler-uploading-to-commons 1.7.0

CLI wrapper around Pywikibot for simpler Wikimedia Commons uploads

It is a wrapper around pywikibot to make uploading to Wikimedia Commons from CLI simpler.

Install

From PyPI:

pip install pwb-wrapper-for-simpler-uploading-to-commons

With shell autocompletion support:

pip install 'pwb-wrapper-for-simpler-uploading-to-commons[autocomplete]'

Usage

Installed CLI command:

pwb-upload --file my.jpg --source https://example.com --license 'PD-old' --category 'Sunsets in Batumi' --date '2025-12-27' --desc 'A beautiful sunset from the beach' --target myrenamed.jpg

For multiple categories, repeat --category:

pwb-upload --file my.jpg --category 'Sunsets in Batumi' --category 'Evening in Georgia' --date '2025-12-27'

Use folder name in category:

pwb-upload --category "Kaspiy ${PWD##*/}" --license 'PD-scan|PD-old-assumed-expired' --source https://dspace.nplg.gov.ge/handle/1234/387883 --dateParse

Category and prefix is the same:

S='xxx' pwb-upload --category "$S" --prefix "$S "

Default source is {{own}}.

Default license is cc-by-4.0.

--author for example [[User:Globustut|Globustut]]

--date in format YYYY-MM-DD.

--dateParse extracts year from a filename (1xxx or 2xxx).

--date and --dateParse are mutually exclusive.

--target (file name on Commons) is optional.

--prefix (prefix for file name on Commons) is optional.

--i lets you start from a specific index.

--recursive includes files from subfolders when no file is specified.

You can upload with minimal arguments:

pwb-upload --file my.jpg --category 'Sunsets in Batumi' --date '2025-12-27'

Or pass the file as positional argument:

pwb-upload my.jpg --category 'Sunsets in Batumi' --date '2025-12-27'

Or upload without category, date, and dateParse (set them later on Commons):

pwb-upload my.jpg

If no file is specified, it uploads eligible files from the current folder (no subfolders by default):

pwb-upload --category 'My category' --author '[[User:Globustut|Globustut]]' --license 'self|CC-BY-4.0|author=Globustut' --date 2005

To include subfolders:

pwb-upload --recursive

For local development (without installation), you can still run:

./upload.py --file my.jpg

Author: for the current user use me.

Autocompletion

Enable completion for the installed command:

eval "$(register-python-argcomplete pwb-upload)"

Release to PyPI

Release scripts in this repository:

• release_minor.sh bumps x.y.z -> x.(y+1).0
• release_patch.sh bumps x.y.z -> x.y.(z+1)
• release-added.sh uses already staged files and already bumped version in pyproject.toml (no git add .)

Call them from git (one-time setup):

git config alias.release-minor '!f() { repo=$(git rev-parse --show-toplevel) && bash "$repo/release_minor.sh" "$@"; }; f'
git config alias.release-patch '!f() { repo=$(git rev-parse --show-toplevel) && bash "$repo/release_patch.sh" "$@"; }; f'
git config alias.release-added '!f() { repo=$(git rev-parse --show-toplevel) && bash "$repo/release-added.sh" "$@"; }; f'

Then run:

git release-minor 'Release message'
git release-patch 'Release message'
git release-added 'Release message'

Build distribution files:

python3 -m build

Upload to TestPyPI:

python3 -m twine upload --repository testpypi dist/*

Upload to PyPI:

python3 -m twine upload dist/*

Wikidata item about this tool https://www.wikidata.org/wiki/Q137601716

Commons category https://commons.wikimedia.org/wiki/Category:Uploaded_with_pwb_wrapper_script_by_Vitaly_Zdanevich

SonarCloud https://sonarcloud.io/project/overview?id=vitaly-zdanevich_pwb_wrapper_for_simpler_uploading_to_commons

See also

My another Python script for uploading to Commons from gThumb

My web extension for uploading to Commons

All upload tools

CLI upload tools

This tool is mentioned at my blog post https://diff.wikimedia.org/2026/04/09/preserve-old-public-domain-newspapers-and-books-from-archive-websites/