← Back to Home

Windows paths: 8 silent divergences from strings

windowspythonpathlib

TL;DR: a Windows path is not a string-to-file mapping, it is a pipeline. You write a string, Win32 normalizes it, the prefix decides which namespace handles it, and only then does NTFS resolve a name. At almost every step the string can be rewritten or swapped for another one, and most of those steps raise nothing, log nothing, and still exit 0.

Every number below comes from measurements I ran on 2026-11-14 on this machine: Windows 11 build 26300, CPython 3.13.12, an NTFS volume. The subject was a throwaway directory I created, not anyone's repository. Documentation quotes are from Microsoft Learn (Naming Files, Paths, and Namespaces; File Streams; Hard Links and Junctions) and the CPython 3.13 docs and source.

The short version: never compare paths with string equality, never walk a tree without asking whether an entry is a reparse point, and never write a file without looking at the length of its absolute form first.

PythonLinux
Technologies referenced · icons from Simple Icons (CC0)
// FLOW_01Article roadmap5 NODES01STEP_01Trailing spaces and dots: the name you wrote is not the name on disk02STEP_02The 18 bytes in data.txt:hidden that no listing shows03STEP_03C:rel.txt is not C:\rel.txt, it points at a working directory you cannot see04STEP_04The \\?\ prefix turns off parsing, and turns off your safety netwith it05STEP_05259 and 260: exists() lies to you on this lineEND_OF_FLOW
Article outline · auto-generated from section headings

Trailing spaces and dots: the name you wrote is not the name on disk

The first thing I measured was two files in an empty directory:

open('note.txt ', 'w')      # one trailing space
open('report.txt.', 'w')    # one trailing dot

Both calls succeeded. Then os.listdir returned ['note.txt', 'report.txt']. The space and the dot were gone. The byte count was normal, the content read back fine, and open('note.txt ') still opened it, because the same stripping happens again on open. Nothing in that loop tells you a rewrite occurred.

Microsoft states the rule in its naming conventions: "Do not end a file or directory name with a space or a period. Although the underlying file system may support such names, the Windows shell and user interface does not." Read the structure of that sentence: the file system supports it, the shell and UI do not. The stripping happens in a Win32 layer, not in NTFS.

There is a second place the same behavior is documented openly: os.path.abspath. The docs say the path is normalized by the operating system, that trailing dots and spaces are stripped, and give the example where c:/temp/spam. . . becomes c:\temp\spam. So the rewrite is visible in the normalization function and invisible in open.

Where it bites: importing names from a spreadsheet or a file listing, where a.txt and a.txt dedupe as two entries but resolve to one file; generating a filename from a title, where the extension check changes after the dot is eaten; and cross-platform sync, where the same name is legal on Linux, so each side keeps its own index and they never agree.

The 18 bytes in data.txt:hidden that no listing shows

On the same machine I wrote this:

open(str(path) + ':hidden', 'w').write('secret-stream-here')

The main file stayed at 9 bytes with the content main-body, while os.path.getsize(path + ':hidden') returned 18. os.listdir showed one entry, data.txt. Plain dir showed nothing extra. Only dir /r printed the second line:

2026/11/14  06:13                 9 data.txt
                                 18 data.txt:hidden:$DATA

This is an NTFS alternate data stream. The official File Streams page gives the naming form, filename:stream name:stream type, notes that the default stream is unnamed and is fully spelled filename::$DATA, and adds a detail that is easy to skip: "There are no file times associated with a stream. The file times for a file are updated when any stream in a file is updated." A stream has no timestamp of its own, but touching one updates the main file's times, so any incremental backup keyed on mtime will misjudge whether the file changed.

I also checked the step people hit first: after shutil.copy2, opening copy.txt:hidden on the copy raises FileNotFoundError. Python's copy reads the default data stream and writes a new file; streams are not part of that. This is not a Python defect. Windows' own copy behaves the same way.

Three consequences follow. Backup tools preserve the main stream and silently drop the rest. Forensics or AV scanning that ignores :$DATA is looking at half a file. And a size calculation like sum(getsize(f) for f in listdir()) reports 9 instead of 27.

C:rel.txt is not C:\rel.txt, it points at a working directory you cannot see

This is the one I would expect to find in production code most often. Two measurements:

os.chdir('C:\\Windows')
os.path.abspath('C:rel.txt')     ->  'C:\\Windows\\rel.txt'
os.chdir('D:\\')
os.path.abspath('C:rel.txt')     ->  'C:\\Windows\\rel.txt'   # unchanged

The second line is the point. Windows keeps a separate current directory per drive, hidden inside the process, and os.getcwd() only ever reports the one for the current drive. So C:rel.txt does not mean C:\rel.txt; it means "rel.txt under whatever C's hidden working directory happens to be". Change the process to D: and it still resolves against C:.

os.path.isabs('C:rel.txt') returns False, os.path.splitdrive gives ('C:', 'rel.txt'), and PureWindowsPath('C:rel.txt').is_absolute() is False too. The os.path.abspath docs state the mechanism: a drive-relative path is resolved against the current directory of the specified drive, and the drive letter is capitalized.

