Editing Manual/Upgrading (section)

== Unpack the new files == <!--T:39-->

=== Using a tarball package === <!--T:40-->

<!--T:41-->
You can put the new files into place using FTP or the command line. Use the command line, if you have access to it! Using the command line will be much faster than having to upload each single one of the thousands of files via FTP.
</translate>

{{Note|1=<translate><!--T:42--> You should put the decompressed tarball in a new and empty folder on your server. If you instead extract the new version directly on top of your old version, rather than in a new directory, you should follow the instructions described in [[<tvar name=1>#Back up existing files and the database</tvar>|Back up existing files and the database]]: otherwise, if you've made any customizations you may erase them in a way that leaves you with no reference to re-apply them from.</translate> <translate><!--T:43--> Extracting a tarball over top of your live copy of MediaWiki can also leave behind files from the old version of MediaWiki which may interfere with the upgraded code.</translate> <translate><!--T:612--> It's recommended that you unpack the new files into a new directory, and then apply customizations to the new directory (restoring <tvar name=1><code>LocalSettings.php</code></tvar>, images folder, extensions, and other customizations like custom skins).</translate>}}

<translate>
==== FTP or graphical ==== <!--T:44-->

<!--T:45-->
If you cannot access the command line on your server, download the MediaWiki tarball to your local computer and use <tvar name=7zip>[http://www.7-zip.org/download.html 7zip]</tvar> to extract the tarball on your local PC.

<!--T:46-->
After you extracted the files locally, use your favorite FTP client software to upload directories and files to the server.

==== cPanel File Manager ==== <!--T:564-->
</translate>
<translate><!--T:565--> cPanel is a popular interface provided by many web hosts.</translate>
<translate><!--T:566--> This method is efficient because the files are uncompressed on the server itself.</translate>

* <translate><!--T:567--> Navigate to the directory that holds your wiki folder.</translate>
* <translate><!--T:568--> Upload the <tvar name=1>mediawiki-1.xx.x.tar.gz</tvar> file.</translate> <translate><!--T:569--> You may need to hit "Reload" to see it.</translate>
* <translate><!--T:570--> Extract the <tvar name=1>mediawiki-1.xx.x.tar.gz</tvar> file.</translate> <translate><!--T:571--> Reload again.</translate>
* <translate><!--T:572--> Confirm that the <tvar name=1>mediawiki-1.xx.x</tvar> folder is present.</translate>
* <translate><!--T:573--> Delete the tar.gz file.</translate>
* <translate><!--T:574--> Copy all necessary skins, extensions, image folders, customizations, and the <tvar name=1><code>LocalSettings.php</code></tvar> into the new folder.</translate> <translate><!--T:575--> (See below.)</translate>
* <translate><!--T:576--> When you are ready to run <tvar name=1>update.php</tvar>, rename your old wiki folder and your new wiki folder.</translate> <translate><!--T:577--> (e.g. "w" becomes "w1.34" and then "mediawiki1.35.0" becomes "w".)</translate> <translate><!--T:578--> This step is easily reversible if you run into problems.</translate>

<translate>
==== Command line ==== <!--T:47-->
</translate>
<translate><!--T:48--> You may need to run the command as <code>sudo</code> if you don't have full write permissions to the wiki install directories under your current user.</translate>
<translate><!--T:224--> When untarring a tarball package normally a new directory for the new wiki version will be created and you will have to copy the old configuration files and images directory from your old installation directory:</translate>

<code class="mw-code mw-highlight plainlinks" style="display:block"><!--
--> /path/to/your/new/installation/  
wget https://releases.wikimedia.org/mediawiki//mediawiki-.tar.gz
tar xvzf mediawiki-.tar.gz
rm mediawiki-.tar.gz
</code>

<translate>
<!--T:49-->
(Open)Solaris users should use <kbd>gtar</kbd>, or:
</translate>

 $ gzip -dc mediawiki-.tar.gz | tar xf -

<translate>
===Other files=== <!--T:50-->

<!--T:51-->
After extracting the tarball, you should copy or move some files and folders from the old installation directory to the new one:
</translate>
* <code>LocalSettings.php</code> - <translate><!--T:52--> contains your old configuration settings.</translate>
<translate>
<!--T:53-->
* The <tvar name=code-img><code>images</code></tvar> (or <tvar name=code-upl><code>uploads</code></tvar> in older versions) directory, which contains all the uploaded files to the wiki, unless you have chosen a different upload directory, and change the ownership and permissions. <tvar name=chmod><code>find ./images -type d -exec chmod 755 {} \;</code></tvar> and <tvar name=chgrp><code>chgrp -R apache images</code></tvar> (e.g. if your web user is ''apache'').</translate>
<translate>
<!--T:54-->
* Some extensions in the <tvar name=dir><code>extensions</code></tvar> directory. You should always get updated extensions; old extensions aren't guaranteed to work with a newer version of MediaWiki.</translate>
<translate>
<!--T:55-->
* In case you use a [[<tvar name=logo>Special:MyLanguage/Manual:$wgLogo</tvar>|custom logo]] this file also needs to be restored from backup. Before 1.24 the logo is usually in <tvar name=dir1><code>skins/common/images/</code></tvar>. After 1.24 the logo is usually in <tvar name=dir2><code>resources/assets/</code></tvar> or <tvar name=dir3><code>images/</code></tvar> if that's what you chose to use.</translate> <translate><!--T:597--> Then add to <tvar name=1><code>LocalSettings.php</code></tvar> e.g. <tvar name=logo2><syntaxhighlight lang=php inline>$wgLogo = "$wgScriptPath/images/logo.png";</syntaxhighlight></tvar></translate>
<translate>
<!--T:555-->
* For 1.35 you may need to restore the logos from <tvar name=1></tvar>.</translate> <translate><!--T:615--> Then add to <tvar name=2><code>LocalSettings.php</code></tvar> e.g. <tvar name=3><syntaxhighlight lang=php inline>$wgLogos = [ '1x' => "path/to/1x_version.png", '2x' => "path/to/2x_version.png", 'svg' => "path/to/svg_version.svg" ];</syntaxhighlight></tvar></translate>
<translate>
<!--T:56-->
* Custom skins from within the <tvar name=skins-dir><code>skins</code></tvar> directory.</translate>
<translate>
<!--T:57-->
* Any modifications made to the old installation files or extensions.</translate>
<translate>
<!--T:58-->
* Any .htaccess file (if you're using Apache and you've defined any rules in them).
</translate>

<translate><!--T:59--> Once done, make this new folder the published folder on the web server, or rename the old installation directory and then rename the new one to match the old name.</translate>
<translate><!--T:583--> Change ownership and group of everything so the web server has access to the files.</translate>

<translate>
=== Using Git === <!--T:60-->

<!--T:61-->
If using <tvar name=git></tvar>, export the files into a clean location, and then copy the old customized files into the new location as described in the previous section.
</translate>

<translate><!--T:62--> You will also need to install some external PHP libraries using Composer or a provided collection maintained for the Wikimedia wiki farm.</translate>
<translate><!--T:213--> More details on installing and updating external libraries can be found in the [[<tvar name=download>Download_from_Git#Fetch_external_libraries</tvar>|Git download documentation]].</translate>

<translate>
=== Using patch === <!--T:63-->
</translate>
<translate><!--T:64--> A small patch file is usually made available for a minor version upgrade.</translate>
<translate><!--T:260--> You'll need to download [[w:patch (Unix)|patch]] to use this.</translate>
<translate><!--T:261--> Manually download and extract the patch file from [<tvar name=dumps>https://releases.wikimedia.org/mediawiki/</tvar> the dumps site] or follow the directions with wget below.</translate>
<translate><!--T:262--> Patches are incremental, you can '''not ''' skip a version.</translate>

# <translate><!--T:65--> <kbd>cd</kbd> to your main MediaWiki directory (the one with <tvar name=1><code>LocalSettings.php</code></tvar>).</translate>
# <translate><!--T:66--> Download the patch file and <kbd>gunzip</kbd> it.</translate>
# <translate><!--T:67--> Use <tvar name=patch><code>patch -p1 --dry-run</code></tvar> to check what will be changed (''e.g.'', <tvar name=patch2><code>patch -p1 --dry-run -i ''mediawiki-x.xx.x.patch''</code></tvar>)</translate>
# <translate><!--T:68--> If all is well, run <kbd>patch</kbd> again without <tvar name=dry><code>--dry-run</code></tvar>.</translate>
# <translate><!--T:69--> Check your Special:Version and you should see the new version number in place.</translate>

<translate>
=== Files remaining that may cause errors === <!--T:70-->

<!--T:71-->
If you unpacked over the old installation directory, some old files can cause problems with the new version.