djangocore-box: A virtual machine for running the Django core test suite

The djangocore-box is a virtual machine (VM) containing all the programs and libraries required for running the Django core test suite in multiple different environments. Every supported version of Python (2.4, 2.5, 2.6, 2.7 and 3.3) is pre-installed as well as every supported database backend (SQLite, Spatialite, MySQL, PostgreSQL and PostGIS — Oracle is coming soon), all the GeoDjango dependencies and a number of third-party components such as Memcached and Python libraries like Sphinx, the Python Imaging Library, Textile and Markdown.

This is particularly useful to anybody interested in contributing to Django core without having to go through the trouble of installing and configuring all the software required to run the tests in all these environments.


Software installation

First of all, you need to install the latest versions of Vagrant and VirtualBox on your host machine.

Adding SSH keys to ssh-agent

SSH-Agent will allow you to share the ssh keys on your host machine with the VM. This will then allow you to authenticate to remote servers, like github for example, from inside the VM.

First, check if your keys are added to ssh-agent:

ssh-add -l

If you don't have any keys, or the key you want available to the VM is not listed, you can add your key by running the following:

ssh-add <path_to_key>


ssh-add ~/.ssh/id_rsa

Booting the VM

Legend: (host) is for commands to run on the host machine, and (vm) is for commands to run inside the VM.

Setup the initial directory layout:

(host) $ mkdir djangocore
(host) $ cd djangocore
(host) $ git clone  # or replace django/django.git by <your username>/django.git if you have your own fork
(host) $ git clone
(host) $ mkdir sandbox

Then, either:

  • If you have not already downloaded the box file separately, then run the following commands to boot the machine.

      (host) $ cd djangocore-box
      (host) $ vagrant up

    This will automatically download the VM, which is about 1GB in size (be warned if you have a low bandwitdh Internet connection) and then boot it up. The download will only occur the first time you run vagrant up. Every subsequent times, it will just boot the VM, which only takes about 30 seconds.

  • Or, if you have already downloaded the box file separately (say, for example someone gave it to you via a flash drive), then run the following command in order to import the box into vagrant and boot up the VM:

      (host) $ vagrant box add djangocore-box-1.1 path/to/your/local/copy/of/
      (host) $ cd djangocore-box
      (host) $ vagrant up

    vagrant box add will copy the box file to ~/.vagrant.d/boxes, so you may delete the file you've dowloaded if you'd like to save some space on your hard drive.

As the VM boots up, it will prompt you to enter your host machine's administrator password (the same that you use for logging into your host machine). This is required so that Vagrant can setup the NFS shared folders.

Once the VM is up and running, type the following command to SSH into the VM (still from inside the djangocore-box/ folder):

(host) $ vagrant ssh

Once inside the VM, you can run the tests by typing any of the pre-defined aliases: runtests{2.4,2.5,2.6,2.7,3.3}-{sqlite,mysql,postgresql,spatialite,postgis}. For example:

(vm) $ runtests2.6-mysql
(vm) $ runtests2.7-spatialite gis
(vm) $ runtests2.5-postgresql auth forms

Building the VM from scratch

You probably don't need to build the VM from scratch, but if you really want it, the steps are still pretty simple. First, rename the file Vagrantfile to a temporary name (e.g. Vagrantfile-backup) and then rename the file Vagrantfile-build to Vagrantfile. Then run vagrant up. The automatic build process will take about an hour. Use that time to do other work, browse the web or go out for a nice stroll in the park!

Sandbox directory

In some cases, you will want to expose test projects, or test code to your host machine. The sandbox directory on the host is mapped to the /sandbox directory on the vagrant managed VM.

Any projects or code you create in /sandbox will be available in the djangocore/sandbox directory.

Notes about the VM configuration

Inside the VM, the /django folder is shared with the host and points to the git clone that was created in the steps above. The repository clone for the djangocore-box itself is also in a shared folder at /djangocore-box. This way you can edit Django's code using your favorite editor/IDE from your host machine and run the tests from inside the VM.

