Skip to content
Go to file


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


pgAdmin 4 

pgAdmin 4 is a rewrite of the popular pgAdmin3 management tool for the
PostgreSQL ( database. 

In the following documentation and examples, "$PGADMIN4_SRC/" is used to denote
the top-level directory of a copy of the pgAdmin source tree, either from a
tarball or a git checkout.


pgAdmin 4 is written as a web application in Python, using jQuery and Bootstrap
for the client side processing and UI. On the server side, Flask is being

Although developed using web technologies, pgAdmin 4 can be deployed either on
a web server using a browser, or standalone on a workstation. The runtime/
subdirectory contains a QT based runtime application intended to allow this -
it is essentially a Python application server that runs in the system tray
and allows the user to connect to the application using their web browser.

Building the Runtime

To build the runtime, the following packages must be installed:

- QT 5 (Use the VC++ build on Windows, not MinGW).
- Python 3.4+

An environment variable named PGADMIN_PYTHON_DIR must be set to the directory
in which Python has been installed, for example:

- /usr
- /usr/local/python-3.8
- C:\Python38

Assuming both qmake is in the path:

  dpage@hal:~/git/pgadmin4$ cd runtime
  dpage@hal:~/git/pgadmin4/runtime$ export PGADMIN_PYTHON_DIR=/opt/local
  dpage@hal:~/git/pgadmin4/runtime$ qmake
  Project MESSAGE: ==================================
  Project MESSAGE: Configuring the pgAdmin 4 runtime.
  Project MESSAGE: ==================================
  Project MESSAGE: Qt version: 5
  Project MESSAGE: Platform: macOS
  Project MESSAGE: Python executable: /opt/local/bin/python3
  Project MESSAGE: Python version: 3.8 (38)
  Project MESSAGE: Python config: /opt/local/bin/python3-config
  Project MESSAGE: CXXFLAGS: -pipe -stdlib=libc++ -I/opt/local/Library/Frameworks/Python.framework/Versions/3.8/include/python3.8 -I/opt/local/Library/Frameworks/Python.framework/Versions/3.8/include/python3.8
  Project MESSAGE: LDFLAGS: -stdlib=libc++ -L/opt/local/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/config-3.8-darwin -ldl -framework CoreFoundation
  Project MESSAGE: LIBS: -lpython3.8 -ldl -framework CoreFoundation
  dpage@hal:~/git/pgadmin4/runtime$ make

To build the runtime in debug mode, use the option below with qmake:
$ qmake CONFIG+=debug

To build the runtime in release mode, use the option below with qmake:
$ qmake CONFIG+=release

By default, the runtime application will be built in release mode.

On Linux, an executable called 'pgAdmin4' will be built, on Windows,
'pgAdmin4.exe', and on Mac OS X, an app bundle called will be

You can also use Qt Creator to build, develop and debug the runtime. Simply
open the $PGADMIN4_SRC/runtime/ project file in Qt Creator and
configure the project with a supported version of Qt when prompted.

Create Database Migrations

In order to make changes to the SQLite DB, navigate to the 'web' directory:

(pgadmin4) $ cd $PGADMIN4_SRC/web

Create a migration file with the following command:

(pgadmin4) $ flask db revision

This will create a file in: $PGADMIN4_SRC/web/migrations/versions/ .
Add any changes to the 'upgrade' function.
Increment the SCHEMA_VERSION in $PGADMIN4_SRC/web/pgadmin/model/ file.

There is no need to increment the SETTINGS_SCHEMA_VERSION.

Configuring the Python Environment

In order to run the Python code, a suitable runtime environment is required.
Python version 3.4 and later are currently supported. It is recommended that a
Python Virtual Environment is setup for this purpose, rather than using the
system Python environment. On Linux and Mac systems, the process is fairly
simple - adapt as required for your distribution:

1) Install the virtualenv packages into the system Python environment

    $ sudo pip install virtualenv virtualenvwrapper

2) Source the virtualenv wrapper tools script. You may want to add this command
   to your ~/.bash_profile file for future convenience:

    $ source /usr/local/bin/

3) Create a virtual environment:

    $ mkvirtualenv pgadmin4

   To make use of the virtual environment in the future, use the following
   command to re-activate it:

    $ workon pgadmin4

4) Ensure that a PostgreSQL installation's bin/ directory is in the path (so
   pg_config can be found for building psycopg2), and install the required

    (pgadmin4) $ PATH=$PATH:/usr/local/pgsql/bin pip install -r $PGADMIN4_SRC/requirements.txt

   If you are planning to run the regression tests, you also need to install
   additional requirements from web/regression/requirements.txt:

   (pgadmin4) $ pip install -r $PGADMIN4_SRC/web/regression/requirements.txt

