Guide · Open source
How to use maptoposter: install, run and customise city posters
Updated · written with AI from the project's own documentation and checked against our catalogue data
maptoposter is an open-source Python script that draws a stylized map of a city you name and exports it as an image sized for a poster. This guide shows you how to install it, generate your first poster, and use the themes, distance, size and multilingual options. It is written for people comfortable with a terminal who want a decorative city map without design software.
maptoposteroriginalankur/maptoposter · ★ 14.3k · MIT Install options & downloads Quick start
- 1Install uv or prepare pip. Make sure uv is installed, or create a Python virtual environment and install requirements.txt with pip.
- 2Run a first poster. Run the script with --city and --country, for example Paris and France, using uv run or python.
- 3List the themes. Use --list-themes to see the 17 available themes.
- 4Pick a theme and distance. Choose a theme with -t and a map radius in meters with -d, using the distance guide as a starting point.
- 5Set the print size. Set -W and -H in inches, using the 300 DPI table for screens or A4 prints.
- 6Add multilingual names if needed. Use -dc, -dC and --font-family to display names in a non-Latin script.
What you need before you install maptoposter
maptoposter requires Python. The README does not state a minimum Python version, so check the project's files if you need one. You also need either uv or pip with a virtual environment.
The project is run from the command line, so you should be comfortable opening a terminal and running commands in the project folder.
- Python (the README does not give a version number)
- uv, or pip with a virtual environment
- A terminal to run the script
Install maptoposter with uv
uv is the recommended route. Prepending uv run to the script creates and manages a virtual environment for you, and the first run installs the dependencies.
If you prefer to install dependencies explicitly first, sync the locked versions and then run the script.
# First run will automatically install dependencies
uv run ./create_map_poster.py --city "Paris" --country "France"
# Or sync dependencies explicitly first (using locked versions)
uv sync --locked
uv run ./create_map_poster.py --city "Paris" --country "France"Install maptoposter with pip and a virtual environment
If you do not use uv, create a virtual environment, activate it and install the requirements file. The activate command differs on Windows, as shown in the code block.
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txtGenerate your first poster
The two required options are --city (or -c) and --country (or -C). The city name is used for geocoding, so the country helps the script find the right place. Without uv, run the script with python instead of uv run.
Posters are saved to the posters/ folder, as the example filenames in the README show.
- --city / -c: city name, used for geocoding
- --country / -C: country name, used for geocoding
- -t / --theme: theme name, default terracotta
- -d / --distance: map radius in meters, default 18000
- -W / --width and -H / --height: size in inches, default 12 by 16, maximum 20
- -lat / -long: override the center point, used together
- --country-label: override the country text on the poster
python create_map_poster.py --city <city> --country <country> [options]Choose a theme, radius and print size
Themes control colors and styling. The README lists 17 themes in the themes/ directory, and you can see them all with --list-themes. To render every theme for one city, use --all-themes.
The distance option sets how much of the city appears. The README suggests 4000 to 6000 meters for small, dense cities, 8000 to 12000 meters for medium cities or a focused downtown, and 15000 to 20000 meters for large metros.
For sizing, the README gives values for 300 DPI output. For example, a 1080 by 1080 pixel Instagram post uses 3.6 by 3.6 inches, and an A4 print at 2480 by 3508 pixels uses 8.3 by 11.7 inches.
- noir: pure black background, white roads
- midnight_blue: navy background with gold roads
- blueprint: architectural blueprint aesthetic
- warm_beige: vintage sepia tones
- sunset: warm oranges and pinks
- Distance 4000-6000 m: small or dense cities such as Venice
- Distance 15000-20000 m: large metros such as Tokyo
python create_map_poster.py -c "New York" -C "USA" -t noir -d 12000
python create_map_poster.py -c "Tokyo" -C "Japan" --all-themes
python create_map_poster.py --list-themesShow city names in non-Latin scripts
The multilingual options let you display the city and country in your own language. Use --display-city (-dc) and --display-country (-dC) for the text, and --font-family for a Google Fonts family name. The README notes that fonts are downloaded automatically and cached in fonts/cache/.
The README includes examples for Japanese, Korean, Arabic, Thai, Chinese and Khmer.
python create_map_poster.py -c "Tokyo" -C "Japan" -dc "東京" -dC "日本" --font-family "Noto Sans JP" -t japanese_inkOverride the map center
If the geocoded center is not the spot you want, pass exact coordinates with -lat and -long. The README says to use them together.
python create_map_poster.py --city "New York" --country "USA" -lat 40.776676 -long -73.971321 -t noirWhat people use it for
- A decorative map of a hometown as a gift or wall print
- A map poster of a city you have visited, using a theme that matches its character
- Social media images at Instagram or wallpaper sizes
- Experimenting with color themes for map-based design
- Posters with city and country names in Japanese, Korean, Arabic or other scripts
Frequently asked questions
Is maptoposter free to use?
The project is licensed under MIT, as stated in the project information. You can use the script under the terms of that licence; check the LICENSE file in the repository for the full text.
What do I need to run maptoposter?
You need Python and either uv or pip with a virtual environment. The README does not state a minimum Python version.
Do I need design software to make a poster?
No. maptoposter is aimed at people who want a decorative city map without using design software. You choose a theme, radius and size on the command line and the script exports the image.
Can I use maptoposter for precise maps?
Not really. The README describes stylized designs rather than survey-grade maps, so it is not suited to users who need precise cartographic accuracy.
Does maptoposter work with non-English city names?
Yes. The multilingual options let you set display names in scripts such as Japanese, Korean, Arabic and Thai, and choose a Google Fonts family to render them.
How does maptoposter compare to OSMnx, Mapnik or QGIS?
The project information lists OSMnx, Mapnik and QGIS as comparable projects. maptoposter's focus is a stylized poster output from a single command, while those tools are typically used for mapping and analysis.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
maptoposter suits people who are comfortable with Python and the command line and want a decorative city poster for a home, gift or design experiment. If you want a point-and-click editor or need survey-grade map accuracy, pick a different tool.
Install options & downloads