v.external.out(1grass)

📦
version 8.5.0 · 13 versions
, in ubuntu stonking

✨ v.external.out — the GRASS manual but make it make sense ✨

okay bestie, welcome to v.external.out from the GRASS User's Manual 💖 this one's all about telling GRASS where to put your vector output when it's not staying in native format.

KEYWORDS: vector, export, output, external, OGR, PostGIS 🦋

🌸 SYNOPSIS 🌸

v.external.out
v.external.out --help
v.external.out [-frpg]  [output=string]   [format=string]
[options=string[,string,...]]   [loadsettings=name]
[savesettings=name]   [--overwrite]  [--help]  [--verbose]  [--quiet]
[--ui]

🎀 Flags:

  • -f — lists all the formats it supports, then dips. literally just shows you the menu and leaves 💅
  • -r — stop using OGR/PostGIS, go back to native output, and exit. the "never mind, we're going home" flag 🏠
  • -p — print the current status. vibe check on your settings ✨
  • -g — print the current status in shell script style. same info, but make it scriptable, periodt 🐚
  • --overwrite — let output files overwrite the ones already there. no cap, this is the "yes I'm sure" flag 💀
  • --help — print the usage summary
  • --verbose — verbose module output (it talks more, we love a yapper)
  • --quiet — quiet module output (it shuts up, respect)
  • --ui — force the GUI dialog to launch 🖥️

💜 Parameters:

  • output=string — name of the output directory, or the OGR / PostGIS data source. it's giving "where do the files go"
    • Examples:
      • ESRI Shapefile: a directory containing a shapefile
      • MapInfo File: a directory containing a mapinfo file
      • PostGIS database: a connection string, eg. 'PG:dbname=db user=grass'
  • format=string — the format for your output vector data 🎨
    • Options: AmigoCloud, BAG, CSV, Carto, DGN, DXF, ESRI_Shapefile, Elasticsearch, FITS, FlatGeobuf, GML, GPKG, GPSBabel, GPX, GeoJSON, GeoJSONSeq, GeoRSS, JML, JSONFG, KML, MBTiles, MEM, MSSQLSpatial, MVT, MapInfo_File, MapML, MiraMonVector, MySQL, NGW, ODS, OGR_GMT, OpenFileGDB, PCIDSK, PDF, PDS4, PGDUMP, PMTiles, PostgreSQL, S57, SQLite, Selafin, VDV, VICAR, WAsP, XLSX, netCDF, PostgreSQL
    • Default: ESRI_Shapefile
  • options=string[,string,...] — creation options 🛠️
    • Examples:
      • 'SHPT=POINTZ': create 3D point Shapefile data
      • 'GEOM_TYPE=geography': use geography PostGIS data
      • 'SCHEMA=grass': create new PostGIS tables in 'grass' schema
  • loadsettings=name — name of the input file to read settings from 📥
  • savesettings=name — name for the output file where you save the current settings 📤

🌈 DESCRIPTION 🌈

So basically, v.external.out tells GRASS to write vector maps in an external data format (think ESRI Shapefile, Mapinfo, and others, bestie) using the OGR library. PostGIS data can also be written by the built-in GRASS-PostGIS data provider. she contains multitudes 💅

👑 NOTES 👑

The number of available output formats (v.external.out -f) depends on your OGR installation. There's also a 'PostgreSQL' format presented when GRASS comes with PostgreSQL support (check for '--with-postgres' in g.version -b output).

To store geometry and attribute data in a PostGIS database ('PostgreSQL' format), GRASS uses the built-in GRASS-PostGIS data provider. PostGIS data can be written by the OGR library too, when the GRASS_VECTOR_OGR environmental variable is defined, or when GRASS is not compiled with PostgreSQL support. two paths, one destination ✨

Creation options refer to the output format specified by the format option. See the list of valid creation options at the OGR formats specification page, example for ESRI Shapefile or PostgreSQL/PostGIS format (section "Layer Creation Options"). Options are comma-separated pairs (key=value), and the options are case-insensitive, eg. options="SCHEMA=myschema,FID=cat". lowercase, uppercase, she doesn't care 💅

💖 PostgreSQL/PostGIS Creation Options

Note that the built-in GRASS-PostGIS data provider (format=PostgreSQL) supports different creation options compared to the PostgreSQL/PostGIS driver from the OGR library:

  • SCHEMA=<name> — name of schema where to create feature tables. If the schema doesn't exist, it's automatically created when writing PostGIS data. she makes her own room 🏠
  • FID=<column> — name of column which will be used as primary key (feature id), default: fid
  • GEOMETRY_NAME=<column> — name of column which will be used for storing geometry data in the feature table, default: geom
  • SPATIAL_INDEX=YES|NO — enable/disable spatial index on the geometry column, default: YES
  • PRIMARY_KEY=YES|NO — enable/disable primary key on the FID column, default: YES
  • SRID=<value> — spatial reference identifier, default: not defined
  • TOPOLOGY=YES|NO — enable/disable native PostGIS topology, default: NO

