ENV 859 - Geospatial Data Analytics   |   Fall 2026   |   Instructor: John Fay

Introduction

Python scripts are simply text files with a .py extension; you can open them and read them—even write them—in Notepad, WordPad, Notepad++, etc. However, working with Python scripts is more easily done in an integrated development environment (IDE) as these IDEs offer tools to auto-format scripts as you write them, debug them, and execute Python statements or chunks of scripts interactively.

Learning Objectives

Section On completion of this lesson, you should be able to:
1. Setting up theVS Code IDE Set up VS Code to work with the ArcGIS Pro installation of Python
2. Writing Python in VS Code Familiarize yourself with VS Code’s layout
Create a coding workspace in VS Code
Create and run a Python script file in VS code
3. Debugging in VS Code Use VS Code’s code tools to identify and address syntax errors
Run code in chunks or one line at a time to identify logical errors
Use the interactive Python terminal while debugging
Run code in Debug Mode

1. Setting up the VS Code IDE 🎞️

Our choice of IDE for this class will be Visual Studio Code, or VS Code. It is a free, popular, and powerful IDE that can be used with many scripting languages. It is installed on NSOE machines, but you are welcome to download and install it on your personal or virtual machines.

Task 1.1: Install Visual Studio Code

  1. Download the Windows installer file from https://code.visualstudio.com/ and run it.
  2. Select all defaults and continue until the software is installed.

Once installed, VS Code is not yet configured for Python, let alone ArcGIS Pro’s unique installation of Python. The tasks below guide you through this process. Once complete, these settings are saved to your local profile. (Note: If you move to a different machine, you may have to repeat this step as profiles don’t necessarily convey from machine to machine.)

Task 1.2: Install the Python and Jupyter Extensions

Our first task is to install the extensions required to run Python smoothly.

  1. Open the VS Code application.
  2. Open the Extensions pane by clicking the extensions icon (the last icon on the Activity Bar on the left side) or by pressing Ctrl+Shift+X.
  3. Search for and install the Python extension. Note that installing this may also install related tools like “Pylance”.
  4. Search for and install the Jupyter extension.

Task 1.3: Modify Settings for ArcGIS Pro Python and Beginner Friendliness

We need to tweak a few settings to enable VS Code to work smoothly with ArcGIS Pro’s version of Python and to prevent common beginner frustrations.

  1. Open the VS Code Settings (Ctrl+,).
  2. Search for terminal.activateEnvironment and de-select the Python > Terminal: Activate Environment setting.
  3. Search for python.REPL and de-select both Python.REPL:Enable REPLSmartSend and Python.REPL:Send to Native REPL.
  4. Search for jupyter.interactiveWindow.textEditor.executeSelection and select Jupyter > Interactive Windows > Text Editor.
  5. Search for python.terminal.executeInFileDir and select it. This ensures your terminal runs exactly where your file is saved, preventing “File Not Found” errors.
  6. Finally, navigate to the File menu at the very top of the screen and click Auto Save to turn it on. This eliminates the frustration of running old, unsaved versions of your code!

Task 1.4: Set the Python Interpreter

Next, we point VS Code to where Python is installed on our machine.

  1. Open the Command Palette (Ctrl+Shift+P) and type Python: Select Interpreter.
  2. Click 📂 Enter interpreter path..., then select Find....
  3. Enter the path exactly: C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe.

Task 1.5: Test the Python Installation

Let’s check that our installation is working.

  1. From the File menu, select New File.
  2. Specify the new file to be a Python File.
  3. Write some code that produces an output, such as: print("Hello World").
  4. Save the file (anywhere for now…).

  5. Run the file by clicking the right-facing triangle (►) in the upper right corner.

    ⚠️ Note: Run without Debugging (Ctrl+F5) used to be a viable alternative to hitting the ► button, but it now has slightly different behavior. Stick with hitting ► for now.

  6. Check that your code produces the correct output in the terminal window that pops up at the bottom of the screen.

🔥Optional: Set up VSCode to Synchronize settings across machines🔥🎞️

  1. Open your machines default browser and sign into https://github.com. (If you don’t have a GitHub account, now is the time to create one…)
  2. In VSCode, Select File > Preferences> Turn on Settings Sync….
  3. In the “Setting Sync” dialog box that appears, click the “Sign in & Turn on” button.
  4. You’ll be asked which account to use: GitHub or Microsoft. Select “Sign in with GitHub. “
  5. Follow the instructions to authenticate VS Code using GitHub. Typically, a browser window should appear asking you to Open Visual Studio Code, where you should click the button to do so.

👉Now if you go to a new machine and open VS Code, you can turn the “Settings Sync” to on and your local VS Code app will pull your saved settings from your GitHub account, updating your local configuration!

2. Writing Python in VS Code 🎞️

You just got comfortable writing and running Python code in Jupyter Notebooks. Moving to a blank text file in VS Code can feel intimidating, so we are going to use a special trick to bridge the gap: The Interactive Window.

Task 2.1: Create a VS Code Workspace

VS Code prefers to organize files within project folders.

  1. In Windows, create a project folder to hold your Python scripts, for example, V:\VSCodeTest.
  2. In VS Code, select File > Open Folder… and select the folder you just created.
  3. If a window appears asking you to trust this folder, go ahead and trust it (you can also select the box to permanently trust your V:\ drive).

