# wttr.in: Console Weather by curl, with PNG, JSON, and Prometheus Output

> wttr.in is a public weather service that responds to plain HTTP requests and returns ANSI output for terminals, PNG for graphical use, and JSON or Prometheus metrics for scripts. The README states it handles tens of millions of queries daily and can be self-hosted with Docker.

**chubin/wttr.in** — :partly_sunny: The right way to check the weather

- Repository: https://github.com/chubin/wttr.in
- Website: https://wttr.in
- Stars: 30,576 · Forks: 1,273
- Language: Go
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/chubin-wttr-in

## What wttr.in Does and Who Uses It

wttr.in is a console-oriented weather forecast service accessible by HTTP. The README describes it as originally a small project, a wrapper for wego (github.com/schachmat/wego), intended to demonstrate the power of console-oriented services. It has grown into a weather service handling tens of millions of queries daily.

The primary audience is developers and system administrators who want weather data inside a terminal, a shell script, or a status bar. The core interaction is a curl command:

```bash
curl wttr.in
```

That returns an ANSI-formatted weather report for the location inferred from your IP address. No account, no API key, no installation. The README gives this as the first example, and it captures the intent of the project: weather as a command, not a web page.

For PowerShell users on Windows:

```PowerShell
Invoke-RestMethod https://wttr.in
```

The service supports five output formats: ANSI for terminals, plain text for scripts, HTML for browsers, PNG for graphical viewers, and JSON and Prometheus metrics for programmatic use. The format is selected based on the User-Agent string when you use a browser, but can be forced explicitly through URL parameters.

## The Query Model: Locations, Units, and Options

Locations can be specified as city names, IATA airport codes, geographic landmarks, coordinates, IP addresses, or domain names. The README gives examples for each category:

```bash
curl wttr.in/London
curl wttr.in/muc
curl wttr.in/Eiffel+Tower
curl wttr.in/@github.com
```

The three-letter airport codes look up weather at the named airport; IATA code `muc` returns Munich International Airport. Landmark names and domains return a geolocation result line below the forecast showing the matched coordinates.

Weather units default to USCS for US-based requests and metric for all others. You can override this:

```bash
curl wttr.in/Amsterdam?u
curl wttr.in/Amsterdam?m
curl wttr.in/Amsterdam?M
```

The `?u` flag forces USCS, `?m` forces metric (SI), and `?M` uses metric but reports wind speed in meters per second rather than kilometers per hour.

Multiple options can be combined. The README gives this example for metric units with Dutch language output:

```bash
curl 'wttr.in/Amsterdam?m2&lang=nl'
```

Single-letter options concatenate without delimiters; multi-letter options use `&` as a separator, matching GNU CLI convention.

To strip ANSI color codes and force plain text:

```bash
curl wttr.in/?T
```

To restrict output to glyphs available in standard console fonts like Consolas and Lucida Console:

```bash
curl wttr.in/?d
```

## One-Line Output for Status Bars and Scripts

The one-line output format is designed for integration with terminal multiplexers like tmux and IRC clients like weechat. It returns a compact weather summary on a single line.

Four preconfigured formats are available:

```bash
curl wttr.in/Nuremberg?format=3
```

The README documents what each format returns:
- Format 1: current condition icon and temperature
- Format 2: condition icon, temperature icon, and wind speed
- Format 3: location name, condition icon, and temperature
- Format 4: location name, condition icon, temperature, and wind speed

To query multiple locations in one call:

```bash
curl -s 'wttr.in/{Nuremberg,Hamburg,Berlin}?format=3'
```

This returns one line per location, useful for scripts that need weather across multiple cities.

For custom output beyond the four presets, the `%`-notation lets you compose the fields you want. The README lists format codes for condition (`c`), humidity (`h`), actual temperature (`t`), feels-like temperature (`f`), wind (`w`), location (`l`), moon phase (`m`), and others.

This one-line output mode is the most common integration point for shell scripts and terminal dashboards. It is also where wttr.in is most directly useful without knowing any of the more complex format options.

## PNG Output and Image Embedding

wttr.in generates PNG weather images. Force PNG format by appending `.png` to the query:

```bash
wget wttr.in/Paris.png
```

For PNG output, URL parameters use `_` instead of `?` and `&`:

```bash
wget wttr.in/Paris_0tqp_lang=fr.png
```

The PNG format supports transparency, useful when embedding weather data into other images. The README gives a concrete example of compositing a weather PNG onto a photograph:

```bash
convert source.jpg <( curl wttr.in/Oymyakon_tqp0.png ) -geometry +50+50 -composite target.jpg
```

