Formato Shapefile: O Guia Completo e Definitivo

Alguém te mandou "um shapefile" e é uma pasta com cinco arquivos de mesmo nome. Ou uma camada que você exportou do QGIS aparece no meio do Atlântico. Ou um colega abriu a sua tabela de atributos e todo acento virou é. Este guia é para quem precisa resolver isso hoje, e para o desenvolvedor a quem disseram para "simplesmente suportar Shapefiles" e que quer saber no que está se metendo. A versão curta primeiro: um Shapefile é o formato vetorial da ESRI dos anos 1990 — um .shp com a geometria, um .dbf com os atributos, um índice .shx e, na prática, um .prj com o sistema de coordenadas, todos com o mesmo nome-base.

Tudo o que é factual nesta página foi testado, não copiado. Construímos Shapefiles a partir de GeoJSON com o GDAL 3.13.3 "Iowa City", apagamos os arquivos-satélite um de cada vez, lemos os bytes do .dbf com um leitor hex, forçamos erros de encoding de propósito e citamos os erros exatos que o GDAL imprime. Quando uma afirmação vem da ESRI Shapefile Technical Description (julho de 1998) em vez do nosso terminal, a gente avisa. Tudo aqui foi verificado em 10 de setembro de 2026.

Uma coisa logo de cara: o Shapefile é um formato dos anos 1990 que continua sendo a forma mais amplamente aceita de trocar dados vetoriais, e a sua especificação está congelada, então nenhum dos seus problemas será corrigido. Este guia não está aqui para te dizer para parar de usá-lo. Está aqui para você saber exatamente quais dos seus dados ele vai destruir, e como tirar os dados de lá intactos.

O que é um Shapefile: os arquivos .shp, .shx, .dbf e .prj

Um Shapefile não é um arquivo. É um conjunto de arquivos que compartilham o mesmo nome-base e diferem pela extensão, e um leitor precisa de vários deles ao mesmo tempo. O Shapefile "quebrado" mais comum é um arquivo enviado sem os outros.

• .shp — obrigatório. A geometria. Cada registro é um código de tipo de forma seguido de coordenadas. Não há dado de atributo aqui, nem sistema de coordenadas.
• .shx — obrigatório. Um índice de largura fixa: para cada registro, o seu deslocamento em bytes dentro do .shp, para que um leitor possa pular direto para uma feição.
• .dbf — obrigatório. A tabela de atributos, no formato dBASE. O registro n no .dbf pertence à forma n no .shp; nada além da posição os liga.
• .prj — obrigatório na prática. Um arquivo de texto de uma linha com o sistema de referência de coordenadas em WKT. A especificação de 1998 não o menciona, motivo pelo qual tantos Shapefiles antigos são distribuídos sem ele e pelo qual "minha camada está no oceano" é a pergunta de suporte mais comum em GIS.
• .cpg — opcional. Um arquivo de texto de uma linha nomeando o encoding do .dbf, por exemplo UTF-8. Sem ele, os leitores chutam.
• .sbn e .sbx — opcional. O índice espacial da ESRI; o ArcGIS os escreve, ferramentas baseadas em GDAL os leem mas nunca os escrevem, então eles ficam desatualizados depois da primeira edição feita em outro lugar.
• .qix — opcional. O índice espacial aberto escrito pelo GDAL, QGIS e MapServer. Criamos um com ogrinfo src.shp -sql "CREATE SPATIAL INDEX ON src" e um src.qix apareceu ao lado do .shp.
• .shp.xml — opcional. Metadados do ArcGIS (título, resumo, linhagem) em XML. O ArcGIS também guarda ali os aliases dos campos, e o GDAL 3.13 ou mais novo lê o .shp.xml para restaurar nomes de campo com mais de 10 caracteres e os aliases; um Shapefile escrito pelo GDAL não tem esse arquivo (nenhuma das nossas exportações produziu um).
• .ain e .aih — opcional. Arquivos antigos de índice de atributos do ArcView. Você pode apagá-los.

