WordPress OS X Install Tips

I like having WordPress running on my laptop because it makes it so easy to experiment with site changes without breaking the actual web site. Its not terribly difficult but there are a couple of quirks that required some googling to discover. Here is my recipe for installing WordPress on Mac OS X. No guarantees but at least its a starting point until things change again.

I’m assuming you are starting with a vanilla (non-Server) Mac OS X install, Mac OS X 10.4.6 in this particular case. The core steps needed are: installing MySQL, enable PHP in the built-in Apache web server and finally installing and configuring WordPress. I’m using a dedicated non-admin account but the same procedure should also work for the main site if you change the root web folder references to /Library/WebServer/Documents.

I’m also assuming you can handle downloading and installing apps and know the basics of using a Terminal command line and some command line editor such as vi or pico.

NOTE: I’m using WordPress here but the basic procedure is similar for other web content apps such as Drupal.

STEP 1 – Installing and Configuring MySQL Database Support

  1. Visit http://mysql.org/downloads/mysql and download the appropriate Standard installer package for your machine. Make sure you choose the appropriate architecture for your machine (PowerPC for G3/G4, PowerPC 64 bit for G5, or Intel.) The Mac section is about 3/4 of the way down the page. Use the current stable version which is 5.0 at the time I write this.
  2. Install the main MySQL package, drag the preference pane to /Library/PreferencePanes and optionally install the StartupItem if you want MySQL launched at boot (not required as you can manually start/stop it from the preference pane as needed.
  3. Start MySQL via the new preference pane in System Preferences. You’ll need admin authorization.
  4. To avoid having to type long strange paths in command lines use your favorite command line editor to add the folder with the MySQL binaries to your shell’s search path. If you’re using the default bash shell that means adding this line to the bottom of the .profile file in your home folder (create it if it doesn’t exist):
    export PATH="$PATH:/usr/local/mysql/bin"

The default MySQL setup has several unnecessary anonymous accounts and does not have a password on the root account (these are all internal to MySQL and have nothing to do with regular Mac OS X accounts.) We’re going to correct those issues as well as delete a test database.

  1. Issue these commands from a Terminal session (you type what’s after the $ or > prompt. Substitute your chosen MySQL rot password for {ROOTPASS} and the Bonjour computer name (shown at the top of Sharing in System Preferences) for {HOST}
    $ mysql -u root
    > drop database test;
    > delete from mysql.user where User = '';
    > flush privileges;
    > set password for root@localhost = password('{ROOTPASS}');
    > set password for root@ = password('{ROOTPASS}');
    > set password for 'root'@'{HOST}.local' = password('{ROOTPASS}');
    > quit

OK, MySQL is ready to roll. If you want it launched automatically every time you boot your machine you have to install the StartupItem and also turn on the appropriate checkbox in the MySQL system preference pane.

STEP 2 – Create the WordPress MySQL Database and User

WordPress doesn’t create its own database so we have to do that ourselves. We’re also going to create a dedicated MySQL user account for WordPress. This isn’t strictly necessary, you can use the root account, but its good security policy for the final web site and not hard to do. I’m using a database name of ‘wordpress’, a MySQL username of ‘wpuser’ and a password for that username of ‘wppass’. Feel free to substitute your own choices.

QUIRK #1: MySQL v4.1 made changes to its password format that WordPress or probably more accurately PHP does not handle but fortunately they included a function old_password() to generate the older format that works.

  1. Perform the following commands from a Terminal command line:
    $ mysql -u root -p
    Enter Password: {ROOTPASS}
    > create database wordpress;
    > grant all privileges on wordpress.* to wpuser@localhost identified by 'foo';
    > set password for wpuser@localhost = old_password('wppass');
    > quit

STEP 3 – Activate PHP in the Apache Web Server

WordPress is written in PHP which is not enabled by default in the built-in Apache web server used for Personal Web Sharing on Mac OS X. To fix that you must un-comment two lines in the Apache configuration file and start (or restart) the server. The configuration file requires root access to edit so you’ll need to invoke your favorite command line text editor, vi in my case, via ‘sudo’:

  1. $ sudo vi /etc/httpd/httpd.conf
    Search for the following two lines, delete the leading # from each then save the changes:
    #LoadModule php4_module libexec/httpd/libphp4.so
    #AddModule mod_php4.c
  2. Open the Sharing preference pane in System Preferences and in the Services tab turn ON Personal Web Sharing. If it was already turned ON then turn it OFF then back ON to make sure the configuration changes take effect.

STEP 4 – Install WordPress

I wanted to install WordPress in a Mac OS X user account set aside specifically for that purpose which means WordPress should go into the Sites folder of that account’s home folder. The WordPress site can then be accessed with the URL http://localhost/~{USER} where {USER} is the short name for the dedicated account. Alternatively, you can install it in the main web server root folder at /Library/WebServer/Documents and access it at http://localhost/. Your call.

  1. Throw out the existing default web page items from the Sites folder if you haven’t already done so.
  2. Download the latest version of WordPress from http://wordpress.org/latest.zip and extract the archive’s contents if Safari hasn’t already. You should wind up with a folder named simply wordpress.
  3. Copy the contents of the downloaded wordpress folder into the Sites folder. Don’t drag the entire folder, you just want its contents.
  4. In the Sites folder, duplicate the document named wp-config-sample.php and rename it to wp-config.php. Open wp-config.php with your favorite plain text editor then edit the first three MySQL settings to read as follows (substitute your MySQL wordpress username and password if necessary):
    define('DB_NAME', 'wordpress'); // The name of the database
    define('DB_USER', 'wpuser'); // Your MySQL username
    define('DB_PASSWORD', 'wppass'); // ...and password

QUIRK #2: Starting in Mac OS X 10.4.4 Apple changed the location where PHP expects to find a crucial MySQL file and the result is that WordPress can’t connect to its database. You scratch your head, verify that you entered the database settings correctly and become thoroughly confused. Fortunately there is a very easy fix that we can incorporate directly into the WordPress settings file, no changes to Mac OS X are needed at all (I discovered it in the comments to a post that proposed a different solution. crimemon, whoever you are, you are my hero!)

  1. For Mac OS X 10.4.4 and later only! change the MySQL settings line after the three above to read:
    define('DB_HOST', 'localhost:/tmp/mysql.sock'); // 99% chance you won't need to change this value

Looks like we’re in that unfortunate 1%.

STEP 5 – Configure WordPress!

The first time you access WordPress it has to install its database tables and perform other one-time setup. The first wordpress user created will be the admin user and is assigned a random password. Your first action should be to login as the admin user and change that password to something you can remember. If this site were visible to the outside world you’d need to choose a secure password to keep boneheads from guessing it and screwing around with your site and its settings. If it will only be used to experiment with WordPress locally its less of an issue but it might be a good idea to do so anyway to reinforce good habits.

Substitute the short name of the Mac OS X account where WordPress is to be installed for {USER}.

  1. Point your web browser at http://localhost/~{USER}/wp-admin/install.php or http://localhost/wp-admin/install.php if you used the main web server root folder for your install. If you’ve done everything correctly and no quirks have been added or changed since I wrote this, you should be greeted by a screen telling you that WordPress has to be set up with a link to STEP 1 in the process. Click the link but don’t go anywhere because its basically instantaneous. If instead of the setup screen you are told that WordPress can’t connect to its database then double check that you’ve entered the correct database settings in wp-config.php. If that still doesn’t help then get googling! Search for database issues in WordPress with whatever version of Mac OS X you are using.
  2. You will be given the name of the admin account (admin), the initial random password assigned to it and a link to login to WordPress. Click the link, login as admin, then immediately edit your profile to assign a password you can remember.


And that’s it! You now have a functional WordPress install and that’s as far as I’m taking you with this post. The official WordPress site has lots of resources and extensive documentation so that’s probably a good place to start.


If you try the alternate perma-link formats you’ll discover they don’t work with the above setup, the reason being that Mac OS X does not support using .htaccess files with Apache in its default configuration, and that is essential for perma-links and other plug-ins that need URL rewrite rules to do their thing. Its easy to enable .htaccess for the root folder but the hints I’ve found for enabling them in individual Mac OS X account Sites folders don’t seem to work. I’ll post additional instructions if and when I figure that out.

20 Responses to “WordPress OS X Install Tips”

  1. Steve Lawson says:

    Thanks for that; your instructions worked flawlessly for me.

  2. GLORIAD System Advancements » Blog Archive » WordPress Links says:

    […] http://warker.com/2006/09/16/wordpress-os-x-install-tips/ […]

  3. James says:

    I’ve found that using MAMP and WordPress makes it as easy as it is to install WordPress alone, and there is no installing of anything into your system.

  4. Al says:

    Thank you so much for posting those instructions – that worked flawlessly. For some reason I had php5 already installed so skipped the php 4 enabling so it was even easier! Great article!!

  5. links for 2007-02-15 at Al Power says:

    […] WordPress OS X Install Tips Some localhostin’ fun for getting wordpress and mysql working on OS X – very useful! (tags: wordpress mysql localhosting) Powered by Gregarious […]

  6. Dave says:

    James: I’ve been looking at MAMP lately and it looks very nice. Recent versions of Apache, MySQL and PHP in a plain old app without a tedious installation process. I’ve also worked out how to serve multiple sites from one account (instructions coming soon) and if MAMP can do the same I’ll probably give it a try.

  7. Janne says:

    Thanks so much for the /tmp/mysql.sock tip – had been searching for a solution for some time now… Works like a charm now.

  8. Ben says:

    yeah I second Janne. thank you for that tip…saved me a headache…

  9. new shiny wp blog on os x at wp says:

    […] WordPress OS X Install Tips […]

  10. matt shobe says:

    …the mysql.sock tip is a friggin’ lifesaver. Welcome to the Essential Permalinks club!

  11. Joseph says:

    I was having trouble installing WordPress locally on an iMac G5. Kept getting the error that WordPress couldn’t connect to the database. Your tips solved it! Thank you!

  12. Simon says:

    Again, the /tmp/mysql.sock tip helped no end.

  13. Security at GLORIAD » Blog Archive » WordPress Links says:

    […] http://warker.com/2006/09/16/wordpress-os-x-install-tips/ […]

  14. Adrian says:

    I hope you have time to read and understand this..

    I installed wordpress on an old G4 733 running the latest os x 10.4.9. Installed following yours and the default read me that came with the install. Runs perfectly fine on that machine both as admin and view page.

    My problem is if i try to test the blog on my G5 mac on the same wireless local network, if i type my domain/wordpress/ the url in the window on safari reverts to localhost/wordpress/ but all i get is a 404 error. If however i type the dashboard location which is url/wordpress/wp-admin/ i get the wordpressdashboard but it only has an unformatted plain white blackground in a default form of text, the css appears to be doing nothing to chenge the shape or add the background theme.

    Unfortunatly I am a total self taught idiot at these things i have previously installed phorum on the g4 and that ca nbe accessed from both the G5 and the wider internet using the external url address.

    So it seems close to root on my web server i can see it all on the machine it is running on but I cannot access the page by trying to access using my expected external url which other php mysql type web sites running on the same machine under Apache can….

    Any help will be so gratefully appreciated cheers.. I hope someone still comes here for a read on a regular basis

  15. nerdbot.com says:

    […] four hours to troubleshoot my way through this. I eventually found the problem buried deep within this tutorial (thanks, […]

  16. Christoph says:


    I must have spent 3 hours this weekend trying to figure it out.

  17. Installing WordPress 2.6.1 on Mac OS X Leopard « Bart Guijt’s Purpleware says:

    […] http://yoursite.com/?p=123) your WordPress setup could fail you. First, you need to follow the WordPress install instructions on Mac OS X – these are written for OS X Tiger, but they work just as well for Leopard. However, there are a […]

  18. Leopard: How to Install Wordpress : Tech Center says:

    […] associated with this article.http://www.angry-fly.com/index.cfm/2007/10/26/Fix-for-MySQL-on-Leopard http://warker.com/2006/09/16/wordpress-os-x-install-tips/ http://remysharp.com/2007/10/27/lamp-in-leopard-osx-105-php5-and-apache-22/ Previous: Ubuntu: […]

  19. Tom says:

    Thank you for the tip on DB_HOSTNAME. I have been fighting the install process for two days, and the light shined today! Thanks again.

  20. Fixing WordPress update issue for Mac localhost « Larry Gordon says:

    […] associated with this article.http://www.angry-fly.com/index.cfm/2007/10/26/Fix-for-MySQL-on-Leopard http://warker.com/2006/09/16/wordpress-os-x-install-tips/ http://remysharp.com/2007/10/27/lamp-in-leopard-osx-105-php5-and-apache-22/%5Bvia tech-recipes] […]