5) Create a local configuration file for pgAdmin. Edit
   $PGADMIN4_SRC/web/ and add any desired configuration options
   (use the file as a reference - any settings duplicated in will override those in A typical development
   configuration may look like:

    from config import *

    # Debug mode
    DEBUG = True

    # App mode
    SERVER_MODE = True

    # Enable the test module

    # Log



    # Use a different config DB for each server mode.
    if SERVER_MODE == False:
        SQLITE_PATH = os.path.join(
        SQLITE_PATH = os.path.join(

   This configuration allows easy switching between server and desktop modes
   for testing.

6) The initial setup of the configuration database is interactive in server
   mode,  and non-interactive in desktop mode. You can run it either by

    (pgadmin4) $ python $PGADMIN4_SRC/web/

   or by starting pgAdmin 4:

    (pgadmin4) $ python $PGADMIN4_SRC/web/

   Whilst it is possible to automatically run setup in desktop mode by running
   the runtime, that will not work in server mode as the runtime doesn't allow
   command line interaction with the setup program.

At this point you will be able to run pgAdmin 4 from the command line in either
server or desktop mode, and access it from a web browser using the URL shown in
the terminal once pgAdmin has started up.

Setup of an environment on Windows is somewhat more complicated unfortunately,
please see pkg/win32/README.txt for complete details.

Once a virtual environment has been created and enabled, setup can continue
from step 4 above.

Building the Web Assets

pgAdmin is dependent on a number of third party Javascript libraries. These,
along with it's own Javascript code, SCSS/CSS code and images must be
compiled into a "bundle" which is transferred to the browser for execution
and rendering. This is far more efficient than simply requesting each
asset as it's needed by the client.

To create the bundle, you will need the 'yarn' package management tool to be
installed. Then, you can run the following commands on a *nix system to
download the required packages and build the bundle:

    (pgadmin4) $ cd $PGADMIN4_SRC
    (pgadmin4) $ make install-node
    (pgadmin4) $ make bundle

On Windows systems (where "make" is not available, the following commands
can be used:

    C:\> cd $PGADMIN4_SRC\web
    C:\$PGADMIN4_SRC\web> yarn install
    C:\$PGADMIN4_SRC\web> yarn run bundle

Creating pgAdmin themes

To create a pgAdmin theme, you need to create a directory under
Copy the sample file _theme.variables.scss.sample to the new directory and
rename it to _theme.variables.scss. Change the desired hexadecimal values of
the colors and bundle pgAdmin. You can also add a preview image in the theme
directory with the name as <dir name>_preview.png. It is recommended that the
preview image should not be larger in size as it may take time to load on slow
networks. Run the yarn run bundle and you're good to go. No other changes are
required, pgAdmin bundle will read the directory and create other required
entries to make them available in preferences.

The name of the theme is derived from the directory name. Underscores (_) and
hyphens (-) will be replaced with spaces and the result will be camel cased.

Configuring the Runtime

The pgAdmin 4 Runtime maintains it's own Python Path to avoid conflicts with
packages or other issues in the system Python installation. It will also search
a number of known locations for the file needed to run pgAdmin
(including relative locations in a source code tree), however you can specify
an alternate path if needed.

If either a working environment or cannot be found at startup, the
runtime will prompt for the locations. Alternatively, you can click the try
icon and select the Configuration option to open the configuration dialogue.

On a Linux/Mac system, the Python Path will typically consist of a single path
to the virtual environment's site-packages directory, e.g.


On Windows, multiple paths are likely to be required, e.g.


If you wish to specify a specific copy of the Python code to run, you can set
the  Application Path to a directory containing, e.g.


Building the documentation

In order to build the docs, an additional Python package is required in the
virtual environment. This can be installed with the pip package manager:

    $ workon pgadmin4
    (pgadmin4) $ pip install Sphinx

The docs can then be built using the Makefile in $PGADMIN4_SRC, e.g.

    (pgadmin4) $ make docs

The output can be found in $PGADMIN4_SRC/docs/en_US/_build/html/index.html

Building packages

Most packages can be built using the Makefile in $PGADMIN4_SRC, provided all
the setup and configuration above has been completed.

To build a source tarball:

    (pgadmin4) $ make src

To build a PIP Wheel, activate either a Python 2 or Python 3 virtual
environment as desired, configured with all the required packages, and then

    (pgadmin4) $ make pip

To build the macOS AppBundle, please see pkg/mac/README.

To build the Windows installer, please see pkg/win32/README.txt.


See for support options.

Project info

The source code repository can be found here:;a=summary

A Redmine project for pgAdmin 4 can be found at the address below. A PostgreSQL
community account is required to access this site. Please note that at present
only project developers can log bug and feature requests:

If you wish to discuss pgAdmin 4, or contribute to the project, please use the
pgAdmin Hackers mailing list:

Dave Page
pgAdmin Project Lead


Mirror of the pgAdmin 4 GIT repo. DO NOT submit pull requests here! Use the mailing list. Issues should be logged at




No packages published
You can’t perform that action at this time.