Path joining cooperates with the same semantics: os.path.join('C:', 'x.txt') yields C:x.txt, while os.path.join('C:\\', 'x.txt') yields C:\x.txt. One missing backslash turns an absolute path into a relative one that depends on hidden state, with no error.

One hard error is worth memorizing: os.path.relpath('C:/x.txt', 'D:/openclaw-blog') raises ValueError: path is on mount 'C:', start on mount 'D:'. That is not a bug; two volumes have no relative path between them.

The \\?\ prefix turns off parsing, and turns off your safety net with it

The purpose is documented in the namespace section: the prefix tells the Windows APIs "to disable all string parsing and to send the string that follows it straight to the file system", which is also how you exceed MAX_PATH.

But "no parsing" cuts both ways. Four spellings, measured:

SpellingResult
\\?\D:\...\v4\a.txtcontent read back normally
\\?\D:\...\v4\..\v4\a.txtOSError: [Errno 22] Invalid argument
\\?\D:\...\v4/a.txt (mixed slash)OSError: [Errno 22] Invalid argument
\\?\a.txt (relative)FileNotFoundError: [Errno 2]

So the prefix is not a path cleaner, it is an inspection-free lane. Put .. in it and you are handing the file system a literal component named ... Put a forward slash in it and it is rejected. Give it a relative path and it is rejected. To use it you must abspath first, convert separators yourself, and pass a fully qualified name.

The docs contain one sentence that is easy to misread: the prefix "also allows the use of '..' and '.' in the path names". The intent is that with automatic expansion disabled you may operate on names that contain those literals. When .. is used as a directory component, this machine returns EINVAL. Documentation sentences like this one need one measurement before they go into a code path.

259 and 260: exists() lies to you on this line

I used a short base, D:\pl1114, then two directory levels of 100 characters each so the parent path was exactly 211 characters, and bisected on the filename length:

Full path lengthResult
259written successfully
260FileNotFoundError: [Errno 2] No such file or directory

At the same moment, against that 260-character path: os.path.exists() returned False, os.path.isfile() returned False, os.stat() raised FileNotFoundError: [WinError 3], os.listdir() raised WinError 3, and Path.mkdir() raised WinError 3.

This is the single most important line in the article: an over-long path does not report "too long", it reports "not found". Any if not exists(p): create(p) on this boundary takes the create branch and then dies inside it.

The documented position: before Windows 10 version 1607 the maximum was MAX_PATH, 260 characters; later versions require "changing a registry key or using the Group Policy tool" to remove it. On this machine LongPathsEnabled under HKLM\SYSTEM\CurrentControlSet\Control\FileSystem is 0, the default, so the wall is live.

Two more numbers. A single name caps at 255: a 255-character filename at a 258-character path was created, and a 256-character name at 259 raised OSError: [Errno 22] Invalid argument. Note the total was still under 260 there, so that failure is about the component, not the path. And with the \\?\ prefix a 260-character path writes fine, provided the parent exists: the prefix waives the length check, it does not create directories for you.

The practical rule is one line: treat len(os.path.abspath(p)) >= 260 as over-long, and do not ask exists.

Junctions: islink says no, os.walk goes in anyway

Create a directory junction with cmd /c mklink /J (no admin needed; it returned 0 here), then ask Python what it is:

os.path.islink(junc)         ->  False
os.path.isjunction(junc)     ->  True
os.path.isdir(junc)          ->  True
os.path.samefile(junc, real) ->  True
Path(junc).resolve()         ->  ...\real

islink being False is not a bug: a symbolic link and a junction are different reparse tags. Microsoft's Hard Links and Junctions page says a junction is implemented through reparse points, and Python only gained os.path.isjunction in 3.12 (the docs mark it "Added in version 3.12").

The damage shows up in traversal. With real\x.txt and a junc pointing at real:

os.walk(parent, followlinks=False)  ->  ['junc\\x.txt', 'real\\x.txt']
Path(parent).rglob('*.txt')         ->  ['junc\\x.txt', 'real\\x.txt']

One file counted twice. The reason is in the source: CPython 3.13.12, Lib/os.py line 434 reads if followlinks or not islink(new_path):. The gate only filters entries where islink is true. The parameter name suggests "do not follow links"; the actual meaning is "do not follow symbolic links".

For backups, disk-usage reports and static-asset scanners this is a hard defect: totals inflate, copies duplicate, and a junction pointing at an ancestor directory recurses forever.

C:/PROGRA~1 and 8.3 short names: one directory, two strings

On the same machine:

os.path.exists('C:/PROGRA~1')                        ->  True
os.path.samefile('C:/Program Files', 'C:/PROGRA~1')  ->  True
os.listdir('C:/PROGRA~1')                            ->  ['AMD', 'Android', 'Autodesk', ...]
os.path.exists('C:/WINDOW~1')                        ->  False

The first two lines show the short name is a real alias. The fourth is the trap: on the same machine, for another system directory, no short name exists. Whether an 8.3 name exists depends on volume policy and on when the entry was created; it is not a guarantee.

