Go to: Synopsis. Return value. Flags. Python examples.
ls( [object [object...]] , [allPaths=boolean], [assemblies=boolean], [cameras=boolean], [containers=boolean], [dagObjects=boolean], [dependencyNodes=boolean],
[exactType=string], [flatten=boolean], [geometry=boolean], [ghost=boolean], [head=int], [hilite=boolean], [intermediateObjects=boolean],
[invisible=boolean], [leaf=boolean], [lights=boolean], [live=boolean], [lockedNodes=boolean], [long=boolean], [materials=boolean], [noIntermediate=boolean], [nodeTypes=boolean], [objectsOnly=boolean], [partitions=boolean], [persistentNodes=boolean],
[planes=boolean], [preSelectHilite=boolean],
[readOnly=boolean], [recursive=boolean], [referencedNodes=boolean],
[references=boolean],
[renderGlobals=boolean],
[renderQualities=boolean],
[renderResolutions=boolean],
[renderSetups=boolean],
[selection=boolean], [sets=boolean], [shapes=boolean], [shortNames=boolean], [showType=boolean], [tail=int], [templated=boolean], [textures=boolean], [transforms=boolean], [type=string], [undeletable=boolean], [untemplated=boolean], [visible=boolean])
Note: Strings representing object names and
arguments must be separated by commas. This is not depicted in the
synopsis.
ls is undoable, NOT queryable, and NOT
editable.
The ls command returns the names (and
optionally the type names) of objects in the scene. The most common
use of ls is to filter or match objects based
on their name (using wildcards) or based on their type. By default
ls will match any object in the scene but it
can also be used to filter or list the selected objects when used
in conjunction with the -selection flag. If type names are
requested, using the -showType flag, they will be interleaved with
object names so the result will be pairs of <object,
type> values. Internal nodes (for example itemFilter nodes)
are typically filtered so that only scene objects are returned.
However, using a wildcard will cause all the nodes matching the
wild card to show up, including internal nodes. For example,
ls * will list all nodes whether internal or
not. When Maya is in relativeNames mode, the ls
command will return names relative to the current namespace
and ls * will list from the the current
namespace. For more details, please refer to the
-relativeNames flag of the
namespace command.
allPaths, assemblies, cameras, containers, dagObjects, dependencyNodes, exactType, flatten,
geometry, ghost, head, hilite, intermediateObjects, invisible, leaf,
lights, live,
lockedNodes, long, materials,
noIntermediate, nodeTypes, objectsOnly, partitions, persistentNodes, planes, preSelectHilite, readOnly, recursive, referencedNodes, references, renderGlobals, renderQualities, renderResolutions, renderSetups, selection, sets,
shapes, shortNames, showType, tail,
templated, textures, transforms, type,
undeletable, untemplated, visible
| Long name (short name) |
Argument types |
Properties |
long(l) |
boolean |
 |
|
Return full path names for Dag objects. By default the shortest
unique name is returned. |
|
shortNames(sn) |
boolean |
|
|
Return short attribute names. By default long attribute names
are returned. |
|
head(hd) |
int |
|
|
This flag specifies the maximum number of elements to be
returned from the beginning of the list of items. Note: each type
flag will return at most this many items so if multiple type flags
are specified then the number of items returned can be greater than
this amount. |
|
tail(tl) |
int |
|
|
This flag specifies the maximum number of elements to be
returned from the end of the list of items. Note: each type flag
will return at most this many items so if multiple type flags are
specified then the number of items returned can be greater than
this amount |
|
type(typ) |
string |
 |