Compacte-os juntos num zip e você tem um Shapefile portátil; o GDAL e o nosso visualizador leem o zip diretamente. Rodamos ogrinfo -so /vsizip/src.zip num zip contendo os cinco arquivos acima e ele listou 1: src (Point) exatamente como faz com os arquivos soltos.

Se o .shx estiver faltando

O GDAL recusa abrir a camada: ERROR 4: Unable to open src.shx or src.SHX. Set SHAPE_RESTORE_SHX config option to YES to restore or create it. O .shx pode ser reconstruído a partir do .shp, então a correção é o que a mensagem diz: ogrinfo -so src.shp --config SHAPE_RESTORE_SHX YES reconstruiu o índice, e depois disso havia um novo src.shx na pasta. Qualquer ferramenta baseada em GDAL, QGIS incluído, aceita a mesma opção.

Para as outras seis formas de um arquivo faltando quebrar um Shapefile, medidas no visualizador e no GDAL, leia Faltou o .shx ou o .dbf: por que o Shapefile não abre.

Se o .dbf estiver faltando

A camada ainda abre, e essa é a armadilha. Apagamos o .dbf e ogrinfo -al -so src.shp reportou Geometry: Point, Feature Count: 2 e o CRS completo, com zero campos. Formas no mapa, sem atributos, sem aviso. Se "os atributos sumiram", verifique o .dbf primeiro.

Se o .prj estiver faltando

A geometria abre, os atributos abrem, e o sistema de coordenadas é desconhecido. O GDAL imprime Layer SRS WKT: seguido de (unknown). Um GIS de desktop vai ou te perguntar por um CRS, assumir um, ou carregar a camada com um CRS desconhecido e um ponto de interrogação ao lado — o QGIS faz qualquer uma das três conforme as suas configurações — e se o arquivo está em metros UTM, uma camada tratada como graus não cai nem perto do mapa. A seção sobre o .prj abaixo é sobre esse caso.

Para o passo a passo — o que o GDAL, o QGIS e o nosso visualizador mostram para um arquivo sem .prj, como descobrir em qual CRS os números realmente estão, e a diferença entre atribuir e reprojetar — leia Shapefile no lugar errado: falta o .prj.

Se o .cpg estiver faltando

O arquivo abre e o texto pode estar errado. O cabeçalho do .dbf tem um byte de "language driver" no offset 29; o padrão do GDAL é 87, que ele trata como Latin-1 (o log de debug dele diz Treating as encoding 'ISO-8859-1'). Se os dados eram na verdade UTF-8, ou o leitor ignora o byte, os caracteres acentuados saem como mojibake. A seção do .dbf abaixo mostra os bytes.

Um tipo de geometria por arquivo

O cabeçalho do .shp carrega um tipo de forma para o arquivo inteiro, e cada registro precisa corresponder a ele. A especificação de 1998 define catorze códigos de tipo de forma: 0 para Null; 1, 3, 5 e 8 para Point, PolyLine, Polygon e MultiPoint; os mesmos quatro com Z (11, 13, 15, 18) e com M (21, 23, 25, 28); e 31 para MultiPatch, um tipo de superfície 3D da ESRI que quase nenhuma ferramenta aberta escreve. Na prática você encontra quatro tipos de arquivo — pontos, linhas, polígonos, multipontos — mais as suas variantes 3D.

Uma camada GeoJSON ou GeoPackage pode misturar pontos e linhas. Um Shapefile não pode. Convertemos um GeoJSON contendo um Point e uma LineString com ogr2ogr -f "ESRI Shapefile" out mixed.geojson. O GDAL criou um Shapefile de pontos a partir da primeira feição e então parou, imprimindo ERROR 1: Attempt to write non-point (LINESTRING) geometry to point shapefile., ERROR 1: Unable to write feature 1 from layer mixed. e Terminating translation prematurely after failed translation of layer mixed (use -skipfailures to skip errors). O código de saída foi 1 e a saída continha uma feição. Se você precisa dos dois, precisa de dois Shapefiles; se você só precisa que termine, -skipfailures ainda imprime o mesmo ERROR 1 para cada feição incompatível, mas a descarta e sai com 0, então leia o log antes de confiar na contagem.

Duas sutilezas que não parecem a regra, mas são:

