Python os.startfile() Function

Python’s os.startfile() function asks Windows to open a file or directory with its associated application. Use it when a script should hand an item to the same program Windows would use when the user opens it from File Explorer. It starts an external application; it does not read the file into Python or wait for that application to finish.

How os.startfile() Works

The function delegates the path to the Windows shell. The shell uses the file association or directory handler configured on that computer, so the application that opens a document can vary between systems. A successful return means the launch request was initiated; it does not confirm that a person viewed or edited the item.

Syntax and Parameters

The call signature is os.startfile(path, operation=None, arguments=None, cwd=None, show_cmd=None). For the common case, pass only path as a string or path-like object. See the official Python documentation for os.startfile() for the signature and parameter details. The optional parameters are:

Leave options out unless the task needs them. In particular, an operation accepted for a document may not apply to a directory.

Return Value and Errors

os.startfile() returns None; it does not return a file object, process handle, or success flag. If Windows cannot start the requested item, Python reports an OSError subclass. A missing path commonly produces FileNotFoundError. Catch the specific error when your program can recover, and avoid treating a later print() as proof that an external application opened successfully.

Open a File or Directory

Run this example on Windows with Python:

import os
from pathlib import Path
from tempfile import NamedTemporaryFile

if os.name == "nt":
    with NamedTemporaryFile(mode="w", suffix=".txt", encoding="utf-8", delete=False) as file:
        file.write("A short note.")
        document = Path(file.name)
    os.startfile(document)
    directory = Path.home()
    os.startfile(directory)
else:
    print("os.startfile() is available on Windows only.")

os.startfile() is available on Windows only.

The example creates a temporary text file and passes it to the registered text handler, then passes the existing home directory to the shell. Change document and directory to the paths you want to open. The launch is asynchronous, so returning from os.startfile() does not prove that the associated application opened successfully. This example leaves its temporary file in place for the application to read; remove it when you no longer need it.

Handle a Missing Path

Use FileNotFoundError to handle a path that is absent. This standalone example only calls the Windows-specific function on Windows; the other branch explains why it cannot demonstrate the API there.

import os
from pathlib import Path
from tempfile import TemporaryDirectory

if os.name == "nt":
    with TemporaryDirectory() as folder:
        missing = Path(folder) / "not-created.txt"
        try:
            os.startfile(missing)
        except FileNotFoundError as error:
            print(type(error).__name__)
else:
    print("os.startfile() is available on Windows only.")

os.startfile() is available on Windows only.

A missing path is only one possible launch failure. Permissions, a missing file association, or another shell problem can also prevent Windows from starting the item; handle OSError more broadly if your application needs a fallback for those cases.

Choose an Operation

Pass a shell verb as the second argument when the default open action is not appropriate. For example, os.startfile(path, "edit") requests an edit action for a document, while os.startfile(path, "print") requests printing. For a directory, Windows may support verbs such as "explore" or "find". The verbs and their effects depend on the item’s registered shell handler, so do not assume every computer supports every action. If a requested verb is unavailable, the call can fail with an OSError.

Open a URL

For a web address, use Python’s webbrowser module, which is intended to open URLs in a browser. Supply a complete address, including its scheme. This standalone example asks the configured browser to open the URL:

import webbrowser

opened = webbrowser.open_new_tab("https://example.com")
print(opened)

open_new_tab() returns True when it can open a browser window, and False when it cannot. This return value describes the browser-launch request; it does not verify that the website exists or that the page loaded. Use normal network checks if your application must verify a website response.

Windows Support and Alternatives

os.startfile() is available only on Windows. On other systems, choose a platform-appropriate launcher or a library designed for your application. os.open() is not an equivalent: it is a low-level operating-system call that opens a file descriptor for reading or writing, rather than asking the desktop shell to launch the associated application. Use ordinary file APIs such as open() when Python needs to read or write file contents.