Installing web2py from source on your machine

<!--

Probably need to install MySQLdb also.
Is MySQLdb hard to install? Explains why MySQLdb sometimes needs to be compiled from source, depending on the target system.

$ sudo easy_install pip
$ sudo -H pip install pip --upgrade
$ sudo -H pip install MySQL-python

-->
This chapter shows you how to install the source code version because:

• It will be uploaded to Google App Engine as source files
• If for some odd reason your application doesn't work as expected under a new version of web2py, it will be trivial to roll back to a previous version that worked

Find or create an empty directory

• Change to the parent directory where you want web2py to live. It can be anywhere, but /usr/local is considered a sacred place that won't be touched by operating system updates.

$ cd /usr/local

• Clone the web2py repository to your development machine.

# Creates directory named web2py
# --recursive also obtains the
# pydal library, which is a 
# separate git repository. It's
# meant for python users who don't
# use the rest of the web2py framework
$ git clone --recursive https://github.com/web2py/web2py.git

<!--

Watch out for the following and also read http://askubuntu.com/questions/343395/how-do-i-prevent-git-from-requiring-sudo-on-every-git-command
Try it without the sudo first, but if you get an error such as fatal: could not create work tree dir 'web2py'.: Permission denied then you'll need it.

-->

The default directory name will be web2py.

Optional: Specify a directory name other than web2py

You can specify another directory name at the end of the command line if you wish; in this case, the directory is named myweb2py, so it will end up at /usr/local/myweb2py.

$ sudo git clone --recursive https://github.com/web2py/web2py.git myweb2py

Starting web2py

It's easy to forget that web2py is nothing more than a Python program, especially if you download the installable app instead of the source code version. But it's just a directory tree of Python source code and associated resources. Your application is simply one directory under web2py/applications

That's it! to prove it's a working installation, just do this:

# Go to the web2py directory
$ cd web2py
# You will probably be asked for your password.
$ sudo python web2py.py

You should see the startup page appear:

If web2py doesn't start and you see something like the error message below you almost certainly forgot the sudo part of the command line.

OSError: [Errno 13] Permission denied: '/usr/local/web2py/deposit'

Importing MySQLdb

Web2py relies on a Python library called MySQLdb. Unfortunately, it needs to be compiled from its C source code using the Apple Xcode toolchain, which is a massive download.

Here's how to get pip.

Getting pip if you don't have it

The best way to install Python libraries is the pip utility. See if you have pip on your path:

# If nothing is displayed, you need to get it
$ which pip

• If you don't have pip, install it like this:

$ sudo easy_install pip

On OS X, you'll be asked if you want to install XCode. It's big--about 1.5G at time of printing. There are other ways to get the job done. See Is MySQLdb hard to install? if you can't afford the disk space.

• Use Homebrew to install MySQLdb:

$ brew install mysql-connector-c

• Test the installation:

$ python -c "import MySQLdb"

Reference

The web2py documentation README.MD has notes on App Engine deployment.

Is MySQLdb hard to install? Discusses the issues behind installing MySQLdb and why it has to be installed from source.

Improving this document

Feel free to ignore this. It's a placeholder for new topics under consideration.

• The web2py documentation README.MD discusses how to handle the case where git clone is used on an existing repo with PyDAL installed already. Try installing over such an installation and see what errors occur. This will be common because many novice web2py developers will have installed it from binary.
• Document what happens when user omits sudo. See search results for for example the search ["web2py" "OSError: [Errno 13] Permission denied:"](https://www.google.com/search?q="web2py"+"OSError%3A+[Errno+13]+Permission+denied)