|
List all objects of the specified type. This flag can appear
multiple times on the command line. Note: the type passed to this
flag is the same type name returned from the -showType flag. Note:
some selection items in Maya do not have a specific object/data
type associated with them and will return "untyped" when listed
with this flag.
This flag cannot be used in conjunction with the -exactType
flag. |
|
exactType(et) |
string |
|
|
List all objects of the specified type, but not objects
that are descendents of that type. This flag can appear multiple
times on the command line. Note: the type passed to this flag is
the same type name returned from the -showType flag.
This flag cannot be used in conjunction with the -type flag. |
|
showType(st) |
boolean |
|
|
List the type of each object after its name. |
|
objectsOnly(o) |
boolean |
|
|
When this flag is set only object names will be returned and
components/attributes will be ignored. |
|
selection(sl) |
boolean |
|
|
List objects that are currently selected. |
|
live(lv) |
boolean |
|
|
List objects that are currently live. |
|
hilite(hl) |
boolean |
|
|
List objects that are currently hilited for component
selection. |
|
preSelectHilite(psh) |
boolean |
|
|
List components that are currently hilited for
pre-selection. |
|
geometry(g) |
boolean |
|
|
List geometric Dag objects. |
|
dependencyNodes(dep) |
boolean |
|
|
List dependency nodes. (including Dag objects) |
|
dagObjects(dag) |
boolean |
|
|
List Dag objects of any type. If object name arguments are
passed to the command then this flag will list all Dag objects
below the specified object(s). |
|
leaf(lf) |
boolean |
|
|
List all leaf nodes in Dag. This flag is a modifier and must be
used in conjunction with the -dag flag. |
|
assemblies(assemblies) |
boolean |
|
|
List top level transform Dag objects |
|
allPaths(ap) |
boolean |
|
|
List all paths to nodes in DAG. This flag only works if
-dag is also specified or if an object name is
supplied. |
|
transforms(tr) |
boolean |
|
|
|
shapes(s) |
boolean |
|
|
|
lights(lt) |
boolean |
|
|
|
cameras(ca) |
boolean |
|
|
|
planes(pl) |
boolean |
|
|
List construction plane shapes. |
|
partitions(pr) |
boolean |
|
|
|
sets(set) |
boolean |
|
|
|
textures(tex) |
boolean |
|
|
|
materials(mat) |
boolean |
|
|
List materials or shading groups. |
|
renderQualities(rq) |
boolean |
|
|
List named render qualities. |
|
renderResolutions(rr) |
boolean |
|
|
|
renderGlobals(rg) |
boolean |
|
|
|
renderSetups(rs) |
boolean |
|
|
Alias for -renderGlobals. |
|
nodeTypes(nt) |
boolean |
|
|
Lists all registered node types. |
|
readOnly(ro) |
boolean |
|
|
Returns referenced nodes. Referenced nodes are read only. NOTE:
Obsolete. Please use "-referencedNodes". |
|
referencedNodes(rn) |
boolean |
|
|
Returns referenced nodes. Referenced nodes are read only. |
|
undeletable(ud) |
boolean |
|
|
Returns nodes that cannot be deleted (which includes locked
nodes). These nodes also cannot be renamed. |
|
lockedNodes(ln) |
boolean |
|
|
Returns locked nodes, which cannot be deleted or renamed.
However, their status may change. |
|
persistentNodes(pn) |
boolean |
|
|
Returns persistent nodes, which are nodes that stay in the Maya
session after a file > new. |
|
flatten(fl) |
boolean |
|
|
Flattens the returned list of objects so that each component is
identified individually. |
|
visible(v) |
boolean |
|
|
List only visible dag nodes. |
|
invisible(iv) |
boolean |
|
|
List only invisible dag nodes. |
|
intermediateObjects(io) |
boolean |
|
|
List only intermediate dag nodes. |
|
noIntermediate(ni) |
boolean |
|
|
List only non intermediate dag nodes. |
|
templated(tm) |
boolean |
|
|
List only templated dag nodes. |
|
untemplated(ut) |
boolean |
|
|
List only un-templated dag nodes. |
|
ghost(gh) |
boolean |
|
|
|
recursive(r) |
boolean |
|
|
When set to true, this command will look for name matches in
all namespaces. When set to false, this command will only look for
matches in namespaces that are requested (e.g. by specifying a name
containing the ':'... "ns1:pSphere1"). |
|
references(rf) |
boolean |
|
|
List references associated with files. Excludes special
reference nodes such as the sharedReferenceNode and unknown
reference nodes. |
|
containers(con) |
boolean |
|
|
List containers. Includes both standard containers as well as
other types of containers such as dagContainers. |
|
| Flag can appear in Create mode of
command |
 Flag can appear in Edit mode of command |
 Flag can appear in Query mode of command |
Flag can have multiple arguments, passed
either as a tuple or a list. |
import maya.cmds as cmds
# create some objects to operate on and select them all.
# Note that there are two objects named circle1;
cmds.circle( n='circle1' )
cmds.group()
cmds.circle( n='circle1' )
cmds.sphere( n='sphere1' )
cmds.group()
cmds.instance()
cmds.select( ado=True )
# list all objects
cmds.ls()
# List all selected objects
cmds.ls( selection=True )
# List all hilited objects
cmds.ls( hilite=True )
# List last selected object
cmds.ls( selection=True, tail=1 )
# List all objects named "sphere1". Note that since sphere1 is
# instanced, the command below lists only the first instance.
cmds.ls( 'sphere1' )
# To list all instances of sphere1, use the -ap/allPaths flag.
cmds.ls( 'sphere1', ap=True )
# List all selected objects named "group*"
cmds.ls( 'group*', sl=True )
# List all geometry, lights and cameras in the DAG.
cmds.ls( geometry=True, lights=True, cameras=True )
# List all shapes in the dag.
cmds.ls( shapes=True )
# One thing to note is that it is better to always use the
# -l/long flag when listing nodes without any filter. This is
# because there may be two nodes with the same name (in this
# example, circle1). 'ls' will list the names of all the objects
# in the scene. Objects with the same name need a qualified
# path name which uniquely identifies the object. A command
# to select all objects such as "select `ls`" will fail because
# the object lookup can't resolve which "circle1" object is
# intended. To select all objects, you need the following:
cmds.select(cmds.ls(sl=True))
# When trying to find a list of all objects of a specific
# type, one approach might be to list all objects and then
# use the nodeType command to then filter the list. As in:
allObjects = cmds.ls(l=True)
for obj in allObjects:
if cmds.nodeType(obj) == 'surfaceShape':
print obj
# The problem with this is that 'nodeType' returns the
# most derived type of the node. In this example, "surfaceShape"
# is a base type for nurbsSurface so nothing will be printed.
# To do this properly, the -typ/type flag should be used
# to list objects of a specific type as in:
allObjects = cmds.ls(type='surfaceShape')
for obj in allObjects:
print obj
# List all geometry shapes and their types
cmds.ls( type='geometryShape', showType=True )
# List all paths to all leaf nodes in the DAG
cmds.ls( dag=True, lf=True, ap=True )
# List all nodes below the selected node
cmds.ls( dag=True, ap=True, sl=True )
# List all dag nodes that are read-only (i.e. referenced nodes)
cmds.ls( dag=True, ro=True )
# List all ghosting objects
cmds.ls( ghost=True )
# List reference nodes associated with specific files
cmds.ls( references=True )
# List all reference nodes, including unknown and shared reference nodes
cmds.ls( type='reference' )