What happens to each line of a .pth file found in a site-packages directory?

### The file format A `.pth` file is a plain-text file whose name ends in `.pth`, living in a *site directory*. The format is deliberately trivial and is processed one line at a time: - **Blank lines** and lines whose first character is `#` are ignored. - **A line starting with `import ` or `import\t`** is passed to `exec`. It runs as code, at startup, in the `site` module's context. - **Anything else** is treated as a directory path. It is joined against the directory that contains the `.pth` file (so relative entries are relative to the site directory, not to your working directory), and appended to `sys.path` when the directory exists and is not already present. The surprise for most people is the second rule. It exists so that a distribution can perform startup-time setup — registering a codec, installing an import hook, patching something — without the application knowing. It is used rarely and deliberately, and it is the reason a `.pth` is a genuine execution surface, not just a path list. ### Where the file has to live A `.pth` is not a general mechanism that applies anywhere on `sys.path`. It is read only from directories `site` treats as site directories: the ones it computes from the prefixes at startup, the per-user directory when it is enabled, and anything registered explicitly via `site.addsitedir(path)`. Dropping a `.pth` into an ordinary directory that merely happens to be on `sys.path` — your project root, say — does nothing at all. This trips people who try to "fix" a path problem by leaving a `.pth` next to their script. `site.addsitedir` is the supported way to opt a directory in at runtime: it appends the directory itself and then processes its `.pth` files exactly as startup would. ### Why you meet them in practice The most common encounter is an editable install. Rather than copying your source into site-packages, the installer writes a small `.pth` there that names your source tree (or executes a line that installs a finder for it). Startup appends the directory, so your working copy is importable, and edits take effect without reinstalling. That is also why an editable install is invisible to anything that only reads copied files: the evidence lives in a one-line text file, not in a package directory. The second common encounter is a distribution that needs to run at startup — a coverage or profiling hook, a compatibility patch, a codec registration. These use the executable `import` line. ### Ordering, and why not to rely on it Within one site directory, `site` sorts the `.pth` file names before processing them, which is why you occasionally see numeric prefixes such as `00-something.pth` used to force an order. Across site directories, order follows the order in which `site` processes the directories themselves. Both are implementation-level facts, not a stable contract you should build behaviour on. If two `.pth` files must run in a particular order, that is a design smell: prefer one explicit entry point that does the setup in a known sequence. ### Failure behaviour Errors do not take the interpreter down. When a line raises, `site` prints the failing file, the line number and the traceback to stderr, then abandons the remainder of that file and continues startup. The practical effect is nasty in production: your program runs, but some setup silently did not happen, and the only evidence is a message that scrolled past on stderr — often into a log nobody greps. A duplicated or missing side effect that appears in one environment and not another is very often a `.pth` file that half-ran. ### Security and hygiene An executable line in a `.pth` file runs before your first statement, with your process's privileges, every time that interpreter starts. Anything that can write into a site directory therefore has code execution in every process using that interpreter. This is one concrete reason environments should be built from a lockfile by a process you control, and site directories should not be world-writable. For your own code, prefer the boring alternative: do setup explicitly in your entry point, where it is visible, ordered and testable. Reach for a `.pth` only when the setup genuinely must happen before user code — and then make it a single import line that delegates to a real module you can read, rather than logic inlined into a text file. This format and its rules are unchanged on 3.14.