161

According to the official documentation, os.path is a module. Thus, what is the preferred way of importing it?

# Should I always import it explicitly?
import os.path

Or...

# Is importing os enough?
import os

Please DON'T answer "importing os works for me". I know, it works for me too right now (as of Python 2.6). What I want to know is any official recommendation about this issue. So, if you answer this question, please post your references.

mkrieger1
  • 19,194
  • 5
  • 54
  • 65
Denilson Sá Maia
  • 47,466
  • 33
  • 109
  • 111

6 Answers6

187

os.path works in a funny way. It looks like os should be a package with a submodule path, but in reality os is a normal module that does magic with sys.modules to inject os.path. Here's what happens:

  • When Python starts up, it loads a bunch of modules into sys.modules. They aren't bound to any names in your script, but you can access the already-created modules when you import them in some way.

    • sys.modules is a dict in which modules are cached. When you import a module, if it already has been imported somewhere, it gets the instance stored in sys.modules.

  • os is among the modules that are loaded when Python starts up. It assigns its path attribute to an os-specific path module.

  • It injects sys.modules['os.path'] = path so that you're able to do "import os.path" as though it was a submodule.

I tend to think of os.path as a module I want to use rather than a thing in the os module, so even though it's not really a submodule of a package called os, I import it sort of like it is one and I always do import os.path. This is consistent with how os.path is documented.

Incidentally, this sort of structure leads to a lot of Python programmers' early confusion about modules and packages and code organization, I think. This is really for two reasons

  1. If you think of os as a package and know that you can do import os and have access to the submodule os.path, you may be surprised later when you can't do import twisted and automatically access twisted.spread without importing it.

  2. It is confusing that os.name is a normal thing, a string, and os.path is a module. I always structure my packages with empty __init__.py files so that at the same level I always have one type of thing: a module/package or other stuff. Several big Python projects take this approach, which tends to make more structured code.

Honest Abe
  • 8,430
  • 4
  • 49
  • 64
