🇯🇵 日本語 | 🇺🇸 English | 🇪🇸 Español | 🇵🇹 Português | 🇹🇭 ไทย | 🇨🇳 中文

Domine a manipulação de arquivos e diretórios com o módulo os do Python!

Para executar Python no prompt de comando ou PowerShell no seu PC, é necessário baixar e instalar o Python.
Se ainda não o fez, consulte o artigo Instalação do Python e configuração do ambiente de desenvolvimento para instalar o Python.

Ao gerenciar um site, muitas vezes você precisa manipular arquivos no servidor, como organizar imagens carregadas ou fazer backups regulares, certo? É nessas horas que o módulo os do Python se torna um grande aliado.

O módulo os é uma biblioteca padrão do Python para interagir com as funcionalidades do sistema operacional (SO), especialmente para manipular o sistema de arquivos. Com ele, você pode automatizar tarefas que normalmente faz com o mouse ou pela linha de comando, como criar, deletar e renomear arquivos e diretórios, tudo a partir de um programa.

Neste artigo, vamos apresentar muitos códigos prontos para copiar e colar, desde o uso básico do módulo os até exemplos práticos, para que criadores web como você possam usá-los imediatamente quando pensarem "quero automatizar uma pequena tarefa". Vamos deixar a teoria complicada para depois e primeiro experimentar a alegria de fazer as coisas funcionarem! 🚀


Uso básico do módulo os

Primeiro, o básico. Vamos ver a preparação para usar o módulo os e suas funções básicas mais comuns. Qualquer operação complexa é feita a partir da combinação desses fundamentos.

1. Importando o módulo os

Para usar o módulo os, primeiro você precisa importá-lo (carregá-lo) no início do seu script Python. É como uma palavra mágica, não é mesmo?

import os

2. Verificando o diretório de trabalho atual - getcwd()

Saber onde seu programa está sendo executado no momento (o diretório de trabalho atual) é fundamental para a operação. Você pode verificá-lo usando `os.getcwd()`. (getcwd é a abreviação de get current working directory).

import os

# Obter e exibir o diretório de trabalho atual
current_path = os.getcwd()
print(f"Diretório atual: {current_path}")

# Exemplo de resultado:
# Diretório atual: /Users/yourname/Documents

3. Criando um diretório - mkdir(), makedirs()

Vamos criar uma nova pasta (diretório). `os.mkdir()` cria um único diretório. Se você quiser criar uma hierarquia de diretórios aninhados de uma só vez, `os.makedirs()` é a melhor opção.

Primeiro, um exemplo criando apenas um diretório com `mkdir()`.

import os

# Criar um diretório chamado "my_project"
# Verifique se não existe um diretório com o mesmo nome antes de executar
if not os.path.exists("my_project"):
    os.mkdir("my_project")
    print("Diretório 'my_project' foi criado.")
else:
    print("O diretório 'my_project' já existe.")

Em seguida, com `makedirs()`, criaremos diretórios com uma relação pai/filho, como `parent/child`, de uma só vez. Adicionar `exist_ok=True` é uma aposta segura, pois evita erros se o diretório já existir.

import os

# Criar uma hierarquia de diretórios "contents/images" de uma vez
# Com exist_ok=True, não ocorrerá erro se o diretório já existir
os.makedirs("contents/images", exist_ok=True)
print("O diretório 'contents/images' foi criado (ou já existia).")

4. Obtendo uma lista de arquivos e diretórios - listdir()

Se você quer saber quais arquivos e pastas estão dentro de um diretório específico, use `os.listdir()`. Se você não especificar um caminho como argumento, ele retornará uma lista do diretório de trabalho atual.

import os

# Obter a lista de arquivos e diretórios do diretório atual
# Se você criou "my_project" ou "contents" anteriormente, eles serão exibidos
items = os.listdir('.') # '.' refere-se ao diretório atual
print(f"Conteúdo do diretório atual: {items}")

# Exemplo de resultado:
# Conteúdo do diretório atual: ['my_project', 'contents', 'my_script.py']

5. Juntando caminhos de forma segura - path.join()

