Setting up Eclipse for Python Development and Debugging with Google App Engine

Get started with local development and debugging with Eclipse and the PyDev plugins. This configuration allows you to run your App Engine app locally in a debug mode and use Eclipse’s Debug perspective to set breakpoints and step through your code. The PyDev plugins provide helper functionality for working with App Engine, including creating starter projects and deploying apps.

Before you begin

  1. Install Python 2.7 if you do not already have Python installed. Not sure?
  2. Install the App Engine Python SDK.

Check your version of Python

To check which version of Python that you have installed, run the following command:

python --version

Installing Eclipse

The following instructions assume that you are going to install Eclipse IDE for JavaScript and Web Developers, which is based on Eclipse Neon (4.6). Use the Eclipse Installer to make the installation process easier.

  1. Install the Eclipse Installer.
  2. In the Eclipse Installer, choose the Eclipse IDE for JavaScript and Web Developers package and click Install.

    Installing Eclipse with the Eclipse installer

  3. When the installation finishes, click Launch.

  4. When Eclipse launches, specify a workspace location or accept the default.

Installing PyDev

After you install Eclipse, you should install the PyDev plugin that allows you to use Eclipse as a Python IDE.

  1. In Eclipse, click Help > Eclipse Marketplace.
  2. In the Find field, specify "PyDev".

    Search for PyDev in the Eclipse marketplace and install it.

  3. Click Install and complete the installation wizard.

  4. Restart Eclipse when prompted.

Configuring your project

  1. Create a new project: Click File > New > Project.

  2. On the Select a wizard page, select PyDev Google App Engine Project.

    Select the Pydev project wizard.

  3. On the PyDev Project page, name the project. Then, let Eclipse configure the default interpreter by clicking Please configure an interpreter before proceeding.

    If Eclipse did not find a Python 2.7 interpreter, click the Click here to configure an interpreter not listed link to configure the interpreter.

  4. On the Google App Engine page, click Browse and locate the directory where you installed the App Engine SDK. Where is it?

    Specify the App Engine SDK location when creating your project.

  5. Click Next to continue to configure a basic project or click Finish to start with a blank project.

  6. If you are configuring a project, specify an existing Cloud Platform Console project ID if you have already registered one. If not, you can specify a temporary name that will be inserted into the project’s app.yaml file. You can change this name later if necessary.
  7. Choose a starter template. Recommended: Use the Hello World template to generate an app.yaml file and a simple Python script. You can later develop using your choice of frameworks, such as Flask or Django.

    Note: The PyDev starter projects are out of date and use the Python 2.5 webapp module.

Default location of the SDK

Mac OS X
If you installed the SDK with the Google App Engine launcher, you are prompted to create symlinks when the launcher starts. If you created symlinks, the default location is:
If you did not create symlinks, the default location is:
The location is where you extracted the SDK zip file that you downloaded.
C:\Program Files (x86)\Google\google_appengine\</pre>

Importing libraries for Eclipse to recognize

After you set up a project, you might choose a library that your code will rely on. You will need to import the library into your project and configure your project to load that library, but you will also need to instruct Eclipse to use that library.

To have Eclipse recognize your imported library:

  1. Import the library to your project.
  2. Edit your Eclipse project’s properties: Right-click the project and select Properties.
  3. Select PyDev - PYTHONPATH in the navigation pane of the dialog.
  4. If you manage your libraries in a child folder of your project, such as lib\, click Add source folder.

Eclipse now adds your specified libraries onto the Python path for resolving imports.

Launching your app in debug mode

Running your app in debug mode in Eclipse allows you to set breakpoints in your code. When those lines are executed, processing pauses temporarily, allowing you to inspect your code and step through the execution. This functionality is extremely helpful during development of your app.

Setting up a debug configuration

The first time you launch your app in debug mode, it will create a debug configuration that you can execute later or modify to add parameters for your build.

  1. Right-click your project name in the project explorer and select Debug As > PyDev: Google App Run.

    The console view should open and display the system output of the development server, which includes the URLs that your app is running.

  2. Verify that your app is running by visiting the URL shown in the console. By default, the app runs from http://localhost:8080. If you used the Hello World starter template, you should see "Hello, world!" printed to the browser.

Debug mode is now running within Eclipse. You also created a Debug configuration that you can run again later if you leave Eclipse or need to stop and restart the debugger.

Setting a breakpoint to step through your code

Now that you have the debugger running, you can set breakpoints and use them to step through your code execution.

  1. Open a file in your Eclipse project, such as the file if you are using the starter template.

  2. Right-click the line number next to the code where you want to set a breakpoint and select Add Breakpoint.

    The context menu that displays when right clicking on the line
  number in Eclipse

    A green circle appears on the line where you set the breakpoint.

  3. Return to the browser and open the URL that will run the line where you set the breakpoint. Eclipse asks you to switch to the Debug perspective when the breakpoint is triggered.

  4. If you are prompted to switch to the Debug perspective, click Yes. This perspective provides a debugging-specific view of your code, including the Variables view.

    A full screenshot of the Eclipse IDE in debug mode with the various
  debugging views.

    In the Variables viewer, you can inspect the objects and variables that are currently defined in your code.

    The menu bar buttons provide the following controls:

    • Icon for
     continuing execution Continues execution until the next breakpoint is encountered or execution finishes.
    • Icon for continuing execution Step into lower level code, such as into a method.
    • Icon for stepping line by line Step line by line in the current code rather than going into lower level code.
    • Icon for returning to the higher code Step return to higher level code. If you step into lower level code, you might choose to return back to the higher level code before that lower level code finishes its execution to return you back to the calling code.
    • Icon for terminating execution Terminate the execution.
    • Icon for skipping remaining breakpoints Skip remaining breakpoints.
  5. Click the continue icon (continue icon) to continue process and allow the development server to send a simple "Hello, World!" response to the browser.

To switch back to the PyDev perspective after you are finished debugging, choose Window > Perspective > Open Perspective and choose Pydev. Or, click the PyDev icon in the top right corner of Eclipse:

Displays the icons for quick switching perspectives in Eclipse

Deploying your app from Eclipse

The PyDev plugin for Eclipse allows you to deploy your app from your workspace.

  1. Select or create a new Cloud Platform project and ensure it includes an App Engine application:

    Go to App Engine

    The Dashboard opens if an App Engine application already exists in your project. Otherwise, you are prompted to choose the region where you want your App Engine application located.

    Tip: Your project's ID becomes part of your app's URL, for example, http://[YOUR_PROJECT_ID]

  2. Edit your app.yaml file and change the value of the application element to your project ID.

  3. In the PyDev Package Explorer or Project Explorer view, right-click the project folder and choose PyDev Google App Engine > Upload.

    Image of the context menu when right clicking on the project to
  display the PyDev upload option for App Engine

    If this is your first time running the App Engine SDK management commands, you will be prompted to authorize the SDK to grant access to the tool to modify your App Engine applications. Click Allow.

    You can close the browser window when it says "The authentication flow has completed" and return to Eclipse.

  4. Confirm that your application uploads successully in the Manage Google App Engine dialog:

    Screenshot of the dialog confirming the upload steps and success

  5. Browse to http://[YOUR_PROJECT_ID] and you should see your application serving traffic.

Next steps

Now that you have a development environment set up, the following topics can help you get started with App Engine:

Send feedback about...

App Engine standard environment for Python