String comparison loses everywhere: 'C:/PROGRA~1' != 'C:/Program Files', different lengths, different hashes, different allowlist matches, while samefile says they are the same directory. Use os.path.samefile for identity and os.path.normcase for a comparable string, which the docs describe as lowercasing everything and converting forward slashes to backslashes on Windows.

a[1].txt: glob reads square brackets as a character class

With both a[1].txt and a1.txt present, matching the first one literally:

Path(d).glob('a[1].txt')                  ->  ['a1.txt']
Path(d).glob(glob.escape('a[1].txt'))     ->  ['a[1].txt']
fnmatch.fnmatch('a[1].txt', 'a[1].txt')   ->  False

[1] is a class matching the character 1, so the pattern selected the other file. The glob docs say "For a literal match, wrap the meta-characters in brackets. For example, '[?]' matches the character '?'" — that sentence teaches pattern syntax, it does not promise escaping. glob.escape is the escape entry point and covers ?, * and [.

This shape is common in practice: log files, backup names, paths assembled from user input. One missing escape in a copy, delete or count step means operating on a different file. It is the default risk of every pattern-driven bulk operation, not something specific to glob.

Troubleshooting: reading four real errors

OSError: [Errno 22] Invalid argument on a path with the \\?\ prefix. Almost always a .. or a forward slash after the prefix. Fix: abspath first, then replace separators, confirm no .. remains, and only then prepend the prefix.

FileNotFoundError: [Errno 2] No such file or directory when the file is right there. Measure the length first. At 260 and above this is the error under default settings, and exists() cooperates by returning False. The test is len(p) >= 260, not "the file is gone".

FileNotFoundError: [WinError 3] from os.stat or os.listdir. Same cause, different code per API: open gives Errno 2, stat and listdir give WinError 3. Suspect length before permissions.

OSError: [WinError 17] from os.replace. Cross-volume rename does not exist on Windows. Measured: os.replace raised 17 while shutil.move succeeded by degrading to copy-then-delete, which costs atomicity — the source may be gone while the destination is half written.

One more: calling os.listdir on a file gives NotADirectoryError: [WinError 267], which only appears when the path exists but is the wrong kind of thing. That is a different world from "does not exist".

Two more worth keeping

Case. Write Case.TXT, read it as case.txt: it works, samefile says True, and Path('C:/Temp/Case.TXT') == Path('c:/temp/case.txt') is True on Windows because PurePath comparison folds case there. String == is still False. So "the same file" has three different answers: strings differ, Path objects are equal, samefile is equal.

Device names. The naming rules say plainly: "Also avoid these names followed immediately by an extension; for example, NUL.txt and NUL.tar.gz are both equivalent to NUL." On this build 26300, cmd /c echo hello > nul.txt produced a real 12-byte file, type nul.txt read it back, and os.listdir listed it; only the bare nul stayed a black hole that accepts writes and creates nothing. Both behaviors reproduce, so the advice is not "which one is right" but: do not use device names as filenames, and do not write code that depends on either behavior.

A checklist you can paste into code

None of this is hard to adopt, but skip any one line and the failure you see will be "file not found" or "one extra copy", never the actual cause. Paths belong to the same family as module imports: you think you are describing an object, when you are writing a string that will be reinterpreted. A companion piece on this site covers eight ways Python imports give you the wrong file; earlier, five ways tarfile extraction writes outside the destination shows the security side of a path string reinterpreted downstream, and nine silent bash failures with exit code 0 covers the same failure shape from the shell side.

No affiliate links in this article. All figures are measured on Windows 11 build 26300 with CPython 3.13.12 on NTFS; documentation is quoted from Microsoft Learn's Naming Files, Paths, and Namespaces, File Streams and Hard Links and Junctions pages, and from the CPython 3.13 docs and Lib/os.py.

Scope and limits

FAQ

Q: If os.path.exists returns False, is the file definitely missing?

No. At 260 characters it returns False whether or not the file is there. Measure the absolute length before you doubt the file.

Q: Why did shutil.copy2 lose part of the file?

Because it copies the default data stream. NTFS named streams (file:stream) are outside that path, and Windows' own copy behaves the same. You need stream-aware tooling or an API such as CopyFile2.

Q: Why does followlinks=False still descend into a junction?

The flag only checks islink. A junction reports False there, so os.walk sees an ordinary directory and descends. Filter with os.path.isjunction yourself.

Q: Is the \\?\ prefix just a long-path switch?

It disables string parsing and, as a side effect, the length check. The price is that .., forward slashes and relative paths stop being handled. Normalize the path yourself first.

👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

As an Amazon Associate, I earn from qualifying purchases at no extra cost to you.

☁️ DigitalOcean Cloud ⚡ Vultr VPS 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🧠 AI & LLM Books 🏗️ System Design Books 🐳 Docker & K8s Books 🐧 Linux Admin Books 🐍 Python Books 🗄️ Database Books 🚀 DevOps & SRE Books 🤖 Xiaomi MiMo Platform
← Back to Home