The various versions of python are installed in the /opt folder. The virtualenvs are named py{2.4,2.5,2.6,2.7,3.3} and are installed under /home/vagrant/.virtualenvs/.

virtualenvwrapper is also installed so you may run, for example:

(vm) $ workon py3.3

You should be able to push commits to your fork of django on github directly from inside the VM, as the SSH and git configuration files inside the VM are automatically symlinked to the corresponding files on your host machine. You may push those commits from the host machine too.

The test settings are available in /djangocore-box/test_settings/test_*.py. These files are available in every virtualenv via symlinks.

Firefox is pre-installed so that Django's selenium tests can be run in headless mode in a virtual display (with the id :99). For example, you may run a specific test like so:

(vm) $ runtests2.6-sqlite admin_inlines.tests.SeleniumFirefoxTests --selenium

The VM is based on a Ubuntu 12.04 LTS 64 bits distribution.

Building the documentation

To build the documentation, simply activate one of the virtualenvs and run the Sphinx build command:

workon py2.7
cd /django/docs
make html

Vagrant command tips

  • To exit the VM and return to your host machine, simple type:

    (vm) $ exit

  • To shutdown the VM, type:

    (host) $ vagrant halt

  • To suspend the VM (i.e. freeze the VM's state), type:

    (host) $ vagrant suspend

  • Once shutdown or suspended, a VM can be restarted with:

    (host) $ vagrant up

  • To destroy the VM, simply type:

    (host) $ vagrant destroy

  • To check if the VM is currently running, type:

    (host) $ vagrant status

  • To re-run the provisioning after the VM has been started (if you have built the VM from scratch):

    (host) $ vagrant provision

  • More information is available in the Vagrant documentation.


  • Install the Oracle backend.


djangocore-box was authored by Julien Phalip and other contributors.


djangocore-box: A virtual machine for running the Django core test suite

djangocore-box是一个包含所有程序的虚拟机(VM) 运行Django核心测试套件所需的库是多种不同的 环境。每个受支持的Python版本(2.4,2.5,2.6,2.7和3.3)是 预安装以及每个支持的数据库后端(SQLite,Spatialite, MySQL,PostgreSQL和PostGIS - Oracle即将推出),所有的GeoDjango 依赖关系和许多第三方组件,如Memcached和 Python图书馆如Sphinx,Python Imaging Library,Textile和Markdown。

对于有兴趣贡献Django的人来说,这是特别有用的 核心,无需经历安装和配置的麻烦 在所有这些环境中运行测试所需的软件。



首先,您需要安装最新版本 Vagrant 和 主机上的 VirtualBox


SSH-Agent将允许您与主机上的ssh密钥共享 虚拟机这将允许您对远程服务器(如github)进行身份验证 例如,从VM内部。


ssh-add -l

如果您没有任何密钥,或者您希望VM可用的密钥不是 列出,您可以通过运行以下命令来添加密钥:

ssh-add <path_to_key>


ssh-add ~/.ssh/id_rsa


图例说明: (host)用于在主机上运行命令,(vm) 用于在VM中运行的命令。


(host) $ mkdir djangocore
(host) $ cd djangocore
(host) $ git clone  # or replace django/django.git by <your username>/django.git if you have your own fork
(host) $ git clone
(host) $ mkdir sandbox


  • 如果您尚未分别下载Box文件,请运行 以下命令来引导机器。

     (host)$ cd djangocore-box
      (主机)$ vagrant up

    这将自动下载大小为1GB 的虚拟机 警告,如果你有一个低bandwitdh互联网连接),然后启动它。 下载仅在您第一次运行 vagrant up 时才会发生。每一个 随后的时候,它只会引导虚拟机,这只需要大约30个 秒。

  • 或者,如果您已经单独下载了盒子文件(例如说) 有人通过闪存驱动器给你),然后运行以下命令 要将该盒子导入vagrant并启动VM:

    添加djangocore-box-1.1路径/ to / your / local / copy / of / djangocore-box-1.1.box中的
     (host)$ vagrant box
      (主机)$ cd djangocore-box
      (主机)$ vagrant up

    vagrant box add 将复制框文件到〜/ .vagrant.d / boxes ,所以你可以 如果您要保存一些空间,请删除您下载的文件 硬盘。