Task 2.2: Create and Run a Script using the Interactive Bridge

Let’s create a Python script and run it using the Jupyter-like Interactive Window.

  1. Create a new file (File > New File > Python File).

  2. Save the file as Test.py in your workspace folder.

  3. Type (or copy and paste) the following code exactly, including the #%% at the top:

    #%%
# My test code
myData = ["Cat", "Dog", "Mouse"]
print(myData[1])

  4. Notice that VS Code automatically adds a small Run Cell button directly above the #%% line. Click it!

  5. A new pane will appear on the right side of your screen. This is the Interactive Window. It executes your chunk of code and displays the output exactly like a Jupyter Notebook cell.

  6. Click the Variables button at the top of the Interactive Window to see a list of all your active variables and their current values.

🔥This #%% trick is the perfect way to test small chunks of code interactively while you get used to the VS Code interface!

3. Debugging in VS Code 🎞️

The Interactive Window is great for testing chunks of code, but when you write full, automated GIS scripts, you will eventually need to run them top-to-bottom. Debugging code in this environment requires finding where the bug occurs and modifying the text file to fix it.

The three most common types of coding errors are:

  • Syntax errors: Python doesn’t understand your command. These are usually easy to fix because VS Code flags them with red underlines (called “linting”). Examples include typos in function names or forgetting a closing parenthesis.
  • Runtime errors: Python understands your command, but executing it violates a rule. For example, trying to add a word to a number. The code looks fine, but it crashes when it runs.
  • Logic errors: The hardest to fix. The code runs perfectly to completion, but the output is wrong because your mathematical formula or data logic is flawed.

Task 3.1: Addressing Syntax vs. Runtime Errors

VS Code is excellent at catching Syntax Errors before you even run your code, but Runtime Errors will still sneak through. Let’s look at the difference.

  1. Create a new file, save it as ErrorTest.py, and paste the following code: 
    ENV 859: Exercise 5 
name = "Amelia"
pronoun = "She"
age = 4
class = "Panda bears"
print(name + " is " + age + " years old.")
print(pronoun + " is in the " + class + " class.")

    Notice the red squiggles. These are Syntax Errors. Fix the first error by making line 1 a comment (add a #).

  2. Look at line 5. The word class is blue, indicating it is a reserved Python keyword and cannot be used as a variable name. Rename all instances of class to class_name to fix this second syntax error.

  3. The red squiggles are gone! VS Code thinks your code is perfect. Hit the ► Play button in the top right to run the script in the Terminal.

  4. The Terminal throws a TypeError. This is a Runtime Error. It crashes because line 6 tries to concatenate a string (name) with an integer (age). You can fix this by wrapping age in a str() function, but let’s explore different debugging techniques first.

Task 3.2: Running Code Line-by-Line in the Interactive Window

To zero in on exactly which line is causing a runtime error, you can run selected lines and display their output in an Interactive Window pane that appears on the right.

  1. Highlight the first 4 lines of your corrected code (the variables) and press Shift+Enter. The lines execute silently in the Terminal below.
  2. Highlight line 6 and press Shift+Enter. The error appears again, proving this specific line is the culprit.
  3. You can execute code in the Interactive Window via the prompt at the bottom: Type age = "4", and press enter.
  4. Highlight line 6 in your script again and press Shift+Enter. No error! You successfully tested a fix directly in the terminal before committing it to your script.

Task 3.3: Addressing Errors using Debug Mode

For longer scripts, highlighting lines becomes tedious. VS Code’s Debug Mode lets you pause execution automatically.

  1. Click in the blank margin just to the left of line 4. A red dot appears. This is a Breakpoint. It tells Python to run everything normally, but pause right before executing this line.

  2. Press F5 to run your code in Debug Mode. (If prompted, select Python Debugger and then Python File).

    Why does Python ask this?

    The Interactive Window and the Debugger are two completely separate tools inside VS Code. The Interactive Window is powered by the Jupyter extension, while pressing F5 triggers VS Code’s native debugging engine. They don’t automatically share their exact run configurations. When you hit F5, VS Code actually does know you are using Python. However, it doesn’t know the context in which you want to debug it. Python is used for many different things—you could be debugging a simple text script, a complex web server (like Django or Flask), or even code running on a remote machine.

  3. The script runs and highlights line 4, pausing execution.

  4. A small debugging toolbar appears at the top of the screen. Click the Step Over icon (or press F10) to run that single line and move to the next.

  5. Continue stepping over lines one by one until the crash occurs, allowing you to watch the exact moment of failure.

  6. Exit the debugger by hitting the red square (Stop) in the toolbar or pressing Shift+F5.

Recap

Integrated Development Environments (IDEs) help us write professional scripts. Fundamentally, they are text editors linked to a Python engine, but they provide code formatting, live syntax checking (linting), built-in terminals, and powerful debugging tools.

You can use the Interactive Window (#%%) to ease your transition from Jupyter, and then rely on the Terminal and Debugger as your scripts grow more complex. We will gain plenty of experience with these tools as we move through the rest of the semester.