Juntar e dividir PDF com Python: pypdf e pikepdf

Para juntar PDF em Python, instale o pypdf com pip install pypdf e use PdfWriter: o método append() adiciona cada arquivo na ordem da lista, e write() grava o resultado. Para dividir o arquivo ou trabalhar com sua estrutura interna, o pikepdf é a alternativa, porque é uma camada sobre o qpdf. Os exemplos deste guia foram testados com pypdf 6.20.1 e pikepdf 10.17.0.

Pypdf ou pikepdf: qual usar

As duas bibliotecas resolvem a maior parte dos casos. A tabela mostra onde cada uma se encaixa melhor:

Instalar em um ambiente virtual

Crie um ambiente virtual dentro da pasta do projeto e instale as duas bibliotecas nele. Assim, as versões do projeto não se misturam com as de outros programas no computador:

python3 -m venv .venv && .venv/bin/pip install pypdf pikepdf

No Windows, o programa do ambiente fica em .venv\Scripts\python. Depois da instalação, rode pip show pypdf pikepdf e anote as versões no projeto, para saber com o que o código foi testado.

Juntar com pypdf

O script abaixo junta dois arquivos na ordem em que aparecem na lista. O append() aceita o caminho do arquivo, e o write() grava o PDF final:

from pypdf import PdfWriter

writer = PdfWriter()
writer.append('01.pdf')
writer.append('02.pdf')
writer.write('juntado.pdf')

Para incluir mais arquivos, adicione uma linha de append() para cada um, ou percorra uma lista de nomes ordenada. Quem junta uma pasta inteira deve ordenar os nomes antes, porque a ordem de leitura do sistema de arquivos não é garantida. Os nomes com prefixo numérico, como 01-rg.pdf, resolvem isso.

Extrair um intervalo com pypdf

Para pegar só algumas páginas, leia o arquivo e copie as páginas desejadas para um PdfWriter novo. O fatiamento usa a numeração do Python, que começa em zero, então a primeira página é o índice 0:

from pypdf import PdfReader, PdfWriter

leitor = PdfReader('entrada.pdf')
writer = PdfWriter()
for pagina in leitor.pages[:40]:
    writer.add_page(pagina)
writer.write('parte1.pdf')

Para a parte seguinte, troque o fatiamento por [40:80] ou por [80:]. Esse é o mesmo raciocínio de quem divide um arquivo grande para cumprir o limite de um portal. Para escolher onde cortar, o guia sobre dividir PDF por capítulo ou intervalo mostra os critérios.

Juntar e abrir com senha usando pikepdf

O pikepdf trabalha com um objeto de destino vazio, pikepdf.new(), e puxa as páginas de cada origem com pages.extend(). Abra as origens antes, mantenha-as abertas até salvar e feche-as depois. Quando o arquivo tem senha para abrir, o parâmetro password resolve, e a senha errada gera um erro que o script pode tratar:

import pikepdf

saida = pikepdf.new()
origens = [pikepdf.open(nome, password='senha') for nome in ['01.pdf', '02.pdf']]
for origem in origens:
    saida.pages.extend(origem.pages)
saida.save('juntado.pdf')
for origem in origens:
    origem.close()

Como o pikepdf usa o qpdf por baixo, a junção segue a mesma lógica do AjustaPDF: copia as páginas e o que pertence a cada uma, e deixa de lado o que pertence ao documento inteiro, como os marcadores. Confira o resultado com um leitor antes de confiar no arquivo final.

Dividir em uma página por arquivo

Quando cada página precisa virar um arquivo, percorra as páginas e salve uma por vez. O nome numerado mantém a ordem na pasta:

import pikepdf

with pikepdf.open('entrada.pdf') as pdf:
    for i, pagina in enumerate(pdf.pages, start=1):
        novo = pikepdf.new()
        novo.pages.append(pagina)
        novo.save('pagina-%d.pdf' % i)

Esse código faz algo parecido com a divisão sem intervalo do AjustaPDF, que gera um arquivo por página dentro de um ZIP. Em um PDF com fotos, cada parte leva as imagens que a página usa, então o tamanho de cada arquivo mostra o peso daquela página. Fontes compartilhadas aparecem em todos.

O que as bibliotecas não fazem

Nenhuma das duas reduz imagens como o Ghostscript faz. Para isso, chame o programa a partir do Python com subprocess.run, passando os mesmos parâmetros do guia de comprimir com Ghostscript e qpdf. Também não há OCR: um escaneado continua sem texto pesquisável depois de juntado. E as bibliotecas não convertem PDF em Word, então a conversão exige outro programa.

Um cuidado para código que roda em servidor: o arquivo do usuário fica no disco enquanto o script processa. Apague os temporários ao fim da operação, e não grave o conteúdo em log. Se a sua aplicação recebe arquivos de clientes e não quer manter a infraestrutura, a API HTTP do AjustaPDF é outra saída, com as cotas do plano sem conta descritas no guia.

Quando um script resolve melhor que um site

Um script vale a pena quando a tarefa se repete: todo mês, juntar os comprovantes de cem clientes, ou dividir arquivos que chegam de um sistema. Para um arquivo por vez, o site é mais rápido. A ferramenta de juntar PDF do AjustaPDF resolve a operação sem código, e o guia sobre automatizar PDF com n8n, Make ou Zapier mostra como ligar a API a uma automação sem escrever o laço de arquivos.

Se a sua stack é JavaScript, o caminho equivalente está no guia sobre PDF em Node.js com pdf-lib. Para o terminal, a mesma operação de junção aparece no guia sobre juntar e comprimir PDF no Linux.