Módulo os do Python: Guia de Operações com Arquivos e Diretórios

Name

Soren Atelier

Updated on 10/02/2026

Todo script Python que lê um arquivo de configuração, salva resultados, organiza dados ou automatiza implantações precisa interagir com o sistema de arquivos. Mas os caminhos de arquivos se comportam de forma diferente no Windows, macOS e Linux. Um caminho codificado como /home/user/data não funciona no Windows. Concatenar strings manualmente com + e / leva a bugs de barra dupla e separadores ausentes. E sem verificações adequadas, seu script pode deletar o arquivo errado ou travar quando um diretório já existe.

O módulo os do Python resolve esses problemas. Ele fornece uma interface portável e multiplataforma para trabalhar com o sistema operacional -- criar diretórios, listar arquivos, ler variáveis de ambiente, manipular caminhos e percorrer árvores de diretórios. Ele vem com toda instalação Python, não requer pip install e lida com diferenças de plataforma automaticamente.

Este guia cobre cada função essencial do módulo os, organizada por caso de uso, com exemplos práticos que você pode copiar diretamente para seus projetos.

Obtendo o Diretório de Trabalho Atual

Antes de fazer qualquer coisa com arquivos, você precisa saber onde seu script está executando. os.getcwd() retorna o diretório de trabalho atual como um caminho absoluto.

import os
 
# Obter o diretório de trabalho atual
cwd = os.getcwd()
print(cwd)  # e.g., /home/user/projects/myapp
 
# Mudar o diretório de trabalho
os.chdir('/tmp')
print(os.getcwd())  # /tmp
 
# Voltar ao diretório anterior
os.chdir(cwd)

Use os.getcwd() ao construir caminhos relativos ou quando precisar restaurar o diretório de trabalho após alterá-lo temporariamente.

Operações com Diretórios

Criando Diretórios

os.mkdir() cria um único diretório. Levanta FileExistsError se o diretório já existe e FileNotFoundError se o diretório pai não existe.

import os
 
# Criar um único diretório
os.mkdir('output')
 
# Criar apenas se não existir
if not os.path.exists('output'):
    os.mkdir('output')

os.makedirs() cria diretórios recursivamente -- incluindo todos os diretórios pais ausentes. O parâmetro exist_ok=True previne erros quando o diretório já existe.

import os
 
# Criar diretórios aninhados em uma única chamada
os.makedirs('data/raw/2026/january', exist_ok=True)
 
# Sem exist_ok, isso levanta FileExistsError se 'data' já existir
# os.makedirs('data/raw/2026/january')  # pode levantar erro

Listando Conteúdo de Diretórios

os.listdir() retorna uma lista de todas as entradas (arquivos e diretórios) em um caminho dado.

import os
 
# Listar tudo no diretório atual
entries = os.listdir('.')
print(entries)  # ['main.py', 'data', 'output', 'README.md']
 
# Listar conteúdo de um diretório específico
data_files = os.listdir('/var/log')
print(data_files)

os.scandir() é uma alternativa mais eficiente que retorna objetos DirEntry com atributos de arquivo em cache. Use-o quando precisar de metadados de arquivo junto com os nomes.

import os
 
with os.scandir('.') as entries:
    for entry in entries:
        info = entry.stat()
        print(f"{entry.name:30s}  {'DIR' if entry.is_dir() else 'FILE':4s}  {info.st_size} bytes")

Removendo Diretórios

os.rmdir() remove um diretório vazio. Para diretórios não vazios, use shutil.rmtree().

import os
import shutil
 
# Remover um diretório vazio
os.rmdir('output')
 
# Remover um diretório e todo seu conteúdo (use com cuidado)
shutil.rmtree('data/raw/2026')

Operações com Arquivos

Removendo Arquivos

os.remove() (ou seu alias os.unlink()) deleta um único arquivo. Levanta FileNotFoundError se o arquivo não existir.

import os
 
# Deletar um arquivo
os.remove('temp_output.csv')
 
# Deleção segura com verificação de existência
filepath = 'temp_output.csv'
if os.path.exists(filepath):
    os.remove(filepath)
    print(f"Deletado {filepath}")
else:
    print(f"{filepath} não encontrado")

Renomeando e Movendo Arquivos

