Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

ZODB Browser

buildstatus appveyor coverage

The ZODB browser allows you to inspect persistent objects stored in the ZODB, view their attributes and historical changes made to them.


ZODB is based on Python pickles, which are not secure -- they allow arbitrary command execution. Do not use zodbbrowser on databases from untrusted sources.

Usage as a standalone project

Install zodbbrowser into a virtualenv alongside your application code

pip install zodbbrowser

Run zodbbrowser specifying either a filename or a ZEO address

zodbbrowser /path/to/Data.fs
zodbbrowser --zeo localhost:9080
zodbbrowser --zeo /path/to/zeosock

If you don't have a spare Data.fs to test with, you can create a new empty one with just the barest Zope 3 scaffolding in it:

zodbbrowser empty.fs --rw

Open http://localhost:8070 in a web browser. Note that there are no access controls; all other users on the local machine will be able to access the database contents.

Command-line options

Run zodbbrowser --help to see a full and up-to-date list of command-line options:

Usage: zodbbrowser [options] [FILENAME | --zeo ADDRESS]

Open a ZODB database and start a web-based browser app.

  -h, --help        show this help message and exit
  --zeo=ADDRESS     connect to ZEO server instead
  --listen=ADDRESS  specify port (or host:port) to listen on
  --rw              open the database read-write (allows creation of the
                    standard Zope local utilities if missing)

Help! Broken objects everywhere

If you don't want to see <persistent broken ...> everywhere, make sure your application objects are importable from the Python path. The easiest way of doing that is adding zodbbrowser to your application's buildout (or virtualenv, if you use virtualenvs). This way your application (or Zope's) nice __repr__ will also be used.

Online help

There's a little 'help' link in the bottom-right corner of every page that describes the user interface in greater detail.

Usage as a plugin

Add zodbbrowser to the list of eggs (e.g. in buildout.cfg of your app) and add this to your site.zcml:

<include package="zodbbrowser" />

Rerun bin/buildout, restart Zope and append @@zodbbrowser to the end of the URL to start browsing, e.g. http://localhost:8080/@@zodbbrowser. Or, if you still use ZMI (the Zope Management Interface), look for a new menu item titled "ZODB Browser".


There's a package called z3c.zodbbrowser in the Zope svn repository that implements the same idea (but without history browsing) as a GUI desktop application written using wxPython. It doesn't have a website and was never released to the Python Package Index.

There's also dm.historical which provides access to object history from an interactive Python shell.

If you're not interested in history or objects that cannot be reached through URL traversal, you can use the built-in object inspector that comes with Zope 3 / Grok.


ZODB Browser was developed by Tautvilas Mečinskas ( and Marius Gedminas ( from Programmers of Vilnius. It is licenced under the Zope Public Licence.

Please report bugs at

There's an old bugtracker at but I'd really rather prefer new bugs in GitHub.