# What changed in yarl

> 12 changes in yarl 1 from its official release notes, upgrade guides and advisories: 7 breaking, 1 new APIs and options. Each one cited. Sources checked 2026-10-21. HTML: https://unstale.sh/pypi/yarl/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## yarl 1

### Breaking changes

- The pure Python quoter now rejects non-ASCII safe and protected characters when created, matching the C extension. (1.25.1) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.25.1)
- C and pure Python quoting implementations now reject percent signs in safe or protected when requoting, and spaces in safe or protected for query strings, keeping their behavior consistent. (1.25.1) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.25.1)
- The URL constructor and builder APIs now reject Unicode default-ignorable and format code points in hosts when IDNA normalization could change the host. (1.24.5) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.24.5)
- URL.build and URL.with_host now reject hosts that expand to /, ? or # under IDNA normalization. (1.24.5) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.24.5)
- When validate_host=True, IPv6 zone IDs now reject ASCII control characters and the empty string. (1.24.5) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.24.5)
- URL-building APIs now percent-encode a scheme-shaped leading colon in a relative path so its serialized form cannot be parsed as an absolute or executable-scheme URL. (1.24.5) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.24.5)
- Host validation now rejects Unicode percent characters that NFKC-normalize to a literal percent sign. (1.24.5) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.24.5)

### New APIs and options

- Added a faster replacement for urllib.parse.parse_qsl with keep_blank_values=True that also accepts max_fields and encoding. (1.25.1) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.25.1)

### Performance

- Improved C and pure Python unquoter performance, especially for long strings and strings with many percent-encoded characters. (1.25.1) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.25.1)

### Fixes and other changes

- Fixed query parsing to stop returning empty fields and preserve invalid percent-encoded UTF-8; behavior again matches urllib.parse.parse_qsl. Related query methods also no longer double encode those escapes. (1.25.1) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.25.1)
- The Cython quoting backend now drops lone surrogates consistently with the pure-Python backend and preserves percent escapes when a surrogate falls within one. (1.24.5) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.24.5)
- IPv6 Zone ID URLs now expose the decoded % separator in host instead of %25. (1.24.5) — [release notes](https://github.com/aio-libs/yarl/releases/tag/v1.24.5)