The module provides handy URL class for URL parsing and changing.


URL is constructed from str:

>>> from yarl import URL
>>> url = URL('https://www.python.org/~guido?arg=1#frag')
>>> url

All URL parts: scheme, user, password, host, port, path, query and fragment are accessible by properties:

>>> url.scheme
>>> url.host
>>> url.path
>>> url.query_string
>>> url.query
<MultiDictProxy('arg': '1')>
>>> url.fragment

All URL manipulations produces a new URL object:

>>> url.parent / 'downloads/source'

Strings passed to constructor and modification methods are automatically encoded giving canonical representation as result:

>>> url = URL('https://www.python.org/путь')
>>> url

Regular properties are percent-decoded, use raw_ versions for getting encoded strings:

>>> url.path

>>> url.raw_path

Human readable representation of URL is available as human_repr():

>>> url.human_repr()

For full documentation please read Public API section.


$ pip install yarl

The library is Python 3 only!


YARL requires multidict library.

It installs it automatically.

API documentation

Open Public API for reading full list of available methods.

Comparison with other URL libraries

  • furl (https://pypi.python.org/pypi/furl)

    The library has a rich functionality but furl object is mutable.

    I afraid to pass this object into foreign code: who knows if the code will modify my URL in a terrible way while I just want to send URL with handy helpers for accessing URL properties.

    furl has other non obvious tricky things but the main objection is mutability.

  • URLObject (https://pypi.python.org/pypi/URLObject)

    URLObject is immutable, that’s pretty good.

    Every URL change generates a new URL object.

    But the library doesn’t any decode/encode transformations leaving end user to cope with these gory details.

Source code

The project is hosted on GitHub

Please file an issue on the bug tracker if you have found a bug or have some suggestion in order to improve the library.

The library uses Azure Pipelines for Continuous Integration.

Discussion list

aio-libs google group: https://groups.google.com/forum/#!forum/aio-libs

Feel free to post your questions and ideas here.

Authors and License

The yarl package is written by Andrew Svetlov.

It’s Apache 2 licensed and freely available.


Indices and tables