os.rename() renomeia ou move um arquivo ou diretório. Se o destino já existir, o comportamento depende da plataforma -- pode sobrescrever no Unix mas levantar um erro no Windows. Use os.replace() para substituição atômica garantida.

import os
 
# Renomear um arquivo
os.rename('old_report.csv', 'new_report.csv')
 
# Mover um arquivo para outro diretório
os.rename('report.csv', 'archive/report_2026.csv')
 
# Substituição atômica (sobrescreve destino em todas as plataformas)
os.replace('new_data.csv', 'data.csv')

Obtendo Informações de Arquivos

os.stat() retorna metadados detalhados do arquivo incluindo tamanho, permissões e timestamps.

import os
from datetime import datetime
 
info = os.stat('data.csv')
print(f"Tamanho: {info.st_size} bytes")
print(f"Modificado: {datetime.fromtimestamp(info.st_mtime)}")
print(f"Criado: {datetime.fromtimestamp(info.st_ctime)}")
print(f"Permissões: {oct(info.st_mode)}")

Operações de Caminho com os.path

O submódulo os.path é onde a maior parte do trabalho diário com o sistema de arquivos acontece. Ele lida com construção, validação e decomposição de caminhos entre plataformas.

Construindo Caminhos com Segurança

Nunca concatene caminhos com +. Use os.path.join() para construir caminhos corretamente independentemente do sistema operacional.

import os
 
# Correto: os.path.join lida com separadores
path = os.path.join('data', 'raw', 'sales.csv')
print(path)  # 'data/raw/sales.csv' no Unix, 'data\\raw\\sales.csv' no Windows
 
# Errado: concatenação de strings pode falhar
bad_path = 'data' + '/' + 'raw' + '/' + 'sales.csv'  # falha no Windows

Verificando Existência e Tipo

import os
 
# Verificar se um caminho existe (arquivo ou diretório)
print(os.path.exists('/etc/hosts'))      # True (no Linux/macOS)
 
# Verificar especificamente se é um arquivo
print(os.path.isfile('main.py'))         # True
print(os.path.isfile('data'))            # False (é um diretório)
 
# Verificar especificamente se é um diretório
print(os.path.isdir('data'))             # True
print(os.path.isdir('main.py'))          # False

Decompondo Caminhos

Extraia componentes de um caminho de arquivo sem divisão manual de strings.

import os
 
filepath = '/home/user/projects/report_final.csv'
 
# Obter o nome do arquivo
print(os.path.basename(filepath))    # 'report_final.csv'
 
# Obter o diretório
print(os.path.dirname(filepath))     # '/home/user/projects'
 
# Dividir em diretório e nome do arquivo
directory, filename = os.path.split(filepath)
print(directory)   # '/home/user/projects'
print(filename)    # 'report_final.csv'
 
# Dividir nome do arquivo e extensão
name, ext = os.path.splitext(filepath)
print(name)  # '/home/user/projects/report_final'
print(ext)   # '.csv'
 
# Obter caminho absoluto de um caminho relativo
print(os.path.abspath('data.csv'))   # '/home/user/projects/data.csv'
 
# Resolver diretório home do usuário
print(os.path.expanduser('~/Documents'))  # '/home/user/Documents'

Referência Rápida de Operações de Caminho

Variáveis de Ambiente

O módulo os fornece acesso direto às variáveis de ambiente do sistema -- essencial para ler configurações, chaves de API e configurações de implantação.

import os
 
# Ler uma variável de ambiente (retorna None se não definida)
db_host = os.getenv('DATABASE_HOST')
print(db_host)
 
# Ler com um valor padrão
db_port = os.getenv('DATABASE_PORT', '5432')
print(db_port)  # '5432' se DATABASE_PORT não estiver definida
 
# Acesso via dicionário os.environ (levanta KeyError se ausente)
try:
    secret = os.environ['API_SECRET']
except KeyError:
    print("API_SECRET não configurada")
 
# Definir uma variável de ambiente (para processos filhos)
os.environ['APP_MODE'] = 'production'
 
# Listar todas as variáveis de ambiente
for key, value in os.environ.items():
    print(f"{key}={value}")