当虚拟机启动时,将提示您输入主机 管理员密码(与您用于登录主机的密码相同) 机)。这是必需的,以便Vagrant可以设置NFS共享文件夹。

一旦虚拟机启动并运行,键入以下命令SSH到虚拟机 (仍然在 djangocore-box / 文件夹内):

(host) $ vagrant ssh
一旦进入虚拟机,您可以通过键入任何预定义来运行测试 别名: runtests {2.4,2.5,2.6,2.7,3.3} - {sqlite,mysql,postgresql,spatialite,postgis} 。 例如:

(vm) $ runtests2.6-mysql
(vm) $ runtests2.7-spatialite gis
(vm) $ runtests2.5-postgresql auth forms


您可能不需要从头构建虚拟机,但如果您真的想要的话 它的步骤还是很简单的。首先,将文件 Vagrantfile 重命名为 一个临时名称(例如 Vagrantfile-backup ),然后重命名该文件 Vagrantfile-build Vagrantfile 。然后运行 vagrant up 。自动 构建过程大约需要一个小时。用这个时间做其他的工作,浏览 网路或出去散步在公园!


在某些情况下,您将需要公开测试项目,或测试代码到您的主机 机。主机上的 sandbox 目录映射到 / sandbox vagrant托管虚拟机上的目录。

/ sandbox 中创建的任何项目或代码将可用 djangocore / sandbox 目录。


在虚拟机内, / django 文件夹与主机共享,并指向 在上述步骤中创建的git克隆。存储库克隆为 djangocore-box本身也位于 / djangocore-box 的共享文件夹中。这条路 您可以使用主机上最喜欢的编辑器/ IDE编辑Django的代码 机器,并从VM内部运行测试。

各种版本的python安装在 / opt 文件夹中。的 virtualenvs命名为 py {2.4,2.5,2.6,2.7,3.3} ,并安装在 /home/vagrant/.virtualenvs /

virtualenvwrapper 也可以运行,例如:

(vm) $ workon py3.3
你应该可以直接在github上将提交到django的fork 从VM内部,作为VM中的SSH和git配置文件 自动符号链接到主机上的相应文件。您 可能会从主机推送这些提交。

测试设置在 / djangocore-box / test_settings / test _ *。py 中可用。 这些文件可通过符号链接在每个virtualenv中使用。

预先安装Firefox,以便Django的硒测试可以无头进行 虚拟显示模式(id :99 )。例如,您可以运行一个 具体测试如下:

(vm) $ runtests2.6-sqlite admin_inlines.tests.SeleniumFirefoxTests –selenium

该虚拟机基于Ubuntu 12.04 LTS 64位分发。


要构建文档,只需激活一个virtualenvs并运行 Sphinx构建命令:

workon py2.7
cd /django/docs
make html


  • 要退出虚拟机并返回主机,请简单输入:

    (vm)$ exit

  • 要关闭虚拟机,请键入:

    (host)$ vagrant halt

  • 要挂起虚拟机(即冻结虚拟机的状态),请键入:

    (host)$ vagrant suspend

  • 一旦关机或暂停,可以通过以下方式重新启动VM:

    (host)$ vagrant up

  • 要销毁VM,只需键入:

    (host)$ vagrant destroy

  • 要检查虚拟机当前是否正在运行,请键入:

    (host)$ vagrant status

  • 在虚拟机启动后重新运行配置(如果已经构建) VM从头开始):

    (host)$ vagrant provision

  • Vagrant文​​档中提供了更多信息。


  • 安装Oracle后端。


djangocore-box由 Julien Phalip 创作 和其他贡献者