FactorPad
Build a Better Process

Syntax of the Python os.path Module with Examples

This module comes with 30 functions to return paths, Booleans, times and file sizes, so it offers useful ways to work with the file system.
  1. About - Review the purpose, rules and location of the os.path module.
  2. Assignment - Construct a string object with examples.
  3. Functions - Learn os.path function syntax with examples.
  4. Methods - See which methods help with os.path.
  5. Help - Find additional information locally.
face pic by Paul Alan Davis, CFA
Updated: February 24, 2021
Because case sensitivity and directory structures across Linux, macOS and Windows differ, here we show examples of both for all 30 functions. See how fun that can be.

Outline Back Tip Next

/ factorpad.com / tech / python / reference / python-os-path.html


An ad-free and cookie-free website.


A Guide to Working with HTML documents in Python

Beginner

Python Reference

This Python reference offers programmers a quick way to learn Python and also serves as a source for reminders.

While the version documented here is Python 3.5.3, most of this is suitable for other versions of Python 3. Check your version for details.

Outline

  1. About the Python os.path Module
    1. How to access the appropriate data types
  2. Python os.path Assignment
    1. Syntax
    2. Examples
  3. Python os.path Functions
    1. Syntax
    2. Examples
  4. Python os.path Methods
    1. Syntax
    2. Examples
  5. Find Local Help on Python os.path

1. About the Python os.path module

The os.path module comes with 30 functions and works with two data types, strings or bytes. However, strings are most common and will be most of the focus here.

The functionality of os.path is mostly for finding with absolute and relative paths in the filesystem, but can also be used to find the time when files were created, modified and accessed. Also, Booleans help with program logic and the size of files can be accessed as well. So the module has many use cases.

Because Linux/macOS and Windows differ in path naming conventions some differences may occur and will be shown here. Case sensitivity is another topic to consider carefully when reviewing the examples here.

a. How to access the os.path module

Here we assume the most basic import scenario without aliasing. See our reference document on importing modules for more.

2. Python os.path Assignment

Assignment operations are not required for os.path as it comes with no methods, only functions. Valid data types include the string or bytes data type. A few functions require integers and tuples.

This section is offered as a review for beginners, skip to the functions if you understand string assignment in Python.

Below is syntax for creating a string object with assignment, followed by examples.

