PurePath.as_posix

Three conversions. as_posix() is str(path) with '/' separators — the portable way to print or store a path. as_uri() percent-encodes an absolute path into file:///…; from_uri() parses such a URI back into a Path.

pathlib methodPython 3.4+ (from_uri 3.13+)Live demo
Common call
PurePosixPath('/tmp/a b.txt').as_uri()
Returns
'file:///tmp/a%20b.txt'
Replaces
str(p).replace('\\', '/') and hand-built 'file://' + path
Watch out
as_uri() on a relative path is a ValueError
PurePath.as_posix() / .as_uri() / Path.from_uri(uri)
→ str | Path

Demo

Live evaluation
Non-ASCII and reserved characters are percent-encoded as UTF-8 bytes.
Try:
Inputs
pathstran absolute POSIX path
Code
from pathlib import PurePosixPath
p = PurePosixPath('/etc/hosts')
(p.as_posix(), p.as_uri())
Result
('/etc/hosts', 'file:///etc/hosts')

'/' and the unreserved characters (letters, digits, _ . - ~) stay as they are; everything else becomes %XX of its UTF-8 bytes, so é is %C3%A9 and # is %23. A file URI must be absolute, so a relative path raises ValueError — call resolve() or absolute() on a Path first.

Parameters

NameTypeRequiredDescription
uristryesfrom_uri only: a 'file:' URI. It must describe an absolute path for the running OS.

Return value

str | Path — as_posix and as_uri return str; from_uri returns a Path.

Common patterns

Open a local file in the browser
webbrowser wants a URL; as_uri needs an absolute path.
import webbrowser
from pathlib import Path
webbrowser.open(Path('report.html').resolve().as_uri())
Store paths portably
as_posix() in files and databases; Path() parses it back on any OS.
from pathlib import Path
record = {'file': p.relative_to(root).as_posix()}
restored = root / record['file']
Accept file: URIs from other programs (3.13+)
Path.from_uri decodes %XX and checks the result is absolute.
from pathlib import Path
p = Path.from_uri(dropped_uri)

Examples

1. Forward slashes from a Windows path
from pathlib import PureWindowsPath PureWindowsPath('C:\\Users\\ada').as_posix()
Returns
'C:/Users/ada'
2. as_posix of a POSIX path is str()
from pathlib import PurePosixPath p = PurePosixPath('/srv/app') p.as_posix() == str(p)
Returns
True
3. A file URI
from pathlib import PurePosixPath PurePosixPath('/etc/a b.txt').as_uri()
Returns
'file:///etc/a%20b.txt'
4. Windows drive in a URI
from pathlib import PureWindowsPath PureWindowsPath('C:/Users/me/a b.txt').as_uri()
Returns
'file:///C:/Users/me/a%20b.txt'
5. UTF-8 percent-encoding
from pathlib import PurePosixPath PurePosixPath('/tmp/é').as_uri()
Returns
'file:///tmp/%C3%A9'
6. Relative paths have no URI
from pathlib import PurePosixPath PurePosixPath('docs/cv.pdf').as_uri()
Returns
ValueError: relative path can't be expressed as a file URI
7. from_uri needs a file: URI
from pathlib import Path Path.from_uri('https://example.com/a.txt')
Returns
ValueError: URI does not start with 'file:': 'https://example.com/a.txt'

Pitfalls

1. Building a file URL by string concatenation
Spaces and non-ASCII characters must be percent-encoded; as_uri does it for you.
'file://' + path
'file://' + '/tmp/my notes.txt'
'file:///tmp/my notes.txt'
as_uri()
from pathlib import PurePosixPath
PurePosixPath('/tmp/my notes.txt').as_uri()
'file:///tmp/my%20notes.txt'
2. Calling as_uri() on a relative Path
Make it absolute first.
relative
from pathlib import Path
Path('index.html').as_uri()
ValueError: relative path can't be expressed as a file URI
resolve() first
from pathlib import Path
Path('index.html').resolve().as_uri().startswith('file:///')
True

When to use

Use it
  • Printing, logging or storing paths in a platform-neutral form (as_posix)
  • Handing a local file to a browser or any API that wants a URL (as_uri)
  • Receiving file: URIs from drag and drop or other programs (from_uri, 3.13+)
Reach for something else
  • http(s) URLs → urllib.parse
  • Passing a path to open() or os.* → pass the Path itself

Notes

CPython impl
as_uri percent-encodes os.fsencode(path) with urllib.parse.quote_from_bytes (safe="/"); from_uri strips the empty or "localhost" authority, decodes %XX and raises ValueError unless the result is absolute
from_uri
OS-dependent: 'file:///etc/hosts' is an absolute path on Linux and macOS but not on Windows (no drive), where from_uri raises 'URI is not absolute'
Deprecated in 3.14
Calling as_uri() on a pure path is deprecated from 3.14 (it uses os.fsencode, which depends on the machine); Path.as_uri stays

FAQ

Path(p).resolve().as_uri() → 'file:///…' with spaces and non-ASCII characters percent-encoded. The path must be absolute.