In this example, `tqp0` is the option string (transparency enabled, quiet mode, no wind). The wttr-switcher project (github.com/midzer/wttr-switcher) is mentioned in the README as a way to embed a wttr.in widget in an HTML page.

The PNG output depends on server-side rendering with fonts. The Dockerfile installs several font packages: DejaVu, Noto core, Noto CJK, WQY ZenHei, Symbola, Motoya L Cedar, and Lexi Gulim. This font coverage is why self-hosting the PNG-capable version requires a more involved build than a minimal container image.

## Self-Hosting wttr.in with Docker

The repository includes a Dockerfile for self-hosting. The build uses two stages: a builder stage based on golang:1.26-bookworm that compiles the Go binary with build.sh, and a runtime stage based on Alpine 3.23 that runs the compiled binary.

The runtime environment uses four environment variables, set in the Dockerfile:

```dockerfile
ENV WTTR_MYDIR="/app"
ENV WTTR_GEOLITE="/app/GeoLite2-City.mmdb"
ENV WTTR_LISTEN_HOST="0.0.0.0"
ENV WTTR_LISTEN_PORT="8002"
```

The server listens on port 8002 by default. The GeoLite2 database file is required for IP-based geolocation (the feature that infers your location when you run `curl wttr.in` without specifying a location). You need to supply this file separately, since it is not included in the repository.

To build from source, the Makefile delegates to build.sh:

```bash
bash build.sh build
```

The Go module file specifies Go 1.25.0 as the minimum version.

The runtime binary is at /app/bin/srv and runs as a non-root user (uid 1000). The health check endpoint is at the root path, verified with a Python urllib call in the Dockerfile.

Self-hosting is practical for internal deployments where outbound HTTP to wttr.in is not permitted, but the GeoLite2 requirement and the font-heavy builder stage make it heavier than typical Go service deployments.

## When wttr.in Is Not the Right Tool

wttr.in is a front end over a weather data source. The README does not document which weather data provider it uses. If the underlying data source is inaccurate or unavailable for your location, wttr.in will reflect that inaccuracy; there is no documented fallback or alternative source.

The service is a public endpoint shared across all users. The README does not describe rate limits, but tens of millions of queries daily suggests the service is designed for general use rather than high-volume automated polling. Teams running thousands of automated queries per hour should self-host rather than using the public endpoint.

For applications that need precise hyperlocal forecast data, detailed hourly breakdowns, or weather data tied to specific API SLAs, wttr.in is not the right choice. It is designed for human-readable weather summaries at a city or landmark level, not for weather data pipelines.

The JSON output format is documented in the README and is stable enough for scripting, but the project has no GitHub releases and no explicit versioning commitment for the JSON schema. Scripts that depend on the JSON structure could break if the server-side format changes.

## Conclusion

wttr.in is the right tool when you need weather data in a terminal, a shell script, or a status bar integration, and you want to get it with a single curl command rather than parsing a weather API. The public instance at wttr.in handles the hosting. For teams that cannot send outbound requests to a public service, the Docker image supports self-hosting, but they need to supply a MaxMind GeoLite2 database file (referenced as WTTR_GEOLITE in the Dockerfile) and accept the build complexity of a Go + font-heavy build process. The Prometheus metrics output and the one-line format make it practical for infrastructure monitoring dashboards. It is the wrong tool when you need hyperlocal forecast granularity beyond what the underlying weather source provides, or when you require an SLA on data freshness.

## FAQ

### What is wttr.in?

wttr.in is a console-oriented weather forecast service that responds to plain HTTP requests. You query it with curl or wget (for example, `curl wttr.in/London`) and receive formatted weather output in ANSI, plain text, HTML, PNG, or JSON depending on the client and URL parameters. The README states it handles tens of millions of queries daily.

### How do I use wttr.in?

Run `curl wttr.in` for weather at your current IP location, or `curl wttr.in/London` for a specific city. For a compact one-line output suitable for status bars, use `curl wttr.in/London?format=3`. The README documents URL parameters for units (`?m` for metric, `?u` for USCS), language (`&lang=fr`), and output format.

### Is wttr.in accurate?

The README does not document the underlying weather data source, so accuracy depends on that source's coverage for your location. The service infers location from IP when no city is given, which may not match your physical location precisely. Airport code queries (for example, `curl wttr.in/muc`) anchor the forecast to a specific geographic point.

## Sources

- [chubin/wttr.in on GitHub](https://github.com/chubin/wttr.in)
- [Issues](https://github.com/chubin/wttr.in/issues)
- [License: Apache-2.0](https://github.com/chubin/wttr.in/blob/master/LICENSE)
- [Project website](https://wttr.in)
- [README](https://github.com/chubin/wttr.in/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chubin-wttr-in