Docs in progress for ‘QGIS testing’. Visit for QGIS 2.18 docs and translations.

Loading Projects


Despite our constant efforts, information beyond this line may not be updated for QGIS 3. Refer to for the python API documentation or, give a hand to update the chapters you know about. Thanks.

Sometimes you need to load an existing project from a plugin or (more often) when developing a stand-alone QGIS Python application (see: Python Applications).

To load a project into the current QGIS application you need a QgsProject instance() object and call its read() method passing to it a QFileInfo object that contains the path from where the project will be loaded:

# If you are not inside a QGIS console you first need to import
# qgis and PyQt4 classes you will use in this script as shown below:
from qgis.core import QgsProject
from qgis.PyQt.QtCore import QFileInfo
# Get the project instance
project = QgsProject.instance()
# Print the current project file name (might be empty in case no projects have been loaded)
# Load another project'/home/user/projects/my_other_qgis_project.qgs'))

In case you need to make some modifications to the project (for example add or remove some layers) and save your changes, you can call the write() method of your project instance. The write() method also accepts an optional QFileInfo that allows you to specify a path where the project will be saved:

# Save the project to the same
# ... or to a new file

Both read() and write() funtions return a boolean value that you can use to check if the operation was successful.


If you are writing a QGIS standalone application, in order to synchronise the loaded project with the canvas you need to instanciate a QgsLayerTreeMapCanvasBridge as in the example below:

bridge = QgsLayerTreeMapCanvasBridge( \
         QgsProject.instance().layerTreeRoot(), canvas)
# Now you can safely load your project and see it in the canvas'/home/user/projects/my_other_qgis_project.qgs'))