Cómo Listar los Archivos de una Carpeta en Python

Vamos a ver en esta entrada una de las preguntas más comunes en Python, que es cómo listar todos los archivos o ficheros de una carpeta o directorio en Python. Veremos varias formas de hacerlo y algunos ejemplos.

Para listar los archivos de una carpeta en Python se pueden usar las funciones os.listdir o os.scandir, que devuelven todo el contenido de un directorio, tanto los archivos como las subcarpetas. Otra opción es os.walk, que devuelve dos listas: una con los archivos y otra con las subcarpetas.

A continuación, te voy a a explicar con algo más de detalle estas alternativas. Para nuestros ejemplos vamos a utilizar una carpeta llamada carpeta (muy original, lo sé) con el siguiente contenido, donde se puede ver que dentro de carpeta hay tres archivos y dos subcarpetas (que, a su vez, tienen dos archivos más cada una de ellas):

carpeta
├── archivo1.txt
├── archivo2.txt
├── archivo3.txt
├── subcarpeta1
│   ├── archivo11.txt
│   └── archivo12.txt
└── subcarpeta2
    ├── archivo21.txt
    └── archivo22.txt

Cómo listar el contenido de una carpeta con listdir

Usar la función listdir, que pertenece al módulo os, en Python es muy sencillo. Basta con proporcionarle como parámetro un string con la ruta a la carpeta, que debe existir, y nos devolverá una lista con los nombres de los archivos y otras carpetas contenidas en ella. Lo vemos:

import os

print(os.listdir('carpeta'))

Y el resultado será el siguiente:

['subcarpeta1', 'subcarpeta2', 'archivo2.txt', 'archivo3.txt', 'archivo1.txt']

Más sencillo imposible. Eso sí, asegúrate de que la ruta a la carpeta que queremos leer existe (y de que tenemos permisos de lectura de la misma), de lo contrario se interrumpirá la ejecución del código con el error FileNotFoundError.

Fíjate en un par de cosas. Tenemos todo el contenido directo de carpeta, ya sean ficheros o directorios, pero no tenemos ninguna distinción, es decir, no sabemos si son carpetas o ficheros. Tampoco tenemos el contenido de las subcarpetas. Y tampoco tenemos la ruta completa al contenido.

Para obtener la ruta completa desde nuestra carpeta hasta cada uno de los elementos que contiene podemos hacer uso de la función os.path.join que toma dos parámetros, la carpeta contenedora y el nombre de contenido y genera la ruta válida, con independencia del sistema operativo que estemos usando, para el contenido. Lo vemos:

import os

nombre_carpeta = 'carpeta'

contenido = os.listdir(nombre_carpeta)

for elemento in contenido:
    print(os.path.join(nombre_carpeta, elemento))

Con esto tendremos las rutas válidas a los contenidos de nuestra carpeta (que en mi caso, que uso Linux, serán así):

carpeta/subcarpeta1
carpeta/subcarpeta2
carpeta/archivo2.txt
carpeta/archivo3.txt
carpeta/archivo1.txt

Ahora podemos usar las funciones os.path.isfile y os.path.isdir que nos dicen si el parámetro que le pasamos es un fichero o un carpeta respectivamente. Gracias a esto podemos obtener solo los ficheros o solo las subcarpetas de nuestra carpeta original. Aquí tienes un ejemplo en el que listamos solo los ficheros o solo las carpetas:

import os

nombre_carpeta = 'carpeta'

contenido = os.listdir(nombre_carpeta)

print(f'Los ficheros de {nombre_carpeta} son:')
for elemento in contenido:
    ruta_completa = os.path.join(nombre_carpeta, elemento)
    if os.path.isfile(ruta_completa):  # miramos si es fichero
        print(elemento, ruta_completa, sep=', ')  # mostramos el nombre del elemento y la ruta completa

print()

print(f'Las carpetas de {nombre_carpeta} son:')
for elemento in contenido:
    ruta_completa = os.path.join(nombre_carpeta, elemento)
    if os.path.isdir(ruta_completa):  # miramos si es carpeta
        print(elemento, ruta_completa, sep=', ')  # mostramos el nombre del elemento y la ruta completa

Y el resultado por pantalla será el siguiente:

Los ficheros de carpeta son:
archivo2.txt, carpeta/archivo2.txt
archivo3.txt, carpeta/archivo3.txt
archivo1.txt, carpeta/archivo1.txt
Las carpetas de carpeta son:
subcarpeta1, carpeta/subcarpeta1
subcarpeta2, carpeta/subcarpeta2

Como ahora tenemos las rutas completas a los contenidos de carpeta podríamos ir ejecutando de manera recursiva listdir sobre las subcarpetas para acceder a su contenido si quisiéramos.

