Of course! QFileDialog is a fundamental and highly useful widget in PyQt and PySide. It provides a standardized dialog box that allows users to select files or directories for opening or saving.

Here's a comprehensive guide covering its most common use cases, from simple examples to best practices.

What is QFileDialog?

QFileDialog is a pre-built dialog that follows the platform's native look and feel (on Windows, macOS, and Linux). This ensures a familiar user experience. Its primary functions are:

• Opening a file: Letting the user choose one or more existing files to read.
• Saving a file: Letting the user choose a location and a name to save a new file.
• Selecting a directory: Letting the user choose a folder.

Basic Imports

First, you need to import the necessary classes. The examples below will use PyQt6, but the code is identical for PySide6 (just change the import from PyQt6 to PySide6).

import sys
from PyQt6.QtWidgets import (
    QApplication,
    QMainWindow,
    QPushButton,
    QVBoxLayout,
    QWidget,
    QLabel,
    QTextEdit,
)
from PyQt6.QtGui import QPixmap

Core Methods

QFileDialog is typically used as a static method (called directly on the class, like QFileDialog.getOpenFileName()), which simplifies usage immensely.

a) getOpenFileName(): Open a Single File

This is the most common method. It prompts the user to select a single file.

Syntax:

filename, _ = QFileDialog.getOpenFileName(
    parent,
    caption,
    directory,
    filter,
    selectedFilter,
    options
)

• parent: The widget that the dialog will be centered on (e.g., your main window). Pass None if you don't have a parent.
• caption: The text displayed in the title bar of the dialog.
• directory: The starting directory for the dialog (e.g., "C:/Users/YourUser/Documents" or for the current working directory).
• filter: A string that specifies which file types are shown. It has a specific format: "Description (*.ext1;*.ext2)".
• selectedFilter: (Optional) The filter that will be pre-selected when the dialog opens.
• options: (Optional) A combination of flags to modify the dialog's behavior (e.g., QFileDialog.Option.DontUseNativeDialog).
• Return Value: It returns a tuple: (selected_file_path, selected_filter_string). The second part is often discarded with an underscore (_).

Example:

def open_file_dialog(self):
    # The filter string format: "Name for filter (*.ext1;*.ext2)"
    options = QFileDialog.Option.ReadOnly
    filename, _ = QFileDialog.getOpenFileName(
        self,
        "Open a Text File",
        "",  # Start in the current directory
        "Text Files (*.txt);;All Files (*)",
        options=options
    )
    if filename:
        print(f"Selected file: {filename}")
        # You can now read the file's content
        try:
            with open(filename, 'r') as f:
                self.text_edit.setText(f.read())
        except Exception as e:
            self.text_edit.setText(f"Error opening file: {e}")

b) getOpenFileNames(): Open Multiple Files

This is identical to getOpenFileName but allows the user to select multiple files using Ctrl+Click or Shift+Click.

Syntax:

filenames, _ = QFileDialog.getOpenFileNames(...)

Return Value: It returns a list of file paths.

Example:

def open_multiple_files_dialog(self):
    filenames, _ = QFileDialog.getOpenFileNames(
        self,
        "Select Multiple Files",
        "",
        "Images (*.png *.jpg *.jpeg);;All Files (*)"
    )
    if filenames:
        print(f"Selected files: {filenames}")
        self.text_edit.clear()
        self.text_edit.append(f"Selected {len(filenames)} files:")
        for f in filenames:
            self.text_edit.append(f"- {f}")

c) getSaveFileName(): Save a File

This dialog is used to get a file path for saving. It will warn the user if the file already exists.

Syntax:

filename, _ = QFileDialog.getSaveFileName(...)

The parameters are the same as getOpenFileName.

Example:

def save_file_dialog(self):
    # The default filter can be used to suggest a file extension
    filename, _ = QFileDialog.getSaveFileName(
        self,
        "Save As",
        "",  # You can provide a default filename, e.g., "untitled.txt"
        "Text Files (*.txt);;All Files (*)"
    )
    if filename:
        print(f"File to be saved: {filename}")
        # You can now write content to the file
        try:
            with open(filename, 'w') as f:
                f.write(self.text_edit.toPlainText())
            self.statusBar().showMessage(f"File saved to {filename}", 3000)
        except Exception as e:
            self.statusBar().showMessage(f"Error saving file: {e}", 3000)

d) getExistingDirectory(): Select a Directory

This method opens a dialog specifically for selecting a folder.

Syntax:

directory = QFileDialog.getExistingDirectory(
    parent,
    caption,
    directory,
    options
)

Return Value: It returns a single string containing the path to the selected directory.

Example:

def select_directory_dialog(self):
    directory = QFileDialog.getExistingDirectory(
        self,
        "Select a Directory",
        "",  # Start in the current directory
        QFileDialog.Option.ShowDirsOnly
    )
    if directory:
        print(f"Selected directory: {directory}")
        self.text_edit.setText(f"Selected folder:\n{directory}")