• Um arquivo de polígonos guarda polígonos simples e multipartes lado a lado. O formato não tem um tipo MultiPolygon separado; um registro Polygon simplesmente tem mais de um anel. O GDAL lê os dois casos de volta como POLYGON e MULTIPOLYGON na mesma camada, e é disso que o PostGIS e o QGIS reclamam como "tipos de geometria mistos" na importação. A correção é ogr2ogr -f GPKG out.gpkg in.shp -nlt PROMOTE_TO_MULTI; rodamos e a camada do GeoPackage saiu como Multi Polygon do início ao fim.
• Formas Null são válidas em qualquer arquivo. Um registro com tipo de forma 0 significa "atributos, sem geometria". Exportamos uma feição cuja geometria era null para um Shapefile de pontos e lemos o .shp bruto: o registro 1 tinha tipo de forma 1, o registro 2 tinha tipo de forma 0, e o ogrinfo listou os dois, o segundo com atributos e sem POINT. Alguns visualizadores descartam essas linhas; conte as suas feições depois da importação.

As variantes Z e M guardam uma elevação e uma "medida" por vértice. O GDAL as escreve quando pedido: ogr2ogr -f "ESRI Shapefile" out in.geojson -nlt POINTZ produziu um arquivo que o ogrinfo reporta como src (3D Point). A maioria das ferramentas web achata o Z na leitura.

O .prj e a camada no oceano

O .prj é uma única linha de WKT no dialeto da ESRI para o formato 1.0. Para WGS 84, o GDAL escreve GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]] — repare nos prefixos GCS_ e D_ e na ausência da cláusula AUTHORITY. Um .prj da ESRI não carrega o código EPSG; os leitores comparam os parâmetros com um banco de dados para recuperá-lo. Normalmente funciona; quando os parâmetros estão levemente errados, você recebe um "CRS customizado" com a forma certa e o nome errado.

O sintoma que todo mundo conhece: a camada carrega sem erro e aparece a milhares de quilômetros de distância, muitas vezes na latitude 0, longitude 0 na costa da África Ocidental — "no meio do oceano". Quase sempre as coordenadas são metros projetados com northings de sete dígitos, e o leitor está tratando-as como graus porque o .prj estava faltando ou errado.

Existem duas correções diferentes e elas não são intercambiáveis:

• Atribuir um CRS quando as coordenadas estão corretas e só falta o rótulo. Isso reescreve o .prj e não toca nas coordenadas. ogr2ogr -f "ESRI Shapefile" fixed in.shp -a_srs EPSG:31982 — rodamos num arquivo sem .prj e o ponto permaneceu em POINT (-48.5 -27.6) enquanto o novo .prj declarava SIRGAS_2000_UTM_Zone_22S. (O que, para uma coordenada em graus, agora é uma mentira. Atribuir o CRS errado é a segunda forma mais comum de colocar uma camada no oceano.)
• Reprojetar quando as coordenadas estão corretas em um CRS e você precisa delas em outro. Isso transforma cada vértice. ogr2ogr -f "ESRI Shapefile" out in.shp -s_srs EPSG:4326 -t_srs EPSG:31982 — o mesmo ponto virou POINT (746752.990849492 6944611.29529316), em metros.

No QGIS as mesmas duas operações são "Definir SRC da camada…" (atribuir) e "Exportar → Salvar feições como…" com um CRS diferente (reprojetar), e escolher a errada produz o mesmo desastre a partir do desktop. Se você não tem certeza de qual é o CRS de um arquivo, cole um dos seus pares de coordenadas no nosso conversor de coordenadas e teste sistemas candidatos até o ponto cair em algum lugar que você reconheça.

Datums regionais que você vai encontrar em arquivos .prj

Os nomes abaixo são o que o gdalsrsinfo reporta para cada código na nossa máquina; o .prj vai mostrar a grafia da ESRI, com underscores.