A diferença entre os.getenv() e os.environ[] importa: getenv retorna None (ou um padrão) quando a variável está ausente, enquanto os.environ[] levanta um KeyError. Use getenv para configuração opcional e os.environ para configurações obrigatórias que devem falhar ruidosamente quando ausentes.

Percorrendo Árvores de Diretórios com os.walk

os.walk() percorre recursivamente uma árvore de diretórios, gerando uma tupla de 3 elementos (dirpath, dirnames, filenames) para cada diretório visitado.

import os
 
# Percorrer um diretório de projeto
for dirpath, dirnames, filenames in os.walk('/home/user/project'):
    # Pular diretórios ocultos
    dirnames[:] = [d for d in dirnames if not d.startswith('.')]
 
    print(f"\nDiretório: {dirpath}")
    print(f"  Subdiretórios: {dirnames}")
    print(f"  Arquivos: {filenames}")

A modificação in-place de dirnames[:] controla em quais subdiretórios o os.walk entra. Este é um padrão poderoso para pular diretórios .git, __pycache__ ou node_modules.

Calcular o Tamanho Total de um Diretório

import os
 
def get_directory_size(path):
    total = 0
    for dirpath, dirnames, filenames in os.walk(path):
        for filename in filenames:
            filepath = os.path.join(dirpath, filename)
            # Pular links simbólicos
            if not os.path.islink(filepath):
                total += os.path.getsize(filepath)
    return total
 
size_bytes = get_directory_size('/home/user/project')
size_mb = size_bytes / (1024 * 1024)
print(f"Tamanho total: {size_mb:.2f} MB")

Padrões Comuns

Encontrar Todos os Arquivos por Extensão

import os
 
def find_files(directory, extension):
    """Encontrar recursivamente todos os arquivos com uma extensão dada."""
    matches = []
    for dirpath, dirnames, filenames in os.walk(directory):
        for filename in filenames:
            if filename.endswith(extension):
                matches.append(os.path.join(dirpath, filename))
    return matches
 
# Encontrar todos os arquivos Python
python_files = find_files('/home/user/project', '.py')
for f in python_files:
    print(f)
 
# Encontrar todos os arquivos de dados CSV
csv_files = find_files('data', '.csv')
print(f"Encontrados {len(csv_files)} arquivos CSV")

Criar uma Estrutura de Saída Aninhada

import os
 
def setup_project_dirs(base_path):
    """Criar uma estrutura de diretórios de projeto padrão."""
    dirs = [
        'data/raw',
        'data/processed',
        'data/output',
        'logs',
        'config',
        'reports/figures',
    ]
    for d in dirs:
        full_path = os.path.join(base_path, d)
        os.makedirs(full_path, exist_ok=True)
        print(f"Criado: {full_path}")
 
setup_project_dirs('my_project')

Operações Seguras com Arquivos Temporários

import os
import tempfile
 
# Criar um arquivo temporário que se auto-deleta
with tempfile.NamedTemporaryFile(mode='w', suffix='.csv', delete=False) as tmp:
    tmp.write('col1,col2\n1,2\n3,4\n')
    tmp_path = tmp.name
 
print(f"Arquivo temporário: {tmp_path}")
print(f"Existe: {os.path.exists(tmp_path)}")
 
# Limpeza
os.remove(tmp_path)

os.path vs pathlib: Qual Você Deve Usar?

Python 3.4 introduziu pathlib como alternativa orientada a objetos ao os.path. Ambos funcionam, mas têm forças diferentes.

Quando usar os.path: Bases de código legadas, scripts que precisam suportar Python 2, ou quando trabalhar com bibliotecas que aceitam apenas caminhos como strings.

Quando usar pathlib: Projetos novos, quando quiser uma sintaxe mais limpa, ou quando encadear múltiplas operações de caminho.

# Abordagem os.path
import os
config_path = os.path.join(os.path.expanduser('~'), '.config', 'myapp', 'settings.json')
if os.path.isfile(config_path):
    with open(config_path) as f:
        data = f.read()
 
# Abordagem pathlib
from pathlib import Path
config_path = Path.home() / '.config' / 'myapp' / 'settings.json'
if config_path.is_file():
    data = config_path.read_text()

