Installation

MapToPoster requires Python 3.11 or higher. You can install it using uv (recommended for automatic dependency management) or pip with a virtual environment.

Prerequisites

Before installing MapToPoster, ensure you have:

Python 3.11+ installed on your system
Git (to clone the repository)
Internet connection (for downloading map data from OpenStreetMap)

MapToPoster requires Python 3.11 or higher. Check your version with python --version or python3 --version.

Installation Methods

uv (Recommended)
pip + venv

Install with uv

uv is a fast Python package installer and resolver that automatically manages virtual environments for you.

Install uv

If you don’t have uv installed, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

pip install uv

Clone the repository

git clone https://github.com/yourusername/maptoposter.git
cd maptoposter

Run with uv

The first run automatically creates a virtual environment and installs all dependencies:

uv run ./create_map_poster.py --city "Paris" --country "France"

uv automatically creates and manages the virtual environment. No need to manually activate it!

(Optional) Sync dependencies explicitly

To install dependencies using locked versions before running:

uv sync --locked
uv run ./create_map_poster.py --city "Paris" --country "France"

Why uv?

Automatic environment management: No need to manually create/activate virtual environments
Fast dependency resolution: 10-100x faster than pip
Deterministic installs: Lock file ensures reproducible builds
Simple workflow: Just prefix commands with uv run

Install with pip

Traditional installation using Python’s built-in venv and pip.

Clone the repository

git clone https://github.com/yourusername/maptoposter.git
cd maptoposter

Create virtual environment

python3 -m venv .venv
source .venv/bin/activate

python -m venv .venv
.venv\Scripts\Activate.ps1

python -m venv .venv
.venv\Scripts\activate.bat

Install dependencies

pip install -r requirements.txt

This installs all required packages:

osmnx (2.0.7): OpenStreetMap data fetching
matplotlib (3.10.8): Rendering and visualization
geopandas (1.1.2): Geographic data processing
geopy (2.4.1): Geocoding
requests (2.32.5): Google Fonts downloads
And other dependencies

Verify installation

python create_map_poster.py --list-themes

You should see a list of 17 available themes.

Remember to activate your virtual environment every time you work with MapToPoster:

source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

Verify Installation

Test that everything is working correctly:

uv run ./create_map_poster.py --list-themes

python create_map_poster.py --list-themes

You should see output listing all available themes:

Available Themes:
------------------------------------------------------------
  terracotta
    Terracotta
    Mediterranean warmth - burnt orange and clay tones on cream

  noir
    Noir
    Pure black background, white roads

  midnight_blue
    Midnight Blue
    Navy background with gold roads

  ...

Directory Structure

After installation, your project structure should look like this:

maptoposter/
├── create_map_poster.py    # Main CLI script
├── font_management.py      # Font loading and Google Fonts
├── requirements.txt        # pip dependencies
├── pyproject.toml         # Project metadata
├── uv.lock                # uv lock file (if using uv)
├── themes/                # 17 theme JSON files
│   ├── terracotta.json
│   ├── noir.json
│   ├── midnight_blue.json
│   └── ...
├── fonts/                 # Default Roboto fonts
│   ├── Roboto-Bold.ttf
│   ├── Roboto-Light.ttf
│   └── cache/             # Downloaded Google Fonts (auto-created)
├── posters/               # Generated posters (auto-created)
└── cache/                 # Cached map data (auto-created)

Dependency Overview

MapToPoster uses the following key dependencies:

osmnx 2.0.7

Fetches street networks and geographic features from OpenStreetMap

matplotlib 3.10.8

Renders high-quality poster graphics with precise control over styling

geopandas 1.1.2

Handles geographic data structures and coordinate projections

geopy 2.4.1

Geocodes city names to latitude/longitude coordinates

Troubleshooting

Python version error

MapToPoster requires Python 3.11+. Check your version:

python --version

If you have multiple Python versions, try:

python3.11 -m venv .venv

GEOS library not found

On some systems, you may need to install GEOS separately:

sudo apt-get install libgeos-dev

brew install geos

sudo dnf install geos-devel

SSL certificate errors

If you encounter SSL errors when downloading fonts or map data:

pip install --upgrade certifi

Memory errors with large cities

For very large metropolitan areas or large distance values (>20km), you may need to:

Reduce the --distance parameter
Close other applications to free up memory
Use a smaller output size (--width and --height)

Next Steps

Now that MapToPoster is installed, you’re ready to create your first poster!

Quick Start Guide

Follow the quickstart tutorial to generate your first map poster

Get Started

Usage

Guides

Examples

Prerequisites

Installation Methods

Install with uv

Why uv?

Install with pip

Verify Installation

Directory Structure

Dependency Overview

osmnx 2.0.7

matplotlib 3.10.8

geopandas 1.1.2

geopy 2.4.1

Troubleshooting

Next Steps

Quick Start Guide

​Prerequisites

​Installation Methods

​Install with uv

​Why uv?

​Install with pip

​Verify Installation

​Directory Structure

​Dependency Overview

osmnx 2.0.7

matplotlib 3.10.8

geopandas 1.1.2

geopy 2.4.1

​Troubleshooting

​Next Steps

Quick Start Guide

Prerequisites

Installation Methods

Install with uv

Why uv?

Install with pip

Verify Installation

Directory Structure

Dependency Overview

Troubleshooting

Next Steps