Thefuck Settings File Location: Default Path and Configuration Guide

The default thefuck settings file location is ~/.config/thefuck/settings.py, determined by the XDG Base Directory Specification with fallback to ~/.config when $XDG_CONFIG_HOME is unset.

The thefuck command-line tool by nvbn/thefuck stores user-specific configurations in a Python settings file that is automatically generated on first run. Understanding the default location and initialization logic is essential for customizing rules, modifying delay settings, or troubleshooting configuration issues.

Default Location for the Thefuck Settings File

By default, thefuck creates its configuration directory at $XDG_CONFIG_HOME/thefuck, where the environment variable $XDG_CONFIG_HOME defaults to ~/.config if undefined. The actual settings file is settings.py inside this directory.

Consequently, the standard absolute path is:

~/.config/thefuck/settings.py

According to the source code in thefuck/conf.py, the Settings class determines this path through the _get_user_dir_path() method, which implements the XDG Base Directory logic with appropriate fallbacks.

How Thefuck Determines the Configuration Directory

XDG Base Directory Specification

Thefuck follows the XDG Base Directory Specification to ensure cross-platform consistency. In thefuck/conf.py, the _get_user_dir_path() method checks for the XDG_CONFIG_HOME environment variable:

• If XDG_CONFIG_HOME is set, the configuration directory becomes $XDG_CONFIG_HOME/thefuck
• If unset, it falls back to ~/.config/thefuck

The settings file itself is initialized by _init_settings_file(), which creates settings.py using self.user_dir.joinpath('settings.py').

Legacy Directory Handling

For backward compatibility, thefuck checks for a legacy configuration directory at ~/.thefuck. If this directory exists, the tool uses it instead of the XDG-compliant location and emits a deprecation warning. This logic is implemented in thefuck/conf.py lines 60-64, ensuring existing users are not broken while encouraging migration to the standard location.

Locating and Initializing the Settings File Programmatically

You can inspect the default location programmatically using thefuck's internal configuration classes:

from thefuck.conf import Settings
from thefuck import const

s = Settings(const.DEFAULT_SETTINGS)
s._setup_user_dir()          # creates the user dir if needed

print(s.user_dir)            # → Path('~/.config/thefuck')

print(s.user_dir / 'settings.py')   # → Path('~/.config/thefuck/settings.py')

To manually initialize the configuration file if it does not exist:

mkdir -p "$(thefuck --print-config-dir)"   # creates ~/.config/thefuck

thefuck --init                              # generates the default settings.py

The --print-config-dir flag internally uses the same _get_user_dir_path() logic to determine the correct location.

Customizing the Thefuck Settings Location

You can override the default location by setting the XDG_CONFIG_HOME environment variable before running thefuck:

export XDG_CONFIG_HOME=$HOME/.myconfig   # custom base

thefuck --version                         # will now read ~/.myconfig/thefuck/settings.py

This approach respects the XDG specification while allowing you to centralize configuration files in alternative locations such as $HOME/.dotfiles or version-controlled directories.

Summary

• The default thefuck settings file location is ~/.config/thefuck/settings.py, following the XDG Base Directory Specification.
• The path is determined by Settings._get_user_dir_path() in thefuck/conf.py, with fallback logic for the XDG_CONFIG_HOME environment variable.
• Legacy installations may use ~/.thefuck instead, though this triggers a deprecation warning.
• You can programmatically locate the directory using thefuck --print-config-dir or the Settings class API.

Frequently Asked Questions

Where is the thefuck settings file stored by default?

By default, thefuck stores its settings file at ~/.config/thefuck/settings.py. This location follows the XDG Base Directory Specification, using $XDG_CONFIG_HOME/thefuck when the environment variable is set, or falling back to ~/.config/thefuck otherwise.

Can I move the thefuck config file to a different directory?

Yes, you can change the configuration directory by setting the XDG_CONFIG_HOME environment variable to your preferred base path. Thefuck will then create and use $XDG_CONFIG_HOME/thefuck/settings.py instead of the default location.

What happens if I have an old ~/.thefuck directory?

If the legacy directory ~/.thefuck exists, thefuck will use it for backward compatibility and emit a deprecation warning advising you to migrate to the XDG-compliant location at ~/.config/thefuck. The tool prioritizes the legacy path only when it already exists on your system.

How do I programmatically find the thefuck config path in Python?

You can import the Settings class from thefuck.conf and instantiate it with const.DEFAULT_SETTINGS. Calling _setup_user_dir() initializes the directory, after which settings.user_dir contains the Path object pointing to the configuration directory, and settings.user_dir / 'settings.py' points to the actual settings file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}