Ambas as abordagens são válidas. O módulo os não está obsoleto e continua sendo o padrão para operações a nível de processo, variáveis de ambiente e chamadas de sistema de baixo nível. pathlib simplesmente oferece uma API mais ergonômica para manipulação de caminhos.

Considerações Multiplataforma

O módulo os se adapta automaticamente ao sistema operacional atual, mas existem detalhes que valem a pena conhecer.

import os
 
# os.sep é o separador de caminho da plataforma
print(os.sep)       # '/' no Unix, '\\' no Windows
 
# os.linesep é o final de linha da plataforma
print(repr(os.linesep))  # '\n' no Unix, '\r\n' no Windows
 
# os.name identifica a família do sistema operacional
print(os.name)      # 'posix' no Linux/macOS, 'nt' no Windows
 
# os.path.join lida com separadores automaticamente
path = os.path.join('data', 'output', 'results.csv')
# 'data/output/results.csv' no Unix
# 'data\\output\\results.csv' no Windows

Regras-chave para scripts multiplataforma:

• Sempre use os.path.join() em vez de concatenação de strings com / ou \\.
• Use os.path.expanduser('~') em vez de codificar /home/username.
• Use os.linesep ou abra arquivos em modo texto (que lida com finais de linha) em vez de codificar \n.
• Teste sua lógica de caminhos em ambas as plataformas se seu script será compartilhado.

Automatizando Tarefas do Sistema de Arquivos com RunCell

Ao trabalhar com operações do sistema de arquivos em notebooks Jupyter -- organizando datasets, configurando estruturas de projeto ou auditando árvores de arquivos -- RunCell (opens in a new tab) adiciona uma camada de agente de IA sobre seu ambiente de notebook. Você pode descrever o que deseja ("encontre todos os arquivos CSV com mais de 100MB nesta árvore de diretórios e liste por tamanho") e o RunCell gera e executa o código do módulo os para você, tornando as tarefas repetitivas de gerenciamento de arquivos mais rápidas.

FAQ

O que é o módulo os no Python?

O módulo os faz parte da biblioteca padrão do Python. Ele fornece funções para interagir com o sistema operacional, incluindo manipulação de arquivos e diretórios, tratamento de caminhos, acesso a variáveis de ambiente e gerenciamento de processos. Você o importa com import os -- nenhuma instalação necessária.

Qual é a diferença entre os.path.join e concatenação de strings para caminhos?

os.path.join() usa automaticamente o separador de caminho correto para o sistema operacional atual (/ no Unix, \ no Windows). A concatenação de strings com + requer inserção manual de separadores, o que leva a bugs quando o código é executado em uma plataforma diferente. Sempre use os.path.join().

Como listo recursivamente todos os arquivos em um diretório?

Use os.walk() para percorrer uma árvore de diretórios. Ele gera tuplas (dirpath, dirnames, filenames) para cada diretório. Combine com os.path.join(dirpath, filename) para construir caminhos completos para cada arquivo.

Devo usar os.path ou pathlib?

Para novos projetos Python 3, pathlib oferece uma sintaxe mais limpa e legível com sua API orientada a objetos. No entanto, os e os.path não estão obsoletos e ainda são a escolha certa para variáveis de ambiente (os.environ), operações de processo e bases de código legadas. Muitos projetos usam ambos.

Como deleto de forma segura um arquivo ou diretório no Python?

Use os.remove(path) para deletar um arquivo e os.rmdir(path) para remover um diretório vazio. Sempre verifique primeiro com os.path.exists(path) ou envolva a chamada em um bloco try/except para tratar FileNotFoundError. Para diretórios não vazios, use shutil.rmtree(path).

Conclusão

O módulo os do Python é a base para cada operação do sistema de arquivos que seus scripts realizarão. os.path.join() constrói caminhos com segurança entre plataformas. os.makedirs() cria diretórios aninhados em uma única chamada. os.walk() percorre árvores de diretórios inteiras. os.environ e os.getenv() lidam com configuração sem codificar segredos. E os.stat() fornece metadados detalhados de arquivos.

Para código com muitos caminhos, considere combinar os com pathlib para uma sintaxe mais limpa. Mas o módulo os continua sendo essencial -- é a forma padrão de interagir com o sistema operacional em Python, e todo desenvolvedor Python deve conhecer suas funções principais.