Complete Working Example

Here is a full application demonstrating all the dialogs in a single window.

import sys
from PyQt6.QtWidgets import (
    QApplication, QMainWindow, QPushButton, QVBoxLayout, QWidget,
    QLabel, QTextEdit, QFileDialog, QMessageBox
)
from PyQt6.QtGui import QPixmap
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QFileDialog Demo")
        self.setGeometry(100, 100, 500, 400)
        # Central widget and layout
        central_widget = QWidget()
        self.setCentralWidget(central_widget)
        layout = QVBoxLayout(central_widget)
        # Widgets
        self.label = QLabel("No file selected.")
        self.text_edit = QTextEdit()
        self.text_edit.setPlaceholderText("File content will appear here...")
        # Buttons
        btn_open = QPushButton("Open Text File")
        btn_open.clicked.connect(self.open_file_dialog)
        btn_open_img = QPushButton("Open Image File")
        btn_open_img.clicked.connect(self.open_image_dialog)
        btn_save = QPushButton("Save Text File")
        btn_save.clicked.connect(self.save_file_dialog)
        btn_select_dir = QPushButton("Select Directory")
        btn_select_dir.clicked.connect(self.select_directory_dialog)
        # Add widgets to layout
        layout.addWidget(self.label)
        layout.addWidget(self.text_edit)
        layout.addWidget(btn_open)
        layout.addWidget(btn_open_img)
        layout.addWidget(btn_save)
        layout.addWidget(btn_select_dir)
    def open_file_dialog(self):
        options = QFileDialog.Option.ReadOnly
        filename, _ = QFileDialog.getOpenFileName(
            self, "Open a Text File", "", "Text Files (*.txt);;All Files (*)", options=options
        )
        if filename:
            self.label.setText(f"Selected file: {filename}")
            try:
                with open(filename, 'r') as f:
                    self.text_edit.setText(f.read())
            except Exception as e:
                QMessageBox.critical(self, "Error", f"Could not open file:\n{e}")
    def open_image_dialog(self):
        filename, _ = QFileDialog.getOpenFileName(
            self, "Open an Image", "", "Image Files (*.png *.jpg *.jpeg);;All Files (*)"
        )
        if filename:
            self.label.setText(f"Selected image: {filename}")
            pixmap = QPixmap(filename)
            # Scale the image to fit the text edit widget
            scaled_pixmap = pixmap.scaled(self.text_edit.size(), aspectRatioMode=1, transformMode=0)
            self.text_edit.setPixmap(scaled_pixmap)
    def save_file_dialog(self):
        filename, _ = QFileDialog.getSaveFileName(
            self, "Save As", "", "Text Files (*.txt);;All Files (*)"
        )
        if filename:
            try:
                with open(filename, 'w') as f:
                    f.write(self.text_edit.toPlainText())
                self.statusBar().showMessage(f"File saved to {filename}", 3000)
            except Exception as e:
                QMessageBox.critical(self, "Error", f"Could not save file:\n{e}")
    def select_directory_dialog(self):
        directory = QFileDialog.getExistingDirectory(
            self, "Select a Directory", "", QFileDialog.Option.ShowDirsOnly
        )
        if directory:
            self.label.setText(f"Selected directory: {directory}")
            self.text_edit.setText(f"Selected folder:\n{directory}")
if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec())

Best Practices and Tips

1. Always Check the Return Value: The user can click "Cancel". In that case, the dialog returns an empty string (). Always check if the returned filename or directory is not empty before proceeding.

2. Use with open(...): This is the standard Pythonic way to handle files. It automatically closes the file for you, even if errors occur.

3. Set a Sensible directory: Instead of always starting in (the current working directory), it's much better to start in a user-relevant location like the user's documents folder or the last opened file's directory.

   import os
   # Get the user's documents directory
   start_dir = os.path.expanduser("~/Documents")
   filename, _ = QFileDialog.getOpenFileName(self, "Open File", start_dir, ...)

4. Use QStatusBar for Feedback: Instead of print() or QMessageBox for simple success messages, use the statusBar() of your QMainWindow. It provides non-intrusive, temporary feedback to the user.

   self.statusBar().showMessage("File saved successfully!", 5000) # Message for 5 seconds

5. Advanced Usage: Non-Static Mode: For more complex scenarios, you can create a QFileDialog instance as a widget. This allows you to connect to its signals like fileSelected or directoryEntered for real-time updates as the user browses. However, for 95% of use cases, the static methods are sufficient and simpler.

   # Example of non-static mode
   dialog = QFileDialog(self)
   dialog.setFileMode(QFileDialog.FileMode.ExistingFiles)
   dialog.setNameFilter("Images (*.png *.jpg)")
   if dialog.exec():
       selected_files = dialog.selectedFiles()
       print("Files selected via signal:", selected_files)