Python os.listdir()列出目录内容用法详解 - 完整示例与对比

一、os.listdir() 概述

os.listdir() 是 Python os 模块中最常用的函数之一，用于获取指定目录下的所有条目（文件和子目录）的名称列表。它只返回目录中第一层的条目名称，不递归进入子目录。

该函数返回的条目名称是纯字符串，不包含路径前缀。如果需要完整路径，需要手动与目录路径拼接。同时，它不区分文件和目录，需要配合 os.path.isfile() 和 os.path.isdir() 进行判断。

二、语法与参数说明

函数语法

os.listdir(path='.')

参数说明

三、返回值

返回一个 list，其中包含指定目录中所有条目的名称字符串。如果目录为空，则返回空列表 []。

• 包含内容：所有文件、目录、符号链接、隐藏文件（如 .gitignore）

• 不包含：特殊目录条目 . 和 ..

• 顺序：返回顺序不保证排序，取决于操作系统文件系统

四、代码示例

示例1：列出当前目录内容

import os

items = os.listdir('.')
print(f"当前目录内容 ({len(items)} 项):")
for item in sorted(items):
    print(f"  {item}")

输出结果：

当前目录内容 (5 项):
  config.ini
  data
  main.py
  README.md
  utils

示例2：区分文件和目录

import os

path = '.'
files = []
dirs = []

for item in os.listdir(path):
    full_path = os.path.join(path, item)
    if os.path.isfile(full_path):
        files.append(item)
    elif os.path.isdir(full_path):
        dirs.append(item)

print(f"文件: {sorted(files)}")
print(f"目录: {sorted(dirs)}")

输出结果：

文件: ['config.ini', 'main.py', 'README.md']
目录: ['data', 'utils']

示例3：按扩展名筛选文件

import os

# 筛选所有 Python 文件
py_files = [f for f in os.listdir('.') if f.endswith('.py')]
print(f"Python文件: {py_files}")

# 收集所有扩展名
all_extensions = set()
for f in os.listdir('.'):
    full_path = os.path.join('.', f)
    if os.path.isfile(full_path):
        ext = os.path.splitext(f)[1]
        all_extensions.add(ext)

print(f"所有扩展名: {sorted(all_extensions)}")

输出结果：

Python文件: ['main.py']
所有扩展名: ['.ini', '.md', '.py']

五、实际应用场景

• 文件管理器：在图形界面或命令行文件管理器中展示当前目录的文件和子目录列表

• 批量处理脚本：遍历目录下所有文件，进行格式转换、数据清洗、图片压缩等批量操作

• 自动化测试验证：在测试脚本执行后，检查输出目录是否生成了预期的结果文件

六、注意事项

注意：os.listdir() 返回的是纯名称列表，不包含完整路径。如需完整路径，必须使用 os.path.join() 拼接。

注意：返回结果不保证排序**。不同操作系统和文件系统可能返回不同顺序，如需固定顺序请使用 sorted()。