• EPSG:4674 — SIRGAS 2000, geográfico. O datum oficial do Brasil e da maior parte da América do Sul, mantido pelo IBGE; para fins práticos coincide com o WGS 84. É o código que você deve esperar ver em qualquer levantamento brasileiro recente.
• EPSG:31982 — SIRGAS 2000 / UTM zona 22S, e EPSG:31983 para a zona 23S. Juntas, essas duas cobrem a maior parte de São Paulo, Paraná, Santa Catarina e Rio de Janeiro; a série 3197x/3198x continua pelas outras zonas do Brasil. São os dois códigos que você mais vai atribuir e reprojetar no dia a dia, porque boa parte dos dados de campo brasileiros nasce em uma dessas duas faixas.
• EPSG:4618 — SAD69, geográfico. O datum brasileiro que o SIRGAS 2000 substituiu; Shapefiles municipais e de concessionárias mais antigos ainda estão nele, com as zonas UTM EPSG:29192 (22S) e EPSG:29193 (23S). SAD69 e SIRGAS 2000 diferem por dezenas de metros, então "está perto o suficiente" não é uma resposta válida.
• EPSG:4225 — Córrego Alegre 1970-72, geográfico. O datum anterior ao SAD69; você o encontra em mapas cadastrais antigos e em Shapefiles digitalizados a partir deles. Entre SAD69, Córrego Alegre e o SIRGAS 2000 atual, um arquivo .prj sem AUTHORITY de uma prefeitura brasileira pode estar declarando qualquer um dos três, e é o IBGE quem mantém as tabelas de transformação entre eles.

Fora do Brasil, o EPSG:4326 (WGS 84, geográfico — o que receptores de GPS, GeoJSON e mapas web esperam; um .prj dizendo GCS_WGS_1984 é este), o EPSG:3857 (Pseudo-Mercator, a projeção dos tiles de mapa web) e o EPSG:4269 (NAD83, o padrão dos dados públicos dos Estados Unidos) aparecem com menos frequência nos seus dados, junto com as zonas UTM em WGS 84 — EPSG:32622 para a zona 22N e EPSG:32722 para a 22S, com as séries 326xx e 327xx cobrindo as demais.

Nos vizinhos latino-americanos:

• EPSG:4686 — MAGNA-SIRGAS, geográfico. O datum nacional da Colômbia.
• EPSG:9377 — MAGNA-SIRGAS 2018 / Origen-Nacional. A projeção nacional única da Colômbia, substituindo as origens regionais mais antigas.
• EPSG:5340 — POSGAR 2007, geográfico. O datum nacional da Argentina; as zonas projetadas vão de EPSG:5343 a EPSG:5349 (Argentina 1 a 7, Gauss-Krüger).
• EPSG:5360 — SIRGAS-Chile 2002, geográfico. O Chile re-realiza o seu referencial a cada poucos anos, então arquivos mais recentes podem dizer SIRGAS-Chile 2010, 2013, 2016 ou 2021.
• EPSG:6365 — Mexico ITRF2008, geográfico. O referencial nacional mexicano atual.

Se um .prj citar um destes e a camada ainda cair no oceano, o código errado provavelmente foi atribuído na exportação; teste os candidatos vizinhos antes de mexer nos dados.

O .dbf é onde dói

O lado da geometria de um Shapefile é apenas antigo. O lado dos atributos é onde os seus dados são danificados, silenciosamente, na saída. Empurramos um dataset pequeno — um campo chamado observation_notes, um valor UTF-8 de São João, um NULL, uma string vazia, uma nota de 300 caracteres e um timestamp ISO — através do ogr2ogr e lemos de volta o que sobreviveu.

Nomes de campo são cortados em 10 caracteres

O cabeçalho dBase guarda cada nome de campo em 11 bytes, um dos quais é um terminador. O GDAL avisa e então renomeia: Warning 6: Normalized/laundered field name: 'observation_notes' to 'observatio'. Quando dois nomes colidem, ele inventa um sufixo — observation_notes_final virou observat_1. Uma versão anterior deste guia dizia que Populacao_2026 vira Populaca_26; testamos isso, e está errado. O GDAL mantém os primeiros dez caracteres, então vira Populacao_. Seja o que for que a sua ferramenta faça, o ano se foi.

Isso é permanente. Converter o Shapefile de volta para GeoPackage nos deu campos ainda chamados observatio e observat_1. Os nomes não estão escondidos em lugar nenhum; eles nunca foram escritos.

