2 Create an ArcGIS Pro Python repo

2.1 Introduction

This chapter shows the fastest path for MVR geospatial data scientists to start a Python repository that uses ESRI’s ArcGIS Pro Python stack (especially arcpy).

This guide is intentionally template-first to minimize setup work for analysts who want to get to analysis quickly.

Template repo: MVR-GIS/repo-arcgispro-python
IDE: VS Code (including Git via VS Code Source Control)
Environment strategy: clone ArcGIS Pro’s base environment (arcgispro-py3) into a per-repo environment
Standard environment name: .conda-arcgis
Terminal strategy: use ESRI’s supported activation scripts (proenv.bat) rather than fragile PATH hacks

Authoritative ESRI documentation (canonical): - Installing Python for ArcGIS Pro: https://pro.arcgis.com/en/pro-app/latest/arcpy/get-started/installing-python-for-arcgis-pro.htm

2.2 Scope and assumptions

Applies to ArcGIS Pro 3.x (3.4+ expected in practice).
Windows only.
This workflow relies on ArcGIS Pro’s conda-based Python distribution (the environment ESRI maintains).
This guide does not provide software installation instructions; USACE employees should follow approved internal workflows referenced elsewhere in this user guide.

2.3 What you get by using the template

The template repo exists so you do not have to build project scaffolding yourself. In general, it should already include:

VS Code workspace configuration (including an ESRI-initialized terminal profile using proenv.bat)
a minimal arcpy smoke test script
an environment metadata helper (env/capture_env_metadata.py)
a short “day 1” notebook in notebooks/00_getting_started.ipynb
a predictable folder structure (scripts/, src/, notebooks/, data/, outputs/, env/)

If you find yourself repeatedly adding setup files to downstream repos, treat that as a signal to improve the template rather than redoing setup in each project.

2.4 Key steps (overview)

Create a new repo from the template (Use this template).
Clone locally using VS Code.
Create the per-repo conda environment .conda-arcgis by cloning arcgispro-py3 (one-time).
Open VS Code’s ESRI-initialized terminal and activate .conda-arcgis.
Run the smoke test to confirm arcpy works.
Select the .conda-arcgis interpreter and (optionally) run the starter notebook.

2.5 Prerequisites

ArcGIS Pro 3.x installed and working on your machine
VS Code installed via your organization’s approved method
Git installed via your organization’s approved method

Optional quick check (VS Code terminal):

git --version

2.6 Step 1 — Create a new repository from the template

In GitHub:

Open the template repository: MVR-GIS/repo-arcgispro-python
Click Use this template
Create your new repository:
- Owner: MVR-GIS (or your approved org/user location)
- Repository name: choose a descriptive name for the analysis/workflow
- Visibility: per project needs/policy
Copy the new repository’s clone URL

Definition of done: - The new repo exists and contains the template structure (VS Code config, smoke test, notebook, README).

2.7 Step 2 — Clone the repo using VS Code (Git interface)

Open VS Code
Source Control → Clone Repository (or Command Palette → “Git: Clone”)
Paste the repo URL
Choose a local folder (example: C:\git\)
Open the cloned repo

Verification: - You can see .vscode/, scripts/, and notebooks/ in the VS Code Explorer - Source Control shows a clean working tree

2.8 Step 3 — One-time setup: create the per-repo environment `.conda-arcgis`

ArcGIS Pro ships with a highly customized Python environment (commonly named arcgispro-py3). For project work, we clone it to avoid modifying ESRI’s base environment.

Use the ArcGIS Pro Python Command Prompt (Start Menu) for environment management:

Confirm arcgispro-py3 exists:

conda env list
Create the per-repo environment by cloning:

conda create –name .conda-arcgis –clone arcgispro-py3
Activate and verify:

conda activate .conda-arcgis python -c “import sys; print(sys.executable)” python -c “import arcpy; print(arcpy.__version__)”

Notes: - Cloning can be slow and disk-heavy; this is expected for the ArcGIS stack. - The standardized name .conda-arcgis reduces setup decisions and keeps instructions consistent.

2.9 Step 4 — Use the ESRI-configured terminal inside VS Code

The template repo configures a VS Code integrated terminal that initializes ESRI’s Python tooling via proenv.bat.

In VS Code:

Terminal → New Terminal
Confirm conda is available:

conda –version conda env list
Activate the project environment:

conda activate .conda-arcgis

Verification:

python -c "import arcpy; print(arcpy.__version__)"

If conda is not found: - restart VS Code and open a new terminal - confirm the repo includes .vscode/settings.json

2.10 Step 5 — Run the smoke test (fast validation)

Run the template smoke test from the repo root:

python scripts/smoke_test_arcpy.py

Definition of done: - The smoke test prints your Python executable and reports PASS.

2.11 Step 6 — Select the Python interpreter in VS Code (required)

Even when your terminal is correct, VS Code needs the correct interpreter for: - IntelliSense / type info - running scripts via the Python extension - Jupyter notebook kernels

In VS Code:

Open Command Palette (Ctrl+Shift+P)
Run: Python: Select Interpreter
Choose the interpreter for the conda env named .conda-arcgis

If you do not see .conda-arcgis: - restart VS Code after creating the environment - confirm it exists: conda env list

Verification (terminal):

python -c "import sys; print(sys.executable)"

2.12 Step 7 — Notebook start (recommended, not a tutorial)

This template includes a short “day 1” notebook intended for teams coming from an R Notebook workflow.

In VS Code: 1. Open notebooks/00_getting_started.ipynb 2. Select a kernel/interpreter when prompted: .conda-arcgis 3. Run the cells to confirm: - Python executable and version - arcpy import works

2.13 Step 8 — Capture environment metadata (recommended)

Environment capture is a lightweight audit trail. Run:

python env/capture_env_metadata.py

If you also want to write a pip package list (often large), run:

python env/capture_env_metadata.py --pip-freeze

Outputs are written to env/.

2.14 Project structure (template expectation)

notebooks/ — exploratory analysis + narrative
scripts/ — runnable workflows (entry points)
src/ — reusable functions/modules as patterns stabilize
data/ — project data (use judgment; avoid huge files)
outputs/ — generated outputs (use judgment; avoid committing huge/binary artifacts)
env/ — environment metadata and capture helper

2.15 Git workflow (VS Code Source Control; minimal CLI)

In VS Code Source Control: - Stage files with “+” - Write a commit message and commit - Use “Sync Changes” to push

Recommended habit: - commit small, meaningful increments (especially when you add new scripts/notebooks)

2.16 Troubleshooting (most common)

`arcpy` import fails

Confirm .conda-arcgis is activated:

conda activate .conda-arcgis
Re-run the smoke test:

python scripts/smoke_test_arcpy.py
If it fails even in ArcGIS Pro Python Command Prompt, follow ESRI’s canonical guidance: https://pro.arcgis.com/en/pro-app/latest/arcpy/get-started/installing-python-for-arcgis-pro.htm

VS Code is using the wrong interpreter

Command Palette → Python: Select Interpreter → choose .conda-arcgis
Restart VS Code

2.17 Definition of done

You are ready to proceed to “real work” when:

repo created from MVR-GIS/repo-arcgispro-python
.conda-arcgis created by cloning arcgispro-py3
VS Code terminal can run conda and activate .conda-arcgis
python scripts/smoke_test_arcpy.py passes
VS Code interpreter set to .conda-arcgis
starter notebook runs with .conda-arcgis kernel (recommended)