-
Notifications
You must be signed in to change notification settings - Fork 7
Mac Linux Setup
This guide provides instructions for setting up a basic Django development environment on Mac OS X or Linux. It will walk you through the steps required to install packages and will familiarize you with some best practices for development with Python and Django.
More specifically, this guide will help you get set up with the pip and virtualenv tools for installing Python packages and creating isolated development environments for each project you work on. Once you finish this guide, you will be ready to start developing your first Django project using, for example, the tutorial on the Django project's website.
There's a quick start guide at the end of this document for advanced users already familiar with Python development. However, it is strongly recommended that you read this entire document and only use the quick start guide for reference.
Basic knowledge of launching a terminal and running shell commands is required. Throughout this guide, you will be asked to run commands like this:
$ echo "hello there"
The '$' symbol at the beginning represents a command prompt. Copy everything after the '$', paste it into the terminal, and press enter.
Virtual environments (virtualenvs) will be introduced later. When working inside a virtualenv, the environment's name will appear in parentheses before the prompt to indicate that the command is executed in the virtualenv like so:
(tutorial)$ echo "hello there"
As before, just type the part of the command after the '$' prompt.
This guide assumes you're using the Bash shell. Other shells will work just fine for developing Django projects, but you will need to adjust the virtualenvwrapper configuration instructions slightly so the command to load it runs when your shell starts. To see if you're using Bash, run the following command and verify the output ends with /bash (e.g., /bin/bash):
$ echo $SHELL
The sudo command is used in this guide to install Python packages into the global Python environment on your computer. Sudo allows regular users with administrator privileges to run commands that may modify the system for all users.
Sudo should already be available on your computer. Try the following command To verify you have the proper permissions to use sudo. You may be required to type in your password before the command is executed:
$ sudo echo "hello there"
If you don't have permissions to use sudo, you may need to talk with your computer's administrator to get access or to ensure the parts of this guide requiring sudo are taken care of. If all else fails, you may be able to install the required tools locally in your own account. Such installation is beyond the scope of this guide.
This guide assumes a version of Python supported by Django is already installed on your system and in your path. Run the following command to verify Python is installed and to check the version:
$ python --version
Check the documentation on the Django Project website for a list of supported Python versions. As of this writing, the latest version of Django is 1.3.1 and supports Python versions from 2.4 through 2.7, inclusive, with 2.7.2 recommended. It's worth noting that these requirements apply to the core Django project. Your own projects may use other Python packages or Django apps that require specific versions of Python, but that is beyond the scope of this guide.
Easy Install is the default package manager bundled with Python for
installing and managing Python packages, such as those found in the
Python Package Index.
Pip, an improved replacement for Easy
Install, is generally preferred by the Python community and should be used
in place of it if easy_install is encountered in instructions for
installing packages (i.e., replace easy_install packagename with pip install packagename). You only need to install pip once and you can use
it for all your Python projects. To install pip:
$ sudo easy_install pip
We'll be using the pip install package_name command throughout this
guide to install packages. Other useful pip commands not used here
include pip install --upgrade package_name to upgrade a package and pip uninstall package_name to uninstall a package.
Virtualenvwrapper is a helpful wrapper around virtualenv, a tool to create isolated Python environments. By default, a Python package installed with pip will be put into the main Python installation and available to all Python projects on your system. For a variety of reasons, virtual environments (commonly call virtualenvs) should be used to create project-specific Python environments to isolate your projects from each other. This guide will introduce you to basic virtualenv concepts and the minimal set of commands required to be productive.
Depending on your computer's configuration, you may have more than one
version of Python installed and accessible from different commands. For
example, Python 2.6 may be installed and available as python2.6 and
Python 2.7 may be installed and available as python2.7. Assuming 2.7 is
your default Python version, it will be available both as python and
python2.7 where the former is simply a link to the latter.
TODO: Diagram showing python2.6, python2.7, and python as a link to python2.7
Each installation of Python has a directory called site-packages that contains the packages installed with tools such as easy_install and pip. When you installed pip in the previous section, it was downloaded and installed to the site-packages directory for your default Python installation. You can run the following command to see where this is:
$ python -c 'import pip; print pip.__file__'
Now, consider what happens if you install two Python programs, ProgramA and ProgramB, both of which require version 1 of a library, Library_v1. A single copy of Library_v1 is installed in site-packages and both ProgramA and ProgramB use it.
TODO: Diagram showing ProgramA and ProgramB both happily pointing to Library_v1 in the global site-packages.
So far so good. Next, a new version of ProgramB is released that requires version 2 of the library. Unfortunately, version 2 makes some changes that make it incompatible with ProgramA. You install the updated ProgramB and upgrade the library to Library_v2, overwriting Library_v1. See the problem? ProgramA still requires version 1 of the library but we've replaced it with version 2.
TODO: Diagram showing ProgramA and ProgramB both pointing to Library_v2, but ProgramA is all sad and broken :'( Poor ProgramA.
What you'd like to be able to do is is create separate, isolated Python environments for ProgramA and ProgramB where each one has only its own dependencies installed. Virtual environments make this possible. With virtualenv, you can create an environment specifically for ProgramA and an environment specifically for ProgramB. Each environment contains a copy of Python with its own site-package directory.
TODO: Diagram with two separate virtualenvs, one for ProgramA and one for ProgramB, both with the correct version of the library installed. Everyone is happy again.
There are many other scenarios where virtualenvs are useful. For example:
- You're deploying your website to a shared host where you don't have permissions to install packages into the global site-packages folder. Virtualenv allows you to create a full environment for your program in your own directory.
- You install a Python program with multiple dependencies and get everything running just right. Virtualenv allows this program's dependencies to exist in an isolated environment where other programs can't interfere with them.
Because of the various benefits of virtualenvs, it is a good practice to create one for each Python project you work on.
You only need to install these packages once and then you can use them for all your Python projects. To install virtualenv and virtualenvwrapper:
$ sudo pip install virtualenv
$ sudo pip install virtualenvwrapper
Next you'll need configure your shell to load virtualenvwrapper when you open a terminal. Edit ~/.bash_profile (assuming you're using Bash, otherwise you may need to edit a different file), creating it if it doesn't already exist, and append the following line to load virtualenvwrapper when you open a terminal:
source $(which virtualenvwrapper.sh)
Close and reopen your terminal to apply the changes to your current shell. This only needs to be done once since it will be automatically applied to future shells upon login. To verify successful setup, run the following command:
$ workon
The command should print a) nothing, or b) a list of virtual environments
that you may have created in the past. If it prints a "command not found"
error, you'll need to do some troubleshooting. Try running source $(which virtualenvwrapper.sh) from the command line and try the workon command
again. If this works, it's likely the command isn't being executed when
your shell starts.
This section will show you how to create a virtual environment for a project we'll call tutorial. Similar steps should be followed for each Python project you're working on. Before proceeding, note how your command prompt looks by default. It may look similar to this:
host:dir user$
Using the mkvirtualenv command provided by virtualenvwrapper, create and activate a virtual environment:
$ mkvirtualenv --no-site-packages tutorial
Notice how your prompt has changed to indicate the tutorial environment is active:
(tutorial)host:dir user$
If your prompt did not change and you have a git-aware prompt then read, Why is virtualenv not setting my terminal prompt?
You're now in an isolated Python environment. When you run python or
pip, they will be executed from this environment rather than your
system-wide Python installation. You can verify this by running which python and which pip and noticing the executables are located within
the tutorial virtual environment directory (~/.virtualenvs/tutorial/ by
default). Any Python packages installed with pip (e.g., pip install packagename) or from source (e.g., python setup.py install) will be
properly installed to your virtual environment as long as it is activated.
A list of installed packages can be viewed by running lssitepackages.
You should leave a virtual environment once you're done working on it:
(tutorial)$ deactivate
Note that this doesn't delete the environment, it just deactivates it.
It still exists in ~/.virtualenvs/tutorial/ and can be reactivated with the
workon command. With no arguments, the workon command displays a list of
all your virtual environments. To activate an environment, pass its name
to the workon command (e.g., workon tutorial).
If you're not already in your tutorial project's virtual environment, go ahead an activate it:
$ workon tutorial
The easiest way to install the latest stable version of Django is with pip. Since we're working within a virtual environment, pip will install Django into this environment rather than the system-wide Python folder. Note how the sudo command is not required since you're not making changes outside of your virtual environment:
(tutorial)$ pip install django
Let's verify Django was installed properly and is only available in the virtual environment. Run the following command to run Python, import the django module, and see where it's installed:
(tutorial)$ python -c 'import django; print django.__file__'
The command should output the path to the django package installed in ~/.virtualenvs/tutorial/.
Now, let's deactivate the virtual environment and notice the django module is no longer available from the virtual environment:
(tutorial)$ deactivate
$ python -c 'import django; print django.__file__'
Assuming everything works as planned, there are two acceptable results from executing the previous command:
- An ImportError will be raised if you haven't previously installed Django in the system-wide Python environment.
- If Django was previously installed in the system-wide Python environment, the import may succeed but the command will print a path to the django module outside of your virtual environment.
TODO: Create the Django tutorial project. We're not sure yet if we'll link somewhere else (the Django tutorial) at this point, or do something like provide a pre-packaged working project that can be unpacked.
- Pip documentation
- Virtualenvwrapper documentation - Full command reference and additional documentation
For the more experienced and/or impatient, here's a quick start guide for getting up and running as soon as possible. Use this section as a reference for starting an additional project once you've followed the rest of the guide and understand the fundamentals.
Install pip and virtualenv:
$ sudo easy_install pip
$ sudo pip install virtualenv
$ sudo pip install virtualenvwrapper
Add the following line to the end of your shell's initialization file (e.g., ~/.bash_profile):
source $(which virtualenvwrapper.sh)
Close and reopen your terminal for the changes to take effect.
Create a virtualenv for your project and install the latest stable release of Django. In this example, we'll create a virtualenv named "tutorial":
$ mkvirtualenv --no-site-packages tutorial
(tutorial)$ pip install django
Create a Django project, install addition Python packages if required, etc. Exit the virtualenv when you're done working on the project:
(tutorial)$ deactivate
To re-enter the project's virtualenv later and resume work on the project:
$ workon tutorial