Para a regra de colisão medida num segundo dataset, e o que um .shp.xml completo consegue e não consegue restaurar, leia Nome de coluna cortado em 10 caracteres.

Latin-1 por padrão, e o arquivo-satélite .cpg

Com um ogr2ogr -f "ESRI Shapefile" out in.geojson simples, o GDAL não escreveu nenhum arquivo .cpg, ajustou o byte de language driver no offset 29 para 87, e guardou São João como os bytes Latin-1 Jo\xe3o — a sequência UTF-8 não está em lugar nenhum do arquivo. O GDAL relê a própria saída corretamente porque ele respeita esse byte (a opção ENCODING do driver tem como padrão LDID/87). Um leitor que assume UTF-8 — a maioria do código web, a maioria dos scripts que abrem o .dbf diretamente — mostra Jo�o; uma ferramenta que recodifica o texto Latin-1 como UTF-8 e o exibe como Latin-1 mostra João, o dano estilo é em toda tabela de atributos latino-americana.

A correção do lado da escrita é uma opção: ogr2ogr -f "ESRI Shapefile" out in.geojson -lco ENCODING=UTF-8. A saída então inclui um src.cpg cujo conteúdo inteiro é UTF-8, o byte do cabeçalho é 0, e os bytes guardados são Jo\xc3\xa3o, UTF-8 genuíno. Do lado da leitura, quando alguém te entrega um arquivo Latin-1 cujo byte de cabeçalho não diz nada (0) e que não tem .cpg, diga ao GDAL: ogr2ogr -f GPKG out.gpkg in.shp --config SHAPE_ENCODING ISO-8859-1. Zeramos o byte de language driver do nosso próprio arquivo para reproduzir esse caso: sem a opção o GDAL leu S�o Jo�o, com ela São João voltou. (No arquivo como o GDAL o escreveu, byte de cabeçalho 87, a opção não muda nada — o GDAL já lê aquilo como Latin-1.)

Para as duas direções de mojibake reproduzidas no visualizador, mais a correção de uma linha com o .cpg, leia Acentos errados num Shapefile: .cpg, Latin-1 e UTF-8.

NULL e string vazia são a mesma coisa

O .dbf não tem marcador de NULL. Um campo de texto não definido é preenchido com espaços, e uma string vazia também. Escrevemos duas feições, uma com nota definida como null e outra com nota definida como ""; no .dbf os dois registros continham oitenta espaços, byte a byte idênticos, e o ogrinfo leu os dois de volta como (null). Depois de uma ida e volta pelo GeoPackage, o SQLite reportou typeof(nota) como null para os dois. "Não medido" e "medido, vazio" viraram um único valor, e a diferença não pode ser recuperada. Campos numéricos têm o mesmo problema de outra forma: alguns escritores guardam um número não definido como espaços em branco, outros como 0, e um leitor não consegue diferenciar o segundo de um zero de verdade.

254 caracteres de texto, datas sem hora, e números como texto

Um campo de caractere tem uma largura de um byte, então o teto é 254 caracteres. A nossa nota de 300 caracteres produziu Warning 1: Value '…' of field long_text has been truncated to 254 characters. This warning will not be emitted any more for that layer. — leia a última frase: a primeira truncagem é anunciada, toda truncagem seguinte é silenciosa. O campo voltou como String (254.0), contendo exatamente 254 caracteres.

Existe um tipo de data, D, e ele guarda uma data de calendário e nada mais. Um valor 2026-09-10 virou d: Date e sobreviveu. Um timestamp não: Warning 6: Field dt created as String field, though DateTime requested., e o campo virou String (29.0) — texto que toda ferramenta seguinte precisa parsear e torcer. Não há fuso horário e não há hora. Existe, sim, um booleano, apesar do que você já deve ter lido: o tipo lógico L existe, e um campo true/false que exportamos voltou como Integer(Boolean) com os valores 1 e 0. Essa reclamação específica é um mito.