a. Assignment syntax
Syntax Priority
x = str(object='')
Assignment to a string using the formal approach with the built-in string function. If left blank, the default object='' will create an empty string object.
High
x = 'string'
Assignment to a string using the shortcut, normally enclosed in single quote (') or double quote (") symbols.
High
b. Assignment examples

Here we demonstrate how to create a valid string object created in the context of filesystem paths. We labeled it x and show how to create a string using the long form and short form.

# A path string using the built-in str() function >>> x = str(".") # The "." means current directory >>> type(x) <class 'str'> # A path string using the '' shortcut, could also use "" >>> x = '.' >>> type(x) <class 'str'>

Note that in both examples either a single quote (') or double quote (") is required.

3. Python os.path Functions

The Python os.path functions can be called from Python scripts or the Python Interpreter.

In most cases, the parameter for each os.path function requires one single or multiple path strings as described above. Bytes can also be supplied, but we will not cover that here.

Also, as a takeaway try to focus on the 6 noted as High in the Priority column. These are the most commonly searched for functions of the 30 in total.

a. Function syntax

The 30 functions in the os.path module are segmented into 4 groups.

Functions returning paths

Strings are typically used to navigate the filesystem programmatically or report pathname specifications.

Syntax Priority
os.path.abspath(path)
Returns the full absolute path from the root.
The path string is required and only one can be passed.
High
os.path.basename(path)
Returns the basename or the last section in the path supplied without a directory notation (/) or (\\).
The path string is required and only one can be passed.
Mid
os.path.commonpath(paths)
Used to compare paths for multiple provided in a sequence (list or tuple typically). Returns the longest common subpath of the two or more paths supplied.
The paths sequence is a required paramater and it cannot mix relative and absolute paths.
Mid
os.path.commonprefix(list)
Used to compare paths for multiple provided in a list, however a tuple can be supplied as well. Returns the longest common subpath of the two or more paths supplied in the list working from left to right, so a functional directory name may not be returned.
The list of paths is a required paramater and as long as a sequence is provided, whether it has one or two values, at a minimum an empty string ('') will be returned. It cannot mix relative and absolute paths.
Low
os.path.dirname(path)
Returns the directory name in the path supplied as a string. So if a filename is supplied, the directory will be returned.
The path is required and only one can be passed.
High
os.path.expanduser(path)
For paths that begin with the ~ symbol signifying the user's home directory this function returns the user's home directory or the originally supplied path if the expansion fails or the string does not begin with a ~.
The path is a required string and only one can be passed.
Mid
os.path.expandvars(path)
Returns the argument when environment variables are provided.
The path is a required string and only one can be passed.
Mid
os.path.join(path, *paths)
Used to construct paths from strings provided.
The path is a required string and only one can be passed. The *paths parameter takes one or many path strings.
High
os.path.normcase(path)
Used to normalize paths primarily for Windows filesystems due to their case-insensitive nature. On Windows the string is changed to lowercase and single forward slashes (/) are changed to two backward slashes (\\). On Linux it returns path unchanged.
The path is a required string and only one can be passed.
Mid
os.path.normpath(path)
Used to normalize paths by removing redundant separators, which may make symbolic links not function properly. On Windows it changes single forward slashes (/) to two backward slashes (\\).
The path is a required string and only one can be passed.
Mid
os.path.realpath(path)
Returns the canonical, or direct path, to the specified filename thereby eliminating any symbolic links, if any.
The path is a required string and only one can be passed.
Low
os.path.relpath(path, start=os.curdir)
Returns the relative path directions to go from the current directory to that specified in path. No actual directory lookup is being performed to confirm the existence of directories, instead this is calculated.
The path is a required string. The start=os.curdir parameter is optional and defaults to the current directory, which can be overridden to a different directory. Also see the os.curdir function.
Mid
os.path.split(path)
Splits the path into a (head, tail) tuple where head refers to the last pathname component containing a slash (/) on Linux or double back slash (\\) on Windows, with slashes stripped. The tail is the remaining part. It will never have a slash (/) or double back slash (\\). If the path ends with a slash (/) or double backslash (\\) the tail will be returned as an empty string.
The path parameter is not required and will return two empty strings ('') for head and tail if not supplied.
Mid
os.path.splitdrive(path)
Splits the path into a (drive, tail) tuple where drive refers to the mountpoint, so mostly on Windows and will include the colon symbol. The tail is the remaining part, it will often have the slash (/) or double backslash (\\). If the path doesn't have a drive letter, the head will be returned as an empty string. If the path uses UNC conventions ('//host/computer/dir') the head would result would be ('//host/computer', '/dir').
The path is a required string and only one can be supplied.
Low
os.path.splittext(path)
Splits the path into a (root, ext) tuple where root refers to the first part of a filename and ext refers to the extension. Filenames with a leading period (.) will be ignored and the results will go in the root, the ext will be an empty string ('').
The path is a required string and only one can be supplied.
Mid
Functions returning Booleans

Boolean responses are typically used to add logic to programs relating to filesystem paths.

Syntax Priority
os.path.exists(path)
Returns True if the path exists, and False if a directory is not accessible (broken symbolic links, directory permissions, non-existent paths).
The path is a required string and only one can be passed.
High
os.path.lexists(path)
Returns True if the path exists, even if a symbolic link is broken.
The path is a required paramater, passed as a string and only one can be passed.
Mid
os.path.isabs(path)
Returns True if path is an absolute pathname.
The path is a required string and only one can be passed.
Mid
os.path.isfile(path)
Returns True if path is an existing file.
The path is a required paramater, passed as a string and only one can be passed.
High
os.path.isdir(path)
Returns True if path is an existing directory. This includes regular and symbolic links.
The path is a required paramater, passed as a string and only one can be passed.
High
os.path.islink(path)
Returns True if path is a symbolically linked directory.
The path is a required paramater, passed as a string and only one can be passed.
Mid
os.path.ismount(path)
Returns True if path is a mount point. This may be a different mount point in Linux or drive letter on Windows.
The path is a required paramater, passed as a string and only one can be passed.
Mid
os.path.samefile(path1, path2)
Returns True if path1 and path2 point to the same file or directory.
The path1 and path2 parameters are required, both passed as a string.
Low
os.path.sameopenfile(fp1, fp2)
Returns True if file descriptors for fp1 and fp2 refer to the same file. A file descriptor is a number that uniquely identifies an open file on the computer.
The fp1 and fp2 parameters are required, both passed as an integer.
Low
os.path.samestat(stat1, stat2)
Returns True if the stat tuples stat1 and stat2 refer to the same file. These are often looked up using os.fstat(), os.lstat() or os.stat(). See example below.
The stat1 and stat2 parameters are required, both passed as a tuple. See the os.stat function for more information.
Low
os.path.supports_unicode_filenames
Returns True if Unicode strings can be supplied in filenames.
This is the only function that does not require an argument.
Low
Functions returning timestamps

Timestamps are used to report access, modify and create times for files and directories.

Syntax Priority
os.path.getatime(path)
Returns the time since the directory supplied as path was last accessed. Time is given in seconds since the epoch time. See the time module for details.
The path is a required paramater, passed as a string and only one can be passed.
Low
os.path.getmtime(path)
Returns the time since the file supplied as path was last modified. Time is given in seconds since the epoch time. See the time module for details.
The path is a required string and only one can be passed.
Mid
os.path.getctime(path)
Returns the time since the file supplied as path had its metadata changed (Linux) or created (Windows). Time is given in seconds since the epoch time. See the time module for details.
The path is a required paramater, passed as a string and only one can be passed.
Mid
Function returning file sizes

There is one function that returns file sizes.

Syntax Priority
os.path.getsize(path)
Returns the size of the path file in bytes.
The path is a required paramater, passed as a string and only one can be passed.
Mid

To calculate the aggregate size of all files in a directory it is common to use a loop.

b. Function examples

For the examples below, to illustrate the difference between Linux/macOS and Windows, assume the following directory structure.

# Linux/macOS # Windows ----------------- ----------------- /home \Users /paul \Paul notes.txt Notes.txt /bin \bin /backup.py \backup.py /bot.py \bot.py /website \website /index.html \index.html /style.css \style.css /image.png \image.png

NOTE: Since macOS is similar to Linux with respect to directories using the forward slash symbol (/), that is where macOS is grouped in these examples. Where macOS and Linux differ is in case-insensitive versus case-insensitive file and pathnames. Please make this adjustment on your end.

Function examples are organized in the same fashion as the syntax was introduced above, so the 30 functions are segmented the same way.

Functions returning paths

Starting with the os.path.abspath() function let's say we're in the base of the working directory. The dot (.) specifies the current directory.

# Absolute path >>> os.path.abspath('.') '/home/paul' # Linux / macOS >>> os.path.abspath('.') 'C:\\Users\\Paul' # Windows

To illustrate the os.path.basename function let's specify the full path to the style.css file and it returns only that filename part.

# Base name >>> os.path.basename('/home/paul/website/style.css') 'style.css' # Linux / macOS >>> os.path.abspath('C:\\Users\\Paul\\website\\style.css') 'style.css' # Windows

We can supply a list of paths to os.path.commonpath() to see the longest subpath in common with both files or directories.

# Common path >>> os.path.commonpath(['/home/paul/bin/backup.py', '/home/paul/website/image.png']) '/home/paul' # Linux / macOS >>> os.path.commonpath(['C:\\Users\\Paul\\bin\\backup.py', 'C:\\Users\\Paul\\website\\image.png']) 'C:\\Users\\Paul' # Windows

In the example below we use the os.path.commonpath() function which matches common paths left to right. A working path may not result.

# Common prefix >>> os.path.commonprefix(['/home/paul/bin/backup.py', '/home/paul/bin/bot.py']) '/home/paul/bin/b' # Linux / macOS >>> os.path.commonprefix(['C:\\Users\\Paul\\bin\\backup.py', 'C:\\Users\\Paul\\bin\\bot.py']) 'C:\\Users\\Paul\\bin\\b' # Windows

The os.path.dirname() function returns the directory name of the specified path.

# Directory name >>> os.path.dirname('/home/paul/bin/bot.py') '/home/paul/bin' # Linux / macOS >>> os.path.dirname('C:\\Users\\Paul\\bin\\bot.py') 'C:\\Users\\Paul\\bin' # Windows

With the os.path.expanduser() function you can expand the home directory symbol.

# Expand user >>> os.path.expanduser('~/notes.txt') '/home/paul/notes.txt' # Linux / macOS >>> os.path.expanduser('~\\Notes.txt') 'C:\\Users\\Paul\\Notes.txt' # Windows

With the os.path.expandvars() function you can access system environment variables and build paths from there.

# Expand variables >>> os.path.expandvars('$HOME') '/home/paul' # Linux / macOS >>> os.path.expandvars('%HomePath%') 'C:\\Users\\Paul # Windows

The os.path.join() function is used to join or concatenate multiple paths specified as strings.

# Join paths >>> os.path.join('/home/paul', 'website/index.html') '/home/paul/website/index.html' # Linux / macOS >>> os.path.join('C:\\Users\\Paul', 'website\\index.html') 'C:\\Users\\Paul\\website\\index.html' # Windows

The os.path.normcase() function helps to normalize paths for Windows in particular. Note how directories were changed and all text lowercased on the Windows example.

# Normalize case >>> os.path.normcase('/home/paul/website/image.png') '/home/paul/website/image.png' # Linux / macOS >>> os.path.normcase('C:/Users/Paul/website/image.png') 'C:\\user\\paul\\website\\image.png' # Windows

Use the os.path.normpath() function to change all slashes to the Linux standard. This is primarily for Windows, notice how on Linux Python returns the string unchanged.

# Normalize paths >>> os.path.normpath('\\home\\paul\\notes.txt') '\\home\\paul\\notes.txt' # Linux / macOS >>> os.path.normpath('/Users/Paul/Notes.txt') '\\Users\\Paul\\Notes.txt' # Windows

The os.path.realpath() function will return the canonical path, thereby eliminating symbolic links. In this example all of our links are canonical.

# Normalize paths >>> os.path.realpath('/home/paul/notes.txt') '/home/paul/notes.txt' # Linux / macOS >>> os.path.realpath('C:\\Users\\Paul\\Notes.txt') 'C:\\Users\\Paul\\Notes.txt' # Windows

The os.path.relpath() function calculates the relative path specification that would take you to the first path supplied from the second.

# Relative paths calculated >>> os.path.relpath('/home/paul/bin/', '/home/paul/website/') '../bin' # Linux / macOS >>> os.path.relpath('/Users/Paul/Notes.txt') '..\\bin' # Windows

The os.path.split() function splits the path into a directory part and file part returning a tuple.

# Split paths >>> os.path.split('/home/paul/website/index.html') ('/home/paul/website', 'index.html') # Linux / macOS >>> os.path.split('C:\\Users\\Paul\\website\\index.html') ('C:\\Users\\Paul\\website', 'index.html') # Windows

The os.path.splitdrive() function splits the path into a drive part and remaining part returning a tuple. This is primarily used on Windows and using UNC conventions.

# Split drive >>> os.path.splitdrive('/home/paul/notes.txt') ('/home/paul/notes.txt', '') # Linux / macOS >>> os.path.splitdrive('C:\\Users\\Paul\\notes.txt') ('C:', '\\Users\\Paul\\Notes.txt') # Windows

With the os.path.splitext() function you can split a file path into a root part and and extension part. Note that there is one 't' in splitext.

# Split file extensions >>> os.path.splitext('/website/index.html') ('/website/index', '.html') # Linux / macOS >>> os.path.splitext('\\website\\index.html') (''\\website\\index', '.html') # Windows
Functions returning Booleans

Boolean responses are typically used to add logic to programs relating to filesystem paths.

Use the os.path.exists() function to report if a path exists. Note the difference in case sensitivity between Linux and case insensitivity in Windows. In this case most macOS systems behave more like the Windows operating system.

# Test if a path exists >>> os.path.exists('/home/paul/Notes.txt') False # Linux / macOS >>> os.path.exists('C:\\Users\\Paul\\notes.txt') True # Windows / macOS

Use the os.path.lexists() function to report if a path exists. In this example assume the directory path was a symbolic link.

# Test whether a path exists including symbolic links >>> os.path.exists('/home/paul/website/') True # Linux / macOS >>> os.path.exists('C:\\Users\\Paul\\website\\') True # Windows

The os.path.isabs() function is used to report whether a path name is an absolute path.

# Test whether a path exists including symbolic links >>> os.path.isabs('../website/') False # Linux / macOS >>> os.path.isabs('C:\\Users\\Paul\\website\\') True # Windows

The os.path.isfile() function is used to see if a regular file exists. Note the difference in case sensitivity between Linux and case insensitivity in Windows, and in this case macOS.

# Test if path points to a file >>> os.path.isfile('/home/paul/Notes.txt') False # Linux / macOS >>> os.path.isfile('C:\\Users\\Paul\\notes.txt') True # Windows / macOS

The os.path.isdir() function tests whether the path points to a directory. Note the difference in case sensitivity between Linux/macOS and case insensitivity in Windows. Also, the final forward slash (/) or backward slashes (\\) need not be included.

# Test if path points to a directory >>> os.path.isfile('/home/paul') True # Linux / macOS >>> os.path.isfile('C:\\users\\paul\\') True # Windows / macOS

With the os.path.islink() function you can test whether the path is symbolically linked. Here we don't have symbolic links.

# Test if path points to a symbolic link >>> os.path.islink('/home/paul/website') False # Linux / macOS >>> os.path.islink('C:\\Users\\Paul\\website') False # Windows

The os.path.ismount() function tests whether the path is a mount point.

# Test if path points to a mount point >>> os.path.ismount('/') True # Linux / macOS >>> os.path.ismount('C:\\') True # Windows

The os.path.samefile() function tests whether the files specified are the same. Note the difference in case sensitivity between Linux and case insensitivity in Windows. Again on macOS, it case sensitivity is more like Windows.

# Test if paths point to the same file >>> os.path.samefile('/home/paul/notes.txt', '/home/paul/Notes.txt') False # Linux / macOS >>> os.path.samefile('c:\\users\\paul\notes.txt', 'C:\\Users\\Paul\Notes.txt') True # Windows / macOS

The os.path.sameopenfile() function tests whether the files specified by file descriptor are the same open file. Arguments passed must be a file descriptor integer. A use case may be to test whether a file like bot.py in our example was open multiple times. Here we will use dummy integer values as the rest is beyond our scope here.

# Test if paths point to the same open file >>> os.path.sameopenfile(4205, 4301) True # Linux / macOS >>> os.path.sameopenfile(31982, 32001) False # Windows

The os.path.samestat() function tests whether the files specified return the same stat which is a tuple providing detailed information about files. These are often looked up using os.fstat(), os.lstat() or os.stat().

# Test if paths return the same stat tuples stat1 = os.stat(/home/paul/notes.txt stat2 = os.stat(/home/paul/notes.txt >>> os.path.samestat(stat1, stat2) True # Linux / macOS stat1 = os.stat('C:\\Users\\Paul\\notes.txt stat2 = os.stat('C:\\Users\\Paul\\notes.txt >>> os.path.samestat(stat1, stat2) True # Windows

The os.path.supports_unicode_filenames takes no arguments and reports whether the operating system supports Unicode filenames.

# Test if the Operating System supports Unicode filenames >>> os.path.supports_unicode_filenames False # Linux / macOS >>> os.path.supports_unicode_filenames True # Windows
Functions returning timestamps

These 3 functions return elapsed time since epoch as a float. To translate this to a readable format, the datatime module offers a solution.

Use the os.path.getatime() function to return the time the path was last accessed in seconds since epoch.

# Return time the path was last accessed >>> os.path.getatime('/home/paul') 1544270461.9960694 # Linux / macOS >>> os.path.getatime('C:\\Users\\Paul') 1544299710.3839312 # Windows

The os.path.getmtime() function will return the time the path was last modified in seconds since epoch.

# Return time the path was last modified >>> os.path.getmtime('/home/paul/notes.txt') 1544270583.8967290 # Linux / macOS >>> os.path.getmtime('C:\\Users\\Paul\\Notes.txt') 1544299936.5829109 # Windows

The os.path.getctime() function is used to return the time the path was created in seconds since epoch. See the time and datetime modules for additional processing of time.

# Return time the path was created >>> os.path.getatime('/home/paul/website/image.png') 1544271293.9932810 # Linux / macOS >>> os.path.getmtime('C:\\Users\\Paul\\website\\image.png') 1544299998.8675309 # Windows
Function returning file sizes

The os.path.getsize() function returns the size of a specified file in a directory and through a loop can return a total.

# Return time the size of a file in bytes >>> os.path.getsize('/home/paul/website/image.png') 129372 # Linux / macOS >>> os.path.getsize('C:\\Users\\Paul\\website\\image.png') 129372 # Windows

That's a lot to take in during one sitting, which is why this is a reference document and will be here when you need it.

4. Python os.path Methods

Keep in mind, there are no methods in the os.path module and most inputs are strings, so the examples below provide two examples of methods for strings. This can also be found in a separate discussion of strings in Python.

a. Method syntax

The method syntax examples below assume that the string object has been named x.

Syntax Priority
x.lower()
A common use case with HTML strings, especially in search contexts, is to transform all uppercase characters to lowercase using this string method.
Mid
x.replace(old, new[, count])
The old and new parameters are required and are supplied as strings (' ', " ", ''' ''', or """ """). The optional parameter count will make that number of replacements, from start to finish.
Mid

These methods, while not part of the os.path module are mentioned here so beginners can gain a better understanding of string objects in Python, and as a background for our next example.

b. Method examples

At long last, in our final example we tie it all together. We create an instance of a path string object with text that was capitalized and provided in a messy format. Our objective is to see if it is a valid address on the system and finally, the size of the file.

# An example to fix a string with capitalized and unconventional directories. >>> messy = '|HOME|PAUL|WEBSITE|INDEX.HTML' >>> type(messy) <class 'str'> # Change all text to lowercase using the lower() string method >>> lowered = messy.lower() >>> lowered '|home|paul|website|index.html' # Replace | symbols with / >>> slashed = lowered.replace('|', '/') >>> slashed '/home/paul/website/index.html' # See if the file exists >>> os.path.exists(slashed) True # Find the size of the file >>> os.path.getsize(slashed) 5150 # pun intended

Yay! We made it to the finish line. Now you've seen all 30 functions in the os.path module.

To accomplish this, we used the lower() method for string objects first to transform it to lowercase. Second we used the replace() method to change pipes (|) to forward slashes (/). Next, we tested to see if the filename exists using the os.path.exists() function. Finally, we printed out the size using the os.path.getsize() function.

Thank you for stiking with it, as you can see the os.path offers a lot of useful functionality, but can be tedious.

5. Find Local Help on Python os.path

To access local help on the Python os.path module type help('os.path') at the Python Interpreter. Output for Python 3.5.3 looks like this.

Help on module posixpath in os: NAME posixpath - Common operations on Posix pathnames. MODULE REFERENCE https://docs.python.org/3.5/library/posixpath The following documentation is automatically generated from the Python source file. It may be incomplete, incorrect or include features that are considered implementation detail and may vary between Python implementations. When in doubt, consult the module reference at the location listed above. DESCRIPTION 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 others (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). (Remaining lines trimmed)

It includes an important message about file locations across Linux macOS and Windows computers because differences exist in case sensitivity and directory forward slashes (/) and backward slashes (\\).

Summary

In the end, the os.path module offers 30 convenient functions to handle the filesystem using Python. It and other modules in the os and io modules are important components of The Python Standard Libary for everyone to learn.

Keep a bookmark pointed here for reminders because there isn't a lot of public information on the os.path module at this level of detail. I hope it was a helpful exploration.


Related Python Content


What's Next?

Subscribe to our growing YouTube Channel, a companion to this free online educational website. Hop on the no-spam email list for reminders.

Outline Back Tip Next

/ factorpad.com / tech / python / reference / python-os-path.html


python os path
python os
python filesystem
os path join
os path
python file exists
python check if file exists
python isfile
python isdir
python directory exists
python splitext
python exists
python test if file exists
python does file exist
python os examples
python os path exists
python abspath
python split path
python os path module
python basename
python os command
dirname python
FactorPad tutorials

A newly-updated free resource. Connect and refer a friend today.