Pasamos a ver una opción un poco mejor...

Cómo listar los archivos de una carpeta con scandir

En la propuesta de mejora de Python PEP 471 se sugiere la función os.scandir como una mejor manera para listar los archivos de una carpeta. Esto es así por dos motivos principales:

• La función devuelve objetos ligeros de la clase DirEntry y no solo un string, con lo que podremos operar con esos objetos.
• La función proporciona el contenido a través de un generador y no como una lista completa, cosa que resulta mucho más eficiente si, por ejemplo, tenemos una carpeta con miles de ficheros.

Vamos a obtener los contenidos de nuestra carpeta y a mostrar por pantalla qué elementos obtenemos:

import os

nombre_carpeta = 'carpeta'

contenido = os.scandir(nombre_carpeta)

for elemento in contenido:
    print(elemento)

Ejecutamos y...

<DirEntry 'subcarpeta1'>
<DirEntry 'subcarpeta2'>
<DirEntry 'archivo2.txt'>
<DirEntry 'archivo3.txt'>
<DirEntry 'archivo1.txt'>

Cómo ves, hemos obtenido objetos de tipo DirEntry con los que podemos interactuar para obtener el nombre del elemento y para conocer directamente si un elemento se trata de un fichero o de una carpeta.

Podemos usar las funciones is_file e is_dir de DirEntry para distinguir si se trata de un fichero o un directorio respectivamente.

Además podemos acceder a los atributos name y path para obtener el nombre sencillo del elemento y la ruta completa.

Veamos un pequeño ejemplo listando solo aquellos elementos que son ficheros y mostrando su nombre y la ruta completa:

import os

nombre_carpeta = 'carpeta'

contenido = os.scandir(nombre_carpeta)

for elemento in contenido:
    if elemento.is_file():  # comprobamos si es un fichero
        print(f'{elemento.name} es un fichero y la ruta completa es {elemento.path}')

Y el resultado por pantalla será el siguiente:

archivo2.txt es un fichero y la ruta completa es carpeta/archivo2.txt
archivo3.txt es un fichero y la ruta completa es carpeta/archivo3.txt
archivo1.txt es un fichero y la ruta completa es carpeta/archivo1.txt

Cómo listar los contenidos de una carpeta con walk

Finalmente vamos a ver como listar los archivos de un directorio con la función os.walk. Esta función nos permite "pasear" por el árbol de directorios facilitando así el obtener de manera recursiva los ficheros contenidos en subcarpetas.

La función os.walk recibe el nombre de una carpeta por parámetro y nos devuelve una lista de tuplas, una tupla por cada carpeta, con tres elementos:

1. El nombre del elemento, es decir, del fichero o de la carpeta.
2. Una lista con las subcarpetas.
3. Una lista con los ficheros.

Así, si hacemos una llamada a os.walk y mostramos cada una de las tuplas obtenidas veremos con facilidad todos los contenidos, incluyendo subcarpetas:

import os

for e in os.walk('carpeta'):
    print(e)

Y el resultado por pantalla será el siguiente:

('carpeta', ['subcarpeta1', 'subcarpeta2'], ['archivo2.txt', 'archivo3.txt', 'archivo1.txt'])
('carpeta/subcarpeta1', [], ['archivo11.txt', 'archivo12.txt'])
('carpeta/subcarpeta2', [], ['archivo22.txt', 'archivo21.txt'])

Fíjate en que, para el primer elemento de cada tupla, el que indica el nombre del elemento, la ruta es completa, por ejemplo carpeta/subcarpeta1.

Para acabar, voy a usar walk en un pequeño ejemplo para mostrar los ficheros dentro de cada carpeta:

import os

for carpeta in os.walk('carpeta'):
    print(f'En {carpeta[0]} tenemos {len(carpeta[2])} ficheros:')
    for fichero in carpeta[2]:
        print(f' - {fichero}')

El resultado será el siguiente:

En carpeta tenemos 3 ficheros:
 - archivo2.txt
 - archivo3.txt
 - archivo1.txt
En carpeta/subcarpeta1 tenemos 2 ficheros:
 - archivo11.txt
 - archivo12.txt
En carpeta/subcarpeta2 tenemos 2 ficheros:
 - archivo22.txt
 - archivo21.txt

Conclusión

Hemos visto tres alternativas (aunque no son las únicas) para listar los archivos de dentro de un carpeta en Python: os.listdir, os.scandir y os.walk. Espero que con esto tengas las herramientas suficientes para poder trabajar con directorios y sus contenidos en Python

Si te ha resultado de utilidad esta entrada, no dudes en suscribirte al blog y recibir tu regalo. ¡Muchas gracias! Y no olvides compartir este artículo.