Números são guardados como texto ASCII com uma largura e precisão fixas. Um campo de ponto flutuante voltou como Real (24.15) — 24 caracteres, 15 decimais — e o valor que escrevemos, 0.1234567890123456789, voltou como 0.123456789012346. Inteiros viram Integer (9.0) ou Integer64 (18.0), dependendo do tamanho. Isso é aceitável para medições e errado para identificadores que precisam corresponder exatamente.

2 GB, e o GDAL não vai te impedir

O .shp guarda os offsets como contagens de 32 bits de palavras de 16 bits e o .dbf não tem offset nenhum, então a própria spec não para nos 2 GB — esse teto é o que o software da ESRI e a maioria dos leitores impõem, e é o número para o qual todo mundo projeta. O que nós verificamos foi a atitude do GDAL: a opção de criação 2GB_LIMIT tem NO como padrão, então o GDAL escreve além do limite (com um único aviso ao cruzá-lo) e o próximo programa é quem falha — o ArcGIS, um MapServer antigo, um formulário de upload com limite de tamanho. Dados perto desse tamanho não deveriam ser um Shapefile. O nosso guia de GeoPackage cobre o formato que resolve todos os problemas desta seção, com os mesmos experimentos do lado oposto.

Como abrir um Shapefile sem o QGIS

Você não precisa de um GIS de desktop para olhar um Shapefile, ler os seus atributos ou descobrir em qual CRS ele está.

• Compacte os arquivos-satélite juntos. Selecione o .shp, .shx, .dbf e .prj (e o .cpg, se houver), e compacte-os num único .zip. Não compacte a pasta que os contém; compacte os arquivos. Um .shp sozinho mostra formas sem atributos.
• Arraste o zip para dentro do visualizador. Solte-o no nosso visualizador gratuito de Shapefile: ele aceita um .zip, um .shp sozinho, ou o .shp mais .dbf mais .prj soltos juntos, e desenha as feições num mapa. Clique numa feição para ler os seus atributos, área ou comprimento e copiar o seu WKT; abra a tabela de atributos para buscar e ordenar o arquivo inteiro; escolha uma coluna como rótulo do mapa. Até dez arquivos carregam lado a lado, que é a forma mais rápida de ver se duas camadas realmente se sobrepõem.
• Exporte direto do navegador. O visualizador escreve GeoJSON, KML e CSV, então "converter esse Shapefile para GeoJSON" é um arrastar e um clique, sem nada instalado.
• Privacidade. Todo o parsing acontece no seu navegador. Nenhum arquivo é enviado a nenhum servidor; os seus arquivos nunca saem do seu dispositivo. É isso que torna a ferramenta usável em dados que você não tem permissão de enviar para lugar nenhum.

No terminal, ogrinfo -so in.shp lista a camada e o seu tipo de geometria, e ogrinfo -al -so in.shp acrescenta os campos, a extensão e o CRS sem imprimir nenhuma feição. Os dois vêm com o GDAL, um único pacote para instalar no Linux, macOS e Windows.

Convertendo a partir do Shapefile

Todo comando desta seção foi executado contra arquivos reais antes da publicação, com o GDAL 3.13.3.

