Help

Using environment settings in Python

Each tool has a set of parameters it uses to execute an operation. Some of these parameters are common among all tools, such as a tolerance or output location. These parameters may obtain their default values from a geoprocessing environment that all tools utilize during their operation. When a tool is executed, the current environment settings can also be used as global input parameter values. Settings such as an area of interest, the spatial reference of the output dataset, and the cell size of a new raster dataset can all be specified with geoprocessing environments.

A script can be executed in several different ways. It can be run as a script tool in an ArcGIS application. It can also be run from another script or by itself from the Python window. When a script is run inside a tool from an ArcGIS application or from another geoprocessing script, the environment settings used by the calling application or script are passed to it. These settings become the default settings used by the tool's script when it is executed. The called script may alter the settings passed to it, but those changes are only used within that script or by any other tool it may call. Changes are not passed back to the calling script or application. The environment model can best be described as cascading, where values flow down to any process that uses the geoprocessing environment.

Getting and setting environment settings

Environment settings are exposed as properties on the env class. These properties can be used to retrieve the current values or to set them. Environments can be accessed as read/write properties from the environment class, as arcpy.env.<environmentName>.

import arcpy

arcpy.env.workspace = "c:/data"

Example 1: Setting environment values

import arcpy

# Set the workspace environment setting
#
arcpy.env.workspace = "c:/St_Johns/data.gdb"

# Set the XYTolerance environment setting
#
arcpy.env.XYTolerance = 2.5

# Calculate the default spatial grid index, divide in half, then
#   set the spatial grid 1 environment setting
#
grid_index = arcpy.CalculateDefaultGridIndex_management("roads")[0]

arcpy.env.spatialGrid1 = float(grid_index) / 2

# Clip the roads by the urban area feature class
#
arcpy.Clip_analysis("roads", "urban_area", "urban_roads")

Example 2: Getting and setting an environment value

import arcpy

# Check the current raster cell size and make sure it is a certain size
#   for standard output
#
arcpy.env.workspace = "c:/avalon/data"

if arcpy.env.cellSize < 10:
    arcpy.env.cellSize = 10
elif arcpy.env.cellSize > 20:
    arcpy.env.cellSize = 20
    
arcpy.HillShade_3d("island_dem", "island_shade", 300)

Using environment settings to handle scratch data

The scratchGDB and scratchFolder environments are read-only environments that provide a geodatabase and folder location that are guaranteed to exist. This means that you can reliably use a geodatabase or folder at any time, without having to create or manage one.

import arcpy

inputFC = arcpy.GetParameterAsText(0)
clipFC = arcpy.GetParameterAsText(1)
outputFC = arcpy.GetParameterAsText(2)

# Use scratchGDB environment to write intermediate data
#
tempData = arcpy.CreateScratchName(workspace=arcpy.env.scratchGDB)

result = arcpy.Buffer_analysis(inputFC, tempData, "50 METERS")
arcpy.Clip_analysis(clipFC, result, outputFC)

The scratchFolder environment is set as follows:

  • If scratchWorkspace is not set, scratchFolder defaults to the current user's temporary files directory.
  • If scratchWorkspace references a geodatabase, scratchFolder will be the folder containing the geodatabase.
  • If scratchWorkspace is set to a folder, scratchFolder will be the same as scratchWorkspace.

The scratchGDB environment is set as follows:

  • If scratchWorkspace is not set, scratchGDB defaults to a geodatabase named scratch.gdb in the current user's temporary files directory.
  • If scratchWorkspace references a geodatabase, scratchGDB will be the same as scratchWorkspace.
  • If scratchWorkspace is set to a folder, scratchGDB will be set to a geodatabase named scratch.gdb in the scratchWorkspace folder.

Resetting environments

Since geoprocessing environments can significantly affect tool operation and output, it is important to be able to keep track of environment settings and to reset environments to their default states when necessary.

The ResetEnvironments function can be used to restore the default environment values, or the ClearEnvironment function can be used to reset a specific environment.

import arcpy

# Reset geoprocessing environment settings
arcpy.ResetEnvironments()

# Reset a specific environment setting
arcpy.ClearEnvironment("workspace")

Related topics