Manual:Pywikibot/Installation

Initial setup
First you have to choose which branch of PWB you want to use:
 * Core or formerly "rewrite" which is better for doing running in WMF projects (like Wikipedia) but be noticed all of scripts hasn't been migrated to this branch so maybe you can't run some scripts
 * Compat or formerly "trunk": It's old and slow and dirty but you can use it so much more easier in non-WMF projects (for example for wikis without API support) and all of the scripts exist in this branch

Depends on which branch you want to install and which OS you're using you have to do things: The two things to do are:
 * 1) Download Python (for Windows users) or update it, if needed (for Mac users)
 * 2) Install httplib2 (for just core, not compat) or install BeautifulSoup (for just compat, not core)
 * 3) Download pywikibot

After that you just need to make a file named "user-config.py" and you DO NOT need to "install" pywikibot to be able to make use of it. You can actually just run it from directory you downloaded it (Via Git or nightlies)

Download Python
Requirement: To run Pywikibot, Python v2.7.2 or higher is required, but Python v3.x isn't currently supported.


 * For Windows, download the latest Python v2.x here ( not 3.x version! ) Install the program.
 * For Mac and Unix, Python is already present. On Mac OS X and on some Unix versions (although it might be necessary or recommended to update it if you have a very old version).

Core branch dependencies (see also Dependencies below) easy_install.exe httplib2 (In windows setuptools will be in C:\Python27\Scripts\ dir)
 * Install setuptools
 * Install httplib2 package:

Download Pywikibot
The easiest way to download Pywikibot is to use the latest nightly release. Just download the pywikibot zip file to your computer and decompress the file - there is no further installation required.

Download Pywikibot with Git
For installing with Git you should run: the  option. automatically install required submoduls (like i18n messages or spelling) but if you didn't use this option, after cloning you should install externals. There are two (i18n is really required even for English language bots):
 * For compat (formerly "trunk")
 * For core (formerly "rewrite")

Shortcut in command line
To allow your source code to be developed outside of the pywikibot source directory, add something like: to a file that gets run on login, usually ~/.bashrc - this avoids typing the export PYTHONPATH part in each time you log in. Naturally, change paths to match your installation.

Similarly, you can set the PYWIKIBOT_DIR environment variable to specify the directory in which user-specific information is stored (in particular, user-config.py which contains login data for the bot).

Windows users: create a shortcut
How to make a quick shortcut to run commands (Windows users):

If you're installing Pywikibot in a folder such as "My Documents" it may be troublesome to repeatedly use the "chdir" command to go into the folder to run the bots.

On Windows you can create a shortcut which will open the command box which you can use to run bots easily. Just follow these steps to create one:
 * 1) Right click the folder pywikibot is installed in.
 * 2) Click "Create shortcut". A new shortcut icon with the arrow key will be created.
 * 3) Right click on the new shortcut, and click properties.
 * 4) In the properties window, in the target box type in cmd.exe.
 * 5) In the "start in" box enter the full address of pywikibot.
 * 6) Click "OK".
 * 7) Click the shortcut and the cmd.exe opens up with the full path listed.
 * If you click properties again on this shortcut, you will notice that the shortcut icon has changed.

Updating

 * If you used Git for downloading Pywikibot, you must go to the your directory and command:
 * If you are using a nightly version, the process is a bit more complicated. You have to re-download a full copy from . Before installing it, backup your configuration files and scripts (user-config.py, any family file, or custom script that you might have created, and any current dump xml file you're using for a wiki). Replace your pywikibot directory by the new version you just downloaded. Restore your configuration files. If you're not sure of what you're doing, do not erase but keep a backup of your complete old pywikibot directory, to avoid losing any important files.

Automatic Updating on Tool Server
For automatic updating you can make update bash file and put it in root and fill it with these commands: and then run crontab -e and enter the following to make your bot to run every day at 00:00AM (midnight): Notice: in these cods username is your username.

Dependencies
The pywikibot framework is quite a big and complex code and as such needs external python modules (libraries) from other sources also in order to work properly. The dependencies can be installed manually or automatically (not supported by core yet).

If any issues arise during installation (of dependencies) please file a bug report or write to the pywikipeda-l maillist.

Automatic (recommended)
If available this is the recommended way, because this will result in an identical setup on all machines. All you have to do is just execute your favorite script after installation and pywikibot will ask you whether you want to install missing packages.

Packages will be installed from OS package management is possible (all Linux, not under win). If they cannot be found they will be downloaded as archive from original source, extracted and installed. In the course of this process a few packages have to be slightly modified in order to work seamlessly with pywikibot. This modification needs and additional binary tool called patch (patch.exe under win). Unfortunately this is not available from MS, therefore we use a port of the original linux code to win called gnuwin32 patch.exe:

Patch for Windows - Patch: apply a diff file to an original Version: 2.5.9 Homepage: http://www.gnu.org/software/patch/patch.html (sources freely available) Description: `patch' takes a patch file containing a difference listing produced by diff and applies those differences to one or more original files, producing patched versions. Win32, i.e. MS-Windows 95 / 98 / ME / NT / 2000 / XP / 2003 / Vista with msvcrt.dll and msvcp60.dll. If msvcrt.dll or msvcp60.dll is not in your Windows/System folder, get them from Microsoft, or (msvcrt.dll only) by installing Internet Explorer 4.0 or higher.

It is worth mentioning here that - despite the OS package management "install mode" - all files are installed locally into the externals/ directory of pywikibot. This is a very useful feature for users that do not have permission to install software to their system, e.g. non-admins.

Manual (for experts)
In order to install the needed packages manually, you first need to know which ones. A full list of all needed modules can be found in externals/__init__.py and contains: Which ones you really need, depends strongly on the script you intend to run - if you are unsure use the automatic mode above. In order to check correct installation just run a bot script. If the dependencies are satisfied everything will be ok, else the framework will complain and ask whether it should install missing packages automatically.
 * framework core code:
 * i18n [git submodule]
 * spelling [git submodule]
 * httplib2 [git submodule]
 * BeautifulSoup.py
 * patch.exe
 * depending of which script will be used:
 * opencv, opencv/haarcascades [git submodule]
 * pycolorname [git submodule]
 * irclib
 * mwparserfromhell
 * parse-crontab
 * odfpy
 * openpyxl
 * python-colormath
 * jseg, jseg/jpeg-6b
 * mlpy
 * music21
 * ocropus
 * pydmtx
 * py_w3c
 * zbar
 * (slic)
 * (bob, xbob_flandmark)

Setup on Wikimedia Labs/Tool Labs server
In order to install your bot onto the Wikimedia servers and run it from there, make sure first to become familiar with Wikimedia Labs/Tool Labs environment.

In the next step you have to request several accounts (for labs, for the tools project, your tool), provide an ssh key and so on. How to do this and then proceed, is described in full detail in Setup pywikibot on Labs.