• Shapefile para GeoPackage: ogr2ogr -f GPKG out.gpkg in.shp. Os nomes de campo ficam como o .dbf os tem (já truncados), o texto vira UTF-8 de verdade, e os NULLs são o que quer que o Shapefile conseguisse expressar, que não é muito. O guia de GeoPackage cobre o que fazer a seguir.
• Shapefile para GeoPackage quando a fonte está em Latin-1 (assuma que está, a não ser que exista um .cpg dizendo o contrário): ogr2ogr -f GPKG out.gpkg in.shp --config SHAPE_ENCODING ISO-8859-1.
• Shapefile para GeoJSON para a web — sempre reprojete, a especificação do GeoJSON exige WGS 84: ogr2ogr -f GeoJSON -t_srs EPSG:4326 out.geojson in.shp. A saída declara urn:ogc:def:crs:OGC:1.3:CRS84. Se a entrada não tiver .prj, o comando falha com ERROR 1: Can't transform coordinates, source layer has no coordinate system. Use -s_srs to set one. — acrescente -s_srs com o CRS que você já estabeleceu.
• Corrija polígonos simples e multipartes misturados de passagem: ogr2ogr -f GPKG out.gpkg in.shp -nlt PROMOTE_TO_MULTI.
• Shapefile para KML para o Google Earth: ogr2ogr -f KML out.kml in.shp. O driver de KML reprojeta para WGS 84 sozinho — o nosso arquivo em UTM saiu com <coordinates>-48.5,-27.6 — e escreve os atributos dentro de cada placemark. Um KMZ é o mesmo KML dentro de um zip; construir e abrir um está coberto no nosso guia de como visualizar KMZ online.
• Escrevendo um Shapefile sem quebrar os acentos: ogr2ogr -f "ESRI Shapefile" out_dir in.gpkg -lco ENCODING=UTF-8. Você ainda vai perder os nomes de campo além de dez caracteres e todo timestamp; a opção só corrige o encoding.
• Só algumas feições: ogr2ogr -f GPKG out.gpkg in.shp -where "status = 1" filtra por atributos, e -clipsrc xmin ymin xmax ymax recorta para uma caixa.
• Reconstrua um arquivo de índice perdido: ogr2ogr -f "ESRI Shapefile" fixed in.shp --config SHAPE_RESTORE_SHX YES. Rodamos numa pasta sem .shx; a cópia em fixed tinha um, e a pasta de origem também passou a ter depois — a opção restaura o índice no lugar.

A flag -nln nomeia a camada de saída em formatos que têm nomes de camada; pule-a e você herda o nome-base do Shapefile, o que é tranquilo até esse nome ser export (2) final.

Erros, decodificados

Cada entrada é sintoma, causa, correção. As mensagens são citadas do GDAL 3.13.3; o QGIS mostra o mesmo texto no seu painel de log.

"Unable to open .shx"

Sintoma: ERROR 4: Unable to open in.shx or in.SHX. Set SHAPE_RESTORE_SHX config option to YES to restore or create it. e a camada não carrega. Causa: o arquivo-satélite de índice não foi copiado junto com o .shp. Correção: ogrinfo -so in.shp --config SHAPE_RESTORE_SHX YES o reconstrói no lugar; depois copie o conjunto inteiro da próxima vez.

"Layer has no CRS" ou (unknown)

Sintoma: ogrinfo imprime Layer SRS WKT: e depois (unknown); o QGIS mostra um ponto de interrogação ao lado da camada ou pede um CRS. Causa: sem .prj. Correção: descubra o que são as coordenadas (dois dígitos antes do ponto são graus, EPSG:4326; eastings de seis dígitos com northings de sete dígitos no Brasil são uma zona 3198x), então atribua, não reprojete: ogr2ogr -f "ESRI Shapefile" fixed in.shp -a_srs EPSG:31982.

"Normalized/laundered field name"

Sintoma: Warning 6: Normalized/laundered field name: 'observation_notes' to 'observatio' na exportação, e um colega depois pergunta o que observat_1 significa. Causa: o limite de 10 caracteres. Correção: nenhuma dentro do .dbf; o ArcGIS guarda o nome longo como alias no .shp.xml, e o GDAL 3.13+ o lê de volta — um Shapefile escrito pelo GDAL não tem esse arquivo. Renomeie os campos para dez caracteres ou menos antes de exportar, para que você escolha as abreviações, ou mantenha um GeoPackage e trate o Shapefile como uma cópia com perdas.

Acentos aparecem como é ou �

Sintoma: São João aparece como São João ou S�o Jo�o. Causa: um .dbf em Latin-1 lido como UTF-8, ou o inverso; não há .cpg para resolver isso. Correção: na leitura, --config SHAPE_ENCODING ISO-8859-1 (ou UTF-8, o que quer que o arquivo realmente seja); na escrita, -lco ENCODING=UTF-8 para que um .cpg seja escrito e o próximo leitor não precise adivinhar.

"File too large" ou um .dbf que outros softwares rejeitam

Sintoma: o GDAL escreveu o arquivo, imprimindo um único aviso ao cruzar os 2 GB; o ArcGIS, um formulário de upload ou uma biblioteca mais antiga o recusa, ou lê lixo depois de alguma feição. Causa: um .shp ou .dbf além de 2 GB, o que o GDAL permite por padrão (2GB_LIMIT=NO). Correção: divida os dados, ou pare de usar Shapefile para isso — ogr2ogr -f GPKG out.gpkg in.shp não tem esse teto.

