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 systemGit (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: macOS/Linux
Windows
With pip
curl -LsSf https://astral.sh/uv/install.sh | sh
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 environmentsFast dependency resolution : 10-100x faster than pipDeterministic installs : Lock file ensures reproducible buildsSimple 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
macOS/Linux
Windows (PowerShell)
Windows (Command Prompt)
python3 -m venv .venv source .venv/bin/activate
Install dependencies
pip install -r requirements.txt
This installs all required packages:
osmnx (2.0.7): OpenStreetMap data fetchingmatplotlib (3.10.8): Rendering and visualizationgeopandas (1.1.2): Geographic data processinggeopy (2.4.1): Geocodingrequests (2.32.5): Google Fonts downloadsAnd 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
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
MapToPoster requires Python 3.11+. Check your version: If you have multiple Python versions, try:
On some systems, you may need to install GEOS separately: sudo apt-get install libgeos-dev
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
