Annotate Selected Features (Cartography)


Creates annotation for the selected features of a layer. The labeling properties defined in the annotation class properties of the specified related annotation feature classes are used.


  • Features to be annotated are determined by a selection applied to a layer. The selection must be determined in a previous step using Select Layer by Attribute or Select Layer by Location or by querying a map layer in ArcGIS Pro.

  • The map determines which feature-linked annotation classes are listed. There can be many feature-linked annotation classes, but only those in the map will be listed. Check the annotation classes in which you want to store the annotation.

  • The Input Layer must include a selection; otherwise, Annotate Selected Features will fail.

  • The Input Layer must have feature-linked annotation; otherwise, Annotate Selected Features will fail.

  • Some labels may not currently display on the map because there is no room for them. To convert these labels, check the Convert unplaced labels to annotation check box. This saves the unplaced labels in the annotation feature class, allowing you to position them later in an ArcGIS Pro edit session.


AnnotateSelectedFeatures(in_map, in_layer, anno_layers, {generate_unplaced})
ParameterExplanationData Type

The input map.


The layer for which the selected features will have annotation created.

Feature Layer
[[annotation_layer, sublayer;sublayer],...]

The feature-linked annotation layers and the specified sublayers that will have annotation converted into them.

Value Table

Specifies whether to create unplaced annotation from unplaced labels.

  • ONLY_PLACEDAnnotation will only be created for features that are currently labeled. This is the default.
  • GENERATE_UNPLACEDUnplaced annotation are stored in the annotation feature class. The status field for these annotation is set to Unplaced.

Derived Output

NameExplanationData Type

The output annotation layers.

Annotation Layer

Code sample

AnnotateSelectedFeatures example (Python window)

The following Python window script demonstrates how to use the AnnotateSelectedFeatures tool in immediate mode.

import arcpy
arcpy.env.workspace = "c:/data/Canada.gdb"
arcpy.SelectLayerByAttribute_management("cities", 'NEW_SELECTION', 
                                        "County = 'Northumberland'")
arcpy.AnnotateSelectedFeatures("Map", 'cities', 
                               "citiesAnno 'Class 1;Class 2'; citiesAltAnno 'Class 1'", 
AnnotateSelectedFeatures example 2 (stand-alone script)

Stand-alone script that annotates selected features for the layer using the AnnotateSelectedFeatures function.

# Name:
# Description: Annotate features based on a selection in a map 

# Import system modules
import arcpy

# Set environment settings
arcpy.env.workspace = "C:\\data\\Northumberland.gdb"

# Execute Annotate Selected Features
p ="C:\\data\\Northumberland.aprx")
for m in p.listMaps():
				arcpy.AnnotateSelectedFeatures_cartography(m, 'Wells', "WellsAnno 'Class 1'", 


This tool does not use any geoprocessing environments.

Licensing information

  • Basic: No
  • Standard: Yes
  • Advanced: Yes

Related topics