"Attempt to write non-point geometry to point shapefile"

Sintoma: ERROR 1: Attempt to write non-point (LINESTRING) geometry to point shapefile. seguido de Terminating translation prematurely, e uma saída com menos feições do que a entrada. Causa: a fonte mistura tipos de geometria e um Shapefile guarda um só. Correção: exporte um Shapefile por tipo com o filtro de geometria — ogr2ogr -f "ESRI Shapefile" points in.geojson -where "OGR_GEOMETRY='POINT'" e de novo com 'LINESTRING'; rodamos os dois e obtivemos uma camada Point e uma camada Line String sem erros. Ou mantenha os dados num formato que permita a mistura.

Feições não desenham, ou desenham no oceano

Sintoma: a camada carrega sem erro e fica invisível, ou fica na latitude 0, longitude 0. Causa: um .prj faltando ou errado, então metros projetados são lidos como graus ou o inverso. Correção: verifique ogrinfo -al -so in.shp procurando Layer SRS WKT; compare a linha Extent com o que os números deveriam parecer no CRS que você espera; atribua o CRS certo. Se a extensão estiver certa e a camada ainda estiver invisível, verifique o Feature Count — um arquivo de formas Null não tem nada para desenhar.

Shapefile vs GeoPackage vs GeoJSON

Sem tabela — só escolha a frase que corresponde à sua situação.

Shapefile ainda é a resposta certa quando o outro lado não aceita mais nada. Isso é real e comum: geoportais governamentais, sistemas municipais antigos, softwares de ativos de concessionárias, pacotes de topografia e um bom número de instalações do ArcGIS importam um Shapefile e nada mais, e é o formato com mais chance de abrir numa ferramenta da qual você nunca ouviu falar. Quando essa é a restrição, exporte com -lco ENCODING=UTF-8, escolha os seus nomes de campo de dez caracteres de propósito, envie o .prj junto, e mantenha o original num formato que não perdeu nada.

GeoPackage é a resposta certa quando os dados são seus para guardar: muitas camadas, tipos de geometria misturados, nomes de campo de verdade, NULLs de verdade, timestamps de verdade, um arquivo só com o CRS dentro dele. É o padrão correto para GIS de desktop e trabalho de campo, e o que um Shapefile deveria virar assim que chega.

GeoJSON é a resposta certa quando um navegador ou uma API vai lê-lo, ou um humano precisa abri-lo num editor de texto. Ele está preso ao WGS 84 por especificação, não tem índice e fica pesado depois de alguns megabytes — e nada disso importa para o caso de "mandar esses quarenta pontos para o frontend" para o qual ele existe.

E nenhum deles é certo quando várias pessoas precisam escrever ao mesmo tempo. Isso é um banco de dados, não um arquivo.

Para times que querem a versão medida dessa comparação — tamanhos, limites de nome de campo, encoding, CRS e tempo de carregamento num dataset real — leia Shapefile vs GeoPackage vs GeoJSON: qual usar.

Onde o Geodocs entra

A gente constrói o Geodocs, uma plataforma para times de dados de campo e de GIS, e escrevemos este guia porque boa parte do que os nossos usuários sobem é um Shapefile, e boa parte das conversas de suporte que vêm depois são um dos sete erros acima. Então a plataforma resolve: ela recebe um Shapefile zipado como um único upload, detecta o encoding do .dbf em vez de assumir um, lê o .prj e reprojeta para o mapa, e mantém os dados onde um nome de campo pode ter mais de dez caracteres e um NULL continua sendo um NULL. Se o seu time ainda está mandando pastas de cinco arquivos por e-mail e torcendo para o .prj ter chegado junto, esse é o problema que a gente existe para eliminar.

Encontrou um erro, ou uma armadilha que a gente deixou passar? Fala com a gente. A gente retesta esta página em vez de copiar e colar.

Última verificação: 10 de setembro de 2026, GDAL 3.13.3.