Concatenar strings de caminho manualmente como `"folder" + "/" + "file.txt"` é arriscado! Isso porque o caractere separador de caminho difere entre os sistemas operacionais (Windows usa `\`, enquanto Mac e Linux usam `/`). `os.path.join()` é muito seguro porque une os caminhos com o separador apropriado para o SO em que está sendo executado.

import os

# Junção de caminho segura e independente do SO
dir_name = "assets"
file_name = "style.css"

# Este código funciona corretamente no Windows, Mac e Linux
correct_path = os.path.join(dir_name, "css", file_name)
print(f"Caminho gerado: {correct_path}")

# Exemplo de resultado (Mac/Linux):
# Caminho gerado: assets/css/style.css

# Exemplo de resultado (Windows):
# Caminho gerado: assets\css\style.css

6. Renomeando / Movendo um arquivo ou diretório - rename()

`os.rename()` pode ser usado não apenas para alterar o nome de um arquivo ou diretório, mas também para movê-lo. Se você especificar um diretório diferente como destino, poderá movê-lo para lá.

import os

# Criar um arquivo de teste chamado "old_name.txt"
with open("old_name.txt", "w") as f:
    f.write("test")

# Renomear "old_name.txt" para "new_name.txt"
if os.path.exists("old_name.txt"):
    os.rename("old_name.txt", "new_name.txt")
    print("Renomeado old_name.txt para new_name.txt.")

# Confirmação
print(f"Conteúdo do diretório atual: {os.listdir('.')}")

7. Deletando um arquivo ou diretório - remove(), rmdir()

Deletar arquivos e diretórios também é fácil. Use `os.remove()` para deletar um arquivo e `os.rmdir()` para deletar um diretório vazio. Tenha cuidado, pois `rmdir()` não pode deletar um diretório que contenha arquivos.

import os

# Criar um arquivo de teste chamado "temp_file.txt"
with open("temp_file.txt", "w") as f:
    f.write("delete me")

# Criar um diretório de teste chamado "temp_dir"
if not os.path.exists("temp_dir"):
    os.mkdir("temp_dir")

# Deletar o arquivo
if os.path.exists("temp_file.txt"):
    os.remove("temp_file.txt")
    print("temp_file.txt foi deletado.")

# Deletar o diretório vazio
if os.path.exists("temp_dir"):
    os.rmdir("temp_dir")
    print("temp_dir foi deletado.")

【Na Prática】Vamos usar o módulo os!

Agora que você entende o básico, vamos ver alguns códigos mais práticos. Estes exemplos podem facilitar um pouco suas tarefas diárias.

Exemplo de aplicação 1: Organizar múltiplos arquivos de imagem por extensão

Sua pasta de downloads ou de recursos está uma bagunça com arquivos de imagem como JPG, PNG e SVG misturados? Aqui está um script que os classifica automaticamente em pastas com base em sua extensão de arquivo.

import os

# --- Preparação: Criar arquivos de teste para serem organizados ---
# Criar um diretório de trabalho chamado "image_sorter"
base_dir = "image_sorter"
os.makedirs(base_dir, exist_ok=True)

# Criar arquivos de imagem de teste
dummy_files = ["cat.jpg", "dog.png", "logo.svg", "photo.jpg", "icon.png"]
for fname in dummy_files:
    # Gerar o caminho de forma segura usando os.path.join
    with open(os.path.join(base_dir, fname), "w") as f:
        f.write(f"This is {fname}.")

print(f"Conteúdo de {base_dir} antes da organização: {os.listdir(base_dir)}")
print("-" * 20)
# --- Fim da preparação ---


# --- Processo principal: Organizar os arquivos ---
# Especificar o diretório a ser organizado
target_dir = "image_sorter"

# Obter todos os arquivos no diretório
for filename in os.listdir(target_dir):
    # Gerar o caminho completo do arquivo
    full_path = os.path.join(target_dir, filename)

    # Se não for um arquivo (= é um diretório), pule-o
    if not os.path.isfile(full_path):
        continue

    # Obter a extensão do nome do arquivo (ex: ".jpg")
    # os.path.splitext é uma função útil que divide o nome do arquivo e a extensão
    ext = os.path.splitext(filename)[1] # Obter o segundo elemento de ("cat", ".jpg")

    # Pular arquivos sem extensão
    if not ext:
        continue

    # Criar uma pasta com o nome da extensão sem o "." (ex: pasta "jpg")
    # Converter a extensão para minúsculas para consistência
    folder_name = ext[1:].lower()
    ext_dir = os.path.join(target_dir, folder_name)

    # Criar a pasta se ela não existir
    os.makedirs(ext_dir, exist_ok=True)

    # Mover o arquivo para a nova pasta
    new_path = os.path.join(ext_dir, filename)
    os.rename(full_path, new_path)
    print(f"Moveu {filename} para a pasta {folder_name}.")

print("-" * 20)
print(f"Conteúdo de {base_dir} após a organização: {os.listdir(base_dir)}")
print(f"Conteúdo da pasta jpg: {os.listdir(os.path.join(base_dir, 'jpg'))}")
print(f"Conteúdo da pasta png: {os.listdir(os.path.join(base_dir, 'png'))}")

【Copie e Cole OK】Código para gerar automaticamente um ambiente de teste na sua área de trabalho

Depois de ler até aqui, alguns de vocês podem estar se perguntando: "Eu quero tentar isso no meu PC, mas onde devo executá-lo?". Por isso, preparamos um código Python "pronto para rodar" que você pode simplesmente copiar, salvar como um arquivo tipo `create_test_env.py` e executar para gerar automaticamente uma pasta e arquivos de teste na área de trabalho do seu PC. Verifique sua área de trabalho após executá-lo!

(※Este código cria uma pasta chamada `python_os_test` na sua área de trabalho. Por favor, delete a pasta quando não precisar mais dela.)

<!DOCTYPE html>
<html lang="pt">
<head>
    <meta charset="UTF-8">
    <title>Exemplo de código do módulo os do Python</title>
    <style>
        body { background-color: #202124; color: #e8eaed; font-family: sans-serif; }
        pre { background-color: #282c34; color: #abb2bf; padding: 1em; border-radius: 5px; overflow-x: auto; }
        code { font-family: 'Courier New', Courier, monospace; }
        h1 { color: #669df6; }
        p { line-height: 1.6; }
    </style>
</head>
<body>
    <h1>Código Python: Gerar um ambiente de teste na área de trabalho</h1>
    <p>Copie o código Python abaixo, salve-o como `create_test_env.py` e execute `python create_test_env.py` no seu terminal ou prompt de comando.</p>
<pre><code>
import os
import sys

def create_test_environment():
    """
    Uma função para gerar diretórios e arquivos de teste na área de trabalho.
    """
    try:
        # 1. Obter o caminho da área de trabalho
        # os.path.expanduser('~') obtém o diretório home do usuário
        desktop_path = os.path.join(os.path.expanduser('~'), 'Desktop')

        # Para ambientes de SO sem área de trabalho (como um servidor CUI), use o diretório atual
        if not os.path.exists(desktop_path):
            desktop_path = os.getcwd()
            print(f"Área de trabalho não encontrada. Criando no diretório atual: {desktop_path}")

        # 2. Criar a pasta de teste principal
        main_test_dir = os.path.join(desktop_path, "python_os_test")
        os.makedirs(main_test_dir, exist_ok=True)
        print(f"Pasta principal criada: {main_test_dir}")

        # 3. Criar subpastas
        sub_dirs = ["documents", "images", "archives"]
        for sub_dir in sub_dirs:
            os.makedirs(os.path.join(main_test_dir, sub_dir), exist_ok=True)

        print(f"Subpastas criadas: {sub_dirs}")

        # 4. Criar arquivos de teste
        files_to_create = {
            "documents": ["report.txt", "memo.md"],
            "images": ["cat.jpg", "dog.png"],
            "": ["readme.txt"] # Diretamente na pasta principal
        }

        for directory, filenames in files_to_create.items():
            for filename in filenames:
                file_path = os.path.join(main_test_dir, directory, filename)
                with open(file_path, "w", encoding="utf-8") as f:
                    f.write(f"Este é o conteúdo de teste para {filename}.")

        print("Arquivos de teste criados.")
        print("\n")
        print("🎉 Configuração concluída!")
        print(f"Por favor, verifique o diretório {main_test_dir}.")

    except OSError as e:
        print(f"Ocorreu um erro: {e}", file=sys.stderr)
        print("Isso pode ser um problema de permissões ou um problema com o caminho.", file=sys.stderr)
    except Exception as e:
        print(f"Ocorreu um erro inesperado: {e}", file=sys.stderr)

if __name__ == "__main__":
    create_test_environment()
</code></pre>
</body>
</html>

3 Pontos de Atenção

O módulo os é poderoso, mas como ele manipula diretamente o sistema de arquivos, há alguns pontos com os quais se deve ter cuidado. Apenas conhecê-los pode prevenir muitos erros.

  1. Especificação incorreta do caminho
    A maioria dos erros "No such file or directory" (FileNotFoundError) é causada por especificações de caminho incorretas. Crie o hábito de verificar sua localização atual com `os.getcwd()` e de verificar previamente a existência do seu alvo com `os.path.exists()`.
  2. Não negligencie o tratamento de erros
    Tentar criar um diretório existente com `os.mkdir()` ou deletar um arquivo inexistente com `os.remove()` fará com que seu programa trave. Escrever seu código para lidar com erros potenciais usando verificações prévias com `os.path.exists()` ou blocos `try...except` resultará em um programa mais robusto.
  3. Operações irreversíveis
    Operações como `os.remove()` e `os.rename()` geralmente não são "desfazíveis". Elas não usam o recurso da lixeira do PC. Especialmente ao lidar com arquivos importantes, é mais seguro adicionar uma etapa intermediária, como movê-los primeiro para uma pasta de backup, em vez de deletá-los diretamente.

Ainda mais conveniente! Introdução a módulos relacionados

O módulo os é fundamental, mas também existem bibliotecas mais modernas e convenientes. Como próximo passo, é uma boa ideia conhecer essas bibliotecas também.

pathlib - Manipulação de caminhos moderna e intuitiva

`pathlib`, adicionado à biblioteca padrão no Python 3.4, é um módulo que permite tratar caminhos como objetos de forma intuitiva. Como são objetos em vez de strings, você pode encadear métodos, juntar caminhos com o operador `/` e, em geral, escrever um código mais limpo.

from pathlib import Path

# Obter o diretório atual como um objeto Path
p = Path('.')

# Criação de diretório usando pathlib
new_dir = p / "pathlib_test" # Você pode juntar caminhos com o operador /!
new_dir.mkdir(exist_ok=True) # Executar como um método

# Listar arquivos também é fácil
for item in p.iterdir():
    print(f"{'Diretório' if item.is_dir() else 'Arquivo'}: {item.name}")

shutil - Operações de arquivo de alto nível

`shutil` (shell utilities) fornece operações de arquivo de nível mais alto que o módulo os. Por exemplo, copiar ou deletar um diretório com seu conteúdo, o que exigiria que você escrevesse uma função recursiva com o módulo os, pode ser feito em uma única linha com `shutil`.

import shutil
import os

# --- Preparação ---
os.makedirs("source_dir/sub_dir", exist_ok=True)
with open("source_dir/sub_dir/data.txt", "w") as f:
    f.write("important data")

# --- Exemplo de uso do shutil ---

# Copiar um diretório inteiro
if os.path.exists("source_dir"):
    shutil.copytree("source_dir", "backup_dir")
    print("Copiado source_dir para backup_dir.")

# Deletar um diretório e seu conteúdo
if os.path.exists("backup_dir"):
    shutil.rmtree("backup_dir")
    print("Deletado backup_dir e seu conteúdo.")

# Também deletar o source_dir agora desnecessário
shutil.rmtree("source_dir")

Conclusão

Neste artigo, cobrimos tudo, desde o básico até exemplos de aplicação de manipulação de arquivos e diretórios usando o módulo os do Python. Nos bastidores do desenvolvimento web, ocorrem muitas operações de arquivo tediosas como essas. Ao dominar o módulo os, você será capaz de automatizar essas tarefas manuais irritantes e se concentrar mais no seu trabalho criativo.

Primeiro, tente copiar e colar o código deste artigo para ter a sensação de "fazer os arquivos se moverem com um programa!" A partir daí, tente personalizá-lo para atender às suas próprias necessidades de trabalho!

Para o Próximo Passo

Depois da manipulação de arquivos, por que não explorar o mundo da computação numérica? Com o módulo math do Python, você pode facilmente realizar vários cálculos matemáticos, como funções trigonométricas e logaritmos.

➡️ Dominando funções matemáticas com o módulo math