Mike Graham
  • 73,987
  • 14
  • 101
  • 130
  • Excellent, very informative answer! Congratulations! Even though it doesn't directly answer the question, it has lots of useful details. But could you please elaborate on "This is consistent with how os.path is documented"? Like Chris Hulan said, the os.walk() example imports just os instead of os.path. – Denilson Sá Maia Apr 27 '10 at 21:36
  • 4
    @Denilson, It does include a direct answer: I always do `import os.path` myself and think that's a nicer way. By "This is consistent with how os.path is documented" I meant that it is given its own page in the documentation at http://docs.python.org/library/os.path.html . – Mike Graham Apr 27 '10 at 21:50
  • 3
    Wow, `os.py` does indeed inject into `sys.modules['os.path']`. So this is why `from os.path import something` actually works. I was curious about when this was introduced and checked the source. Fun fact: This is from 1999, first included in Python 1.5.2. Original commit is [here](https://github.com/python/cpython/commit/0237909e420db2897034a371087963be4a312552). – Bluehorn Dec 18 '19 at 10:12
31

As per PEP-20 by Tim Peters, "Explicit is better than implicit" and "Readability counts". If all you need from the os module is under os.path, import os.path would be more explicit and let others know what you really care about.

Likewise, PEP-20 also says "Simple is better than complex", so if you also need stuff that resides under the more-general os umbrella, import os would be preferred.

Nick T
  • 25,754
  • 12
  • 83
  • 121
  • 2
    I don't see how `import os` is really about being "simple" in any meaningful way. Simple != short. – Mike Graham Apr 27 '10 at 21:20
  • 16
    I was more trying to point out that `import os` **and** a `import os.path` is daft if you e.g. need `os.getcwd()` and `os.path.isfile()` – Nick T Apr 27 '10 at 21:32
  • Though importing both is unnecessary, I think "daft" is a bit strong. – chepner Jan 08 '22 at 23:30
15

Definitive answer: import os and use os.path. do not import os.path directly.

From the documentation of the module itself:

>>> import os
>>> help(os.path)
...
Instead of importing this module directly, import os and refer to
this module as os.path.  The "os.path" name is an alias for this
module on Posix systems; on other systems (e.g. Mac, Windows),
os.path provides the same operations in a manner specific to that
platform, and is an alias to another module (e.g. macpath, ntpath).
...
Lesmana
  • 25,663
  • 9
  • 82
  • 87
  • 16
    Note that it's not docs for an `os.path` module which doesn't exist, but for `posixpath`. – wRAR May 08 '13 at 10:12
  • 22
    That is not at all how I think that docstring is meant to be interpreted, although it is pretty misleading. Keep in mind that the sentence `"Instead of importing this module directly, import os and refer to this module as os.path."` is located in `posixpath.py` (or `macpath.py`, `ntpath.py` etc.). I'm fairly sure that what they mean is that one should not `import posixpath` (which works), but rather import the module via `os` for better portability. I don't think they intend to give a recommendation as to whether `import os` or `import os.path` is preferred. – flornquake Jun 05 '16 at 23:42
  • 1
    I agree with most of @flornquake 's comment but disagree with the last sentence. Both posixpath.py and ntpath.py say "import os and refer to this module as os.path". They do not say "import os.path and refer to this module as os.path". macpath.py has nothing on the matter. – Pete Forman Jun 27 '17 at 09:14
  • 7
    This is a good example of showing how a document containing a *this* pointer can be misleading :D – Cyker Sep 06 '18 at 17:42
  • 1
    I can't think of any reason to inject `os.path` into `sys.modules` *except* to allow `import os.path` as an import. If you weren't supposed to use the direct import, why bother adding `os.path` to `sys.modules` in the first place? – chepner Jan 08 '22 at 23:15
10

Interestingly enough, importing os.path will import all of os. try the following in the interactive prompt:

import os.path
dir(os)

The result will be the same as if you just imported os. This is because os.path will refer to a different module based on which operating system you have, so python will import os to determine which module to load for path.

reference

With some modules, saying import foo will not expose foo.bar, so I guess it really depends the design of the specific module.

In general, just importing the explicit modules you need should be marginally faster. On my machine:

import os.path: 7.54285810068e-06 seconds

import os: 9.21904878972e-06 seconds

These times are close enough to be fairly negligible. Your program may need to use other modules from os either now or at a later time, so usually it makes sense just to sacrifice the two microseconds and use import os to avoid this error at a later time. I usually side with just importing os as a whole, but can see why some would prefer import os.path to technically be more efficient and convey to readers of the code that that is the only part of the os module that will need to be used. It essentially boils down to a style question in my mind.

Matt Boehm
  • 1,894
  • 1
  • 18
  • 21
  • 3
    `from os import path` will make the calls to path even faster if speed is the issue. – Justin Peel Apr 27 '10 at 19:48
  • Being pythonic, explicit is better than implicit right? In reality I think it really is the judgment call by the user, whether the user is only going to use os.path or multiple modules within os. Maybe one method is more in line with your philosophy over the other? – Andrew Kou Apr 27 '10 at 20:09
  • 27
    Timing this is some of the prematurest premature optimization I've ever seen. This has never been *anyone's* bottleneck and the time here is immaterial to how someone should code. – Mike Graham Apr 27 '10 at 21:20
  • 1
    This isn't unique to `os.path`. [As documented](https://docs.python.org/3/reference/simple_stmts.html#the-import-statement), any non-top-level module import binds the name of the top-level package in the current name space as well. Importing a module also requires the (implicit) import of the package(s) containing it. – chepner Jan 08 '22 at 23:29
6

Common sense works here: os is a module, and os.path is a module, too. So just import the module you want to use:

  • If you want to use functionalities in the os module, then import os.

  • If you want to use functionalities in the os.path module, then import os.path.

  • If you want to use functionalities in both modules, then import both modules:

    import os
import os.path

For reference:

Cyker
  • 9,946
  • 8
  • 65
  • 93
  • 1
    Strictly speaking, `os.path` is an *alias* for an OS-specific module with its own name. `import os.path` is redundant if you already have `import os`, since `os` also has an attribute `path` that refers to the same module. (Which is not to say it doesn't have documentation benefits, only that it's not necessary.) – chepner Jan 08 '22 at 23:21
  • 1
    @chepner The description you gave is useful. But [the official documentation](https://docs.python.org/3/library/os.path.html) simply mentions `os.path` as a *module* while talking nothing about *alias*. The technical detail is injecting a name into `sys.modules`. – Cyker Jan 08 '22 at 23:41
  • 1
    There is no single module named `os.path`. It's always an alias for either `posixpath` or `ntpath`. – chepner Jan 09 '22 at 03:05
  • The same documentation also only links to the files for those two modules. CPython, at least, does not provide a separate or distinct module named `os.path`. – chepner Jan 09 '22 at 03:16
5

Couldn't find any definitive reference, but I see that the example code for os.walk uses os.path but only imports os

tzot
  • 92,761
  • 29
  • 141
  • 204
Chris Hulan
  • 161
  • 4
  • Not (or no longer) true; there's one example that uses `os.path` as a module attribute of `os`, but also an example that uses `from os.path import join, getsize`. Granted, that has as much to do with the `from ... import ...` statement disallowing something like `from os import path.join as join, path.getsize as getsize`. – chepner Jan 08 '22 at 23:23