The recommended way to get a working settings file and configure your first store is to use the clonesatchmo program. However, if you would like to customize the settings by hand or dive into the details of how Satchmo’s settings are used, this portion of the documentation will be useful.

Customizing the settings

Once Satchmo is installed on your PYTHONPATH, you will need to create a new project or integrate Satchmo into an existing project. Before proceeding with the next steps, please familiarize yourself with the sample projects, see here for more.

Each of these projects show examples of how to configure Satchmo and integrate it with other Django applications. Once you are familiar with these examples, you can configure your project based on the notes below.

Additionally, there is a streamlined satchmo directory structure in the skel directory. You may use this as the basis for your store.

You need to customize the file in mystore to include the relevant satchmo information. A sample file called is available in the projects/base directory to act as a template. You may use this file as a template for or use the notes below to configure your existing one.

Please remember to ensure that your Django database connections and settings are working properly before trying to add any pieces of satchmo.

  1. Ensure that /home/user/src/mystore/ has the following satchmo-specific configurations (in addition to the defaults and your other app needs):

    import os
    DIRNAME = os.path.abspath(os.path.dirname(__file__))
    LOCAL_DEV = True
    MEDIA_ROOT = os.path.join(DIRNAME, 'static/')
    MEDIA_URL = '/static/'
    TEMPLATE_DIRS = (os.path.join(DIRNAME, "templates"))
    #### Satchmo unique variables ####
    #from django.conf.urls import patterns, include
                        'SHOP_BASE' : '',
                        'MULTISHOP' : False,
                        'SSL'       : False,
                        #'SHOP_URLS' : patterns('',)
    # Load the local settings
    from local_settings import *


In order for the admin site to work properly, you must have placed before django.contrib.admin

  1. Copy the local_settings file to mystore:

    cp /home/user/src/satchmo-trunk/satchmo/projects/base/ \
  2. You will need to verify the values assigned to the following items in



Satchmo requires that your database be able to support utf-8 characters. This is especially important for MySQL. If you are using MySQL, you may want to use the following statement in your settings file to enforce utf-8 collation:

DATABASES['default']['OPTIONS'] = {
   'init_command' : 'SET NAMES "utf8"',


If you are using a Windows system, we recommend setting your MEDIA_ROOT using normalize_path as shown below:

from satchmo_utils.thumbnail import normalize_path
MEDIA_ROOT = normalize_path(os.path.join(DIRNAME, 'static/'))

Configure the rest of the required files

  1. Next, you need to configure your file. The most simple file would look like this:

    from django.conf.urls import *
    from satchmo_store.urls import urlpatterns
  2. If you have additional urls you would like to add to your project, it would look like this:

    from django.conf.urls import *
    from satchmo_store.urls import urlpatterns
    urlpatterns += patterns('',
        (r'test/', include('simple.localsite.urls'))

3. Ensure that you have a template directory setup. You only need to place templates in the directory if you are overriding existing templates.

After you have installed everything, you should have a directory structure that looks similar to this:

    |-- satchmo.log
    |-- simple.db
    |-- static
    |   |-- css
    |   |   |-- blackbird.css
    |   |   |-- jquery.autocomplete.css
    |   |   `-- style.css
    |   |-- images
    |   |   |-- blackbird_icons.png
    |   |   |-- blackbird_panel.png
    |   |   |-- productimage-picture-default.jpg
    |   |   |-- productimage-picture-default_jpg_85x85_q85.jpg
    |   |   `-- sample-logo.bmp
    |   `-- js
    |       |-- blackbird.js
    |       |-- jquery.ajaxQueue.js
    |       |-- jquery.autocomplete.js
    |       |-- jquery.bgiframe.js
    |       |-- jquery.cookie.js
    |       |-- jquery.form.js
    |       |-- jquery.js
    |       |-- satchmo_checkout.js
    |       |-- satchmo_pay_ship.js
    |       |-- satchmo_product.js
    |       `-- satchmo_store.js
    |-- templates

Test and Install the Data

  1. Now, you should be ready to go. In order to test your Satchmo setup, execute the following command (from the mystore directory):

    python satchmo_check
    Checking your satchmo configuration.
    Your configuration has no errors.
  2. If any errors are identified, resolve them based on the error description.

  3. Sync the new satchmo tables:

    python syncdb
  4. Load the country data stored in the l10n application:

    python satchmo_load_l10n
  5. (Optional) Load the demo store data:

    python satchmo_load_store
  6. (Optional) Load the US tax table:

    python satchmo_load_us_tax