You are not logged in Log in Join
You are here: Home » Download Zope Products » Zope Object Database (ZODB) 3.2 » README » View Document

Log in




ZODB3 3.2.10

ZODB3 3.2.10


The ZODB3 package provides a set of tools for using the Zope Object Database (ZODB) in Python programs separately from Zope. The tools you get are identical to the ones provided in Zope, because they come from the same source repository. They have been packaged for use in non-Zope stand-alone Python applications.

The components you get with the ZODB3 release are as follows:

  • Core ZODB, including the persistence machinery
  • Standard storages such as FileStorage
  • Supporting modules such as ExtensionClass
  • The persistent BTrees modules
  • ZEO
  • ZConfig -- a Zope configuration language
  • documentation
  • Experimental Berkeley storages (while the code for this still exists in this release, the experiment has been dropped, and the BDB-based storages no longer exist in ZODB 3.3)

Our primary development platforms are Linux and Windows XP. The test suite should pass without error on all of these platforms, although it can take a long time on Windows -- longer if you use ZoneAlarm. Many particularly slow tests are skipped unless you pass --all as an argument to


ZODB 3.2.10 requires Python 2.3.3 or later. For best results, we recommend using Python 2.3.5. Python 2.4.1+ may also be used.

This version of ZODB can be used with Zope 2.7.3 or later, but you must replace the version of ZODB that comes packaged with Zope. It should be possible, for example, to install this code into a Zope 2.7 software home.

The Zope 2.7.3 through 2.7.7 releases are compatible with this version of ZODB. Note that Zope 2.7 includes ZEO, so this package should only be needed to run a ZEO server.

The ZEO server in ZODB 3.2 is partially compatible with ZODB 3.1. A new client can talk to an old server, but a new server can not talk to an old client. If you want to upgrade without shutting down all components, you should upgrade all of the clients first. Once all the clients are running the new software, you can safely upgrade the server.


You must have Python installed. If you've installed Python from RPM, be sure that you've installed the development RPMs too, since ZODB3 builds Python extensions. If you have the source release of ZODB3, you will need a C compiler.

If you intend to use the experimental Berkeley storages, you will need to install the Berkeley database software and PyBSDDB, the next generation of Berkeley DB Python wrapper. It is recommended that you use at least Berkeley 4.1.25 and PyBSDDB 4.1.3.

The ZConfig package requires an XML parser with SAX support. If you have Python 2.1, you should probably install the PyXML package. If you have Python 2.2, the pyexpat module should be sufficient; note that pyexpat requires expat be installed.


ZODB3 is released as a distutils package. To build it, run the setup script:

% python build

To test the build, run the test script:

% python

For more verbose test output, append one or two '-v' arguments to this command.

If all the tests succeeded, you can install ZODB3 using the setup script:

% python install

This should now make all of ZODB accessible to your Python programs. You can test this by cd'ing to your home directory and typing the following commands:

Python 2.3.5 (#11, Jan  7 2005, 10:06:56)
[GCC 3.2.2 20030222 (Red Hat Linux 3.2.2-5)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import ZODB
>>> ZODB.__version__


ZODB3 comes with a large test suite that can be run from the source directory before ZODB is installed. The simplest way to run the tests is:

% python -v

This command will run all the tests, printing a single dot for each test. When it finishes, it will print a test summary. The exact number of tests can vary depending on platform and available third-party libraries.:

Ran 1182 tests in 241.269s


The test script has many more options. Use the -h or --help options to see a file list of options. The default test suite omits several tests that depend on third-party software or that take a long time to run. To run all the available tests use the --all option. Running all the tests takes much longer.:

Ran 1577 tests in 1601.557s



The version numbering scheme for ZODB is complicated. Starting with this release, we are trying to make it simpler. This is release 3.1.1 of the package named ZODB3. Versions prior to 3.1 had different names and different numbers. This section describes the gory details.

Historically, ZODB was distributed as a part of the Zope application server. Jim Fulton's paper at the Python conference in 2000 described a version of ZODB he called ZODB 3, based on an earlier persistent object system called BoboPOS. The earliest versions of ZODB 3 were released with Zope 2.0.

Andrew Kuchling extracted ZODB from Zope 2.4.1 and packaged them for use by standalone Python programs. He called this version "StandaloneZODB". Andrew's guide to using ZODB is included in the Doc directory. This version of ZODB was hosted at It supported Python 1.5.2, and might still be of interest to users of this very old Python version.

Zope Corporation released a version of ZODB called "StandaloneZODB 1.0" in Feb. 2002. This release was based on Andrew's packaging, but built from the same CVS repository as Zope. It is roughly equivalent to the ZODB in Zope 2.5.

Why not call the current release StandaloneZODB 1.1? The name StandaloneZODB is a bit of a mouthful. The standalone part of the name suggests that the Zope version is the real version and that this is an afterthought, which isn't the case. Finally, we started work on ZODB4 -- a major new version based on Python 2.2 new-style types instead of ExtensionClass. So we're calling this release "ZODB3". We settled on the 3.1 version number so that we don't create the impression that this version of ZODB is the same as the one Jim described as ZODB 3 in 2000.


ZODB is distributed under the Zope Public License, an OSI-approved open source license. Please see the LICENSE.txt file for terms and conditions.

The ZODB/ZEO Programming Guide included in the documentation is a modified version of Andrew Kuchling's original guide, provided under the terms of the GNU Free Documentation License.

More information

We maintain a Wiki page about all things ZODB, including status on future directions for ZODB. Please see

and feel free to contribute your comments. There is a Mailman mailing list in place to discuss all issues related to ZODB. You can send questions to

or subscribe at

and view its archives at

Andrew's ZODB Programmers Guide is made available in several forms, including DVI and HTML. To view it online, point your browser at the file Doc/guide/zodb/index.html

Bugs and Patches

Bug reports and patches should be added to the Zope Collector, with topic "Database":