Options relevant only to topological output (TOPOLOGY=YES):

  • TOPOSCHEMA_NAME=<schema name> — name of PostGIS Topology schema (relevant only for TOPOLOGY=YES), default: topo_<input>
  • TOPOGEOM_NAME=<column> — name of column which will be used for storing topogeometry data in the feature table, default: topo
  • TOPO_TOLERANCE=<value> — tolerance for PostGIS Topology schema, see CreateTopology function for details, default: 0
  • TOPO_GEO_ONLY=YES|NO — store in PostGIS Topology schema only data relevant to the Topo-Geo data model, default: NO
  • SIMPLE_FEATURE=YES|NO — build simple features geometry in the GEOMETRY_NAME column from topogeometry data, default: NO
⚠️ heads up bestie: topological output requires PostGIS version 2 or later. no version 2, no topology, that's the rule 😭

🦋 EXAMPLES 🦋

🌸 ESRI Shapefile

v.external.out can be used along with v.external to process external geodata in GRASS while writing out the results directly, eg. in ESRI Shapefile format:

# register Shapefile in GRASS mapset:
v.external input=/path/to/shapefiles layer=cities
# define output directory for GRASS calculation results:
v.external.out output=$HOME/gisoutput
# do something (here: spatial query), write output directly as Shapefile
v.select ainput=cities atype=point binput=forests btype=area operator=within output=fcities

Current settings can be printed using the -p or -g flag.

v.external.out -p
output: /path/to/home/gisoutput
format: ESRI Shapefile

💜 PostGIS (simple features)

PostGIS data can be accessed directly using the GRASS-PostGIS data provider (GRASS must be compiled with PostgreSQL support).

# register PostGIS table in GRASS mapset:
v.external output=PG:dbname=gisdb layer=cities
# define output PostGIS database for GRASS calculation results stored as simple features:
v.external.out output=PG:dbname=gisdb format=PostgreSQL
# do some processing...

Note: If the environment variable GRASS_VECTOR_OGR is defined, or GRASS is compiled without PostgreSQL support, then GRASS will use the PostgreSQL driver from the OGR library for reading and writing PostGIS data.

🎀 PostGIS Topology

# define output PostGIS database for GRASS calculation results stored as topological elements:
v.external.out output=PG:dbname=gisdb format=PostgreSQL options=topology=YES
# do some processing...

Note: PostGIS topological access is supported only in the built-in GRASS-PostGIS data provider. periodt 💅

🌈 GRASS native format

To restore the original settings, ie. use the GRASS native format, type:

v.external.out -r

⭐ Restore settings

Current settings can be stored to a file by specifying the output option.

# define output PostGIS database for GRASS calculation with
# results stored as topological elements:
v.external.out output=PG:dbname=gisdb format=PostgreSQL \
  options=topology=YES savesettings=gisdb_topo.txt
# ... and do some processing in PostGIS Topology

# Back to native format:
v.external.out -r

# do some processing in native format

Restore previous settings from "gisdb_topo.txt" file by specifying the loadsettings option.

v.external.out loadsettings=gisdb_topo.txt
# ... and do some processing in PostGIS Topology

🔥 REFERENCES 🔥

  • GRASS-OGR data provider
  • OGR vector library C API documentation
  • GRASS-PostGIS data provider
  • libpq - C Library

🫶 SEE ALSO 🫶

v.external, v.in.ogr, v.out.ogr, v.out.postgis

See also the GRASS user wiki page for more examples.

💖 AUTHOR 💖

Martin Landa, Czech Technical University in Prague, Czech Republic (development supported by Fondazione Edmund Mach and Comune di Trento, Italy) — iconic behavior honestly 👑

💅 SOURCE CODE 💅

Available at: v.external.out source code (history)

Latest change: Monday Dec 08 14:05:20 2025 in commit: 5eb9d11009059ec22a089de51a2f9dc5e39e4601

Main index | Vector index | Topics index | Keywords index | Graphical index | Full index

okay that's the whole thing bestie, you ate that 🍓 this was the v.external.out(1grass) page, straight from the GRASS 8.5.0 Reference Manual, © 2003-2026 GRASS Development Team — go forth and export your vectors in whatever format your heart desires 💜 ✨ 🦋

📦 where this page comes from