# Juntar e dividir PDF com Python: pypdf e pikepdf

Para juntar e dividir PDF com Python, use pypdf ou pikepdf. Veja código testado, quando escolher cada biblioteca e os limites de cada uma.

URL canônica: https://www.ajustapdf.com/blog/pdf-com-python-pypdf-pikepdf

Publicado em 2026-09-24 · 5 min de leitura

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:

| Tarefa | Biblioteca indicada | Por quê |
| --- | --- | --- |
| Juntar arquivos inteiros | pypdf (append) ou pikepdf (pages.extend) | Os dois copiam as páginas na ordem da lista |
| Extrair um intervalo de páginas | pypdf, com fatiamento da lista de páginas | Código curto, sem mexer em objetos internos |
| Abrir arquivo com senha | pikepdf, com o parâmetro password | Erro específico para senha errada ou ausente |
| Trabalhar com a estrutura do arquivo | pikepdf | Acesso direto aos objetos, como o qpdf faz na linha de comando |

## 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](/blog/comprimir-pdf-ghostscript-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](/blog/api-de-pdf-para-desenvolvedores) é 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](/juntar-pdf) do AjustaPDF resolve a operação sem código, e o guia sobre [automatizar PDF com n8n, Make ou Zapier](/blog/automatizar-pdf-n8n-make-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](/blog/pdf-em-node-com-pdf-lib). Para o terminal, a mesma operação de junção aparece no guia sobre [juntar e comprimir PDF no Linux](/blog/juntar-e-comprimir-pdf-no-linux).

## Perguntas frequentes

### Qual biblioteca Python serve para juntar PDF, pypdf ou pikepdf?

Para juntar arquivos inteiros e extrair páginas, pypdf é a escolha mais simples, porque append() adiciona cada arquivo na ordem da lista. Escolha pikepdf quando quiser trabalhar com a estrutura do arquivo ou abrir PDFs com senha. Ele é uma camada sobre o qpdf, o mesmo motor de junção que o AjustaPDF usa.

### Como abrir um PDF com senha em Python?

Com pikepdf, passe a senha em pikepdf.open('arquivo.pdf', password='senha'). Se a senha estiver errada ou faltar, a biblioteca levanta pikepdf.PasswordError, que pode ser capturado para mostrar uma mensagem. Sem a senha de abertura, o arquivo não é lido.

### Dá para comprimir PDF com pypdf ou pikepdf?

Nenhuma das duas reduz a resolução das imagens como o Ghostscript faz. pikepdf salva o arquivo com a compressão do qpdf, que não perde qualidade e tem pouco efeito em páginas escaneadas. Para reduzir fotos, chame o Ghostscript a partir do Python com subprocess.

### Como dividir um PDF em uma página por arquivo?

Abra o arquivo com pikepdf, percorra pdf.pages com enumerate e, para cada página, crie um pikepdf.new(), anexe a página com append e salve com um nome numerado. O código deste guia gera pagina-1.pdf, pagina-2.pdf e assim por diante, um arquivo por página.

### Preciso instalar algo além do pip para usar pypdf e pikepdf?

Em geral, não. Os dois são instalados com pip install pypdf pikepdf, sem compilar nada em um computador comum. Use um ambiente virtual com python3 -m venv, para não misturar as versões com outros projetos.