Installing and Testing — peewee 3.9.3 documentation

# Installing and Testing

Most users will want to simply install the latest version, hosted on PyPI:

    pip install peewee

Peewee comes with a couple C extensions that will be built if Cython is available.

- Sqlite extensions, which includes Cython implementations of the SQLite date manipulation functions, the REGEXP operator, and full-text search result ranking algorithms.

## Installing with git

The project is hosted at https://github.com/coleifer/peewee and can be installed using git:

    git clone https://github.com/coleifer/peewee.git
    cd peewee
    python setup.py install

Note

On some systems you may need to use `sudo python setup.py install` to install peewee system-wide.

If you would like to build the SQLite extension in a git checkout, you can run:

    # Build the C extension and place shared libraries alongside other modules.
    python setup.py build_ext -i

## Running tests

You can test your installation by running the test suite.

    python runtests.py

You can test specific features or specific database drivers using the `runtests.py` script. To view the available test runner options, use:

    python runtests.py --help

Note

To run tests against Postgres or MySQL you need to create a database named “peewee_test”. To test the Postgres extension module, you will also want to install the HStore extension in the postgres test database:

    -- install the hstore extension on the peewee_test postgres db.
    CREATE EXTENSION hstore;

## Optional dependencies

Note

To use Peewee, you typically won’t need anything outside the standard library, since most Python distributions are compiled with SQLite support. You can test by running `import sqlite3` in the Python console. If you wish to use another database, there are many DB-API 2.0-compatible drivers out there, such as `pymysql` or `psycopg2` for MySQL and Postgres respectively.

- Cython: used to expose additional functionality when using SQLite and to implement things like search result ranking in a performant manner. Since the generated C files are included with the package distribution, Cython is no longer required to use the C extensions.
- apsw: an optional 3rd-party SQLite binding offering greater performance and comprehensive support for SQLite’s C APIs. Use with `APSWDatabase`.
- gevent is an optional dependency for `SqliteQueueDatabase` (though it works with `threading` just fine).
- BerkeleyDB can be compiled with a SQLite frontend, which works with Peewee. Compiling can be tricky so here are instructions.
- Lastly, if you use the Flask framework, there are helper extension modules available.

## Note on the SQLite extensions

Peewee includes two SQLite-specific C extensions which provide additional functionality and improved performance for SQLite database users. Peewee will attempt to determine ahead-of-time if SQLite3 is installed, and only build the SQLite extensions if the SQLite shared-library is available on your system.

If, however, you receive errors like the following when attempting to install Peewee, you can explicitly disable the compilation of the SQLite C extensions by settings the `NO_SQLITE` environment variable.

    fatal error: sqlite3.h: No such file or directory

Here is how to install Peewee with the SQLite extensions explicitly disabled:

    $ NO_SQLITE=1 python setup.py install