# Where Are thefuck Settings Managed? A Deep Dive into the Configuration System

> Discover where thefuck settings are managed Explore conf.py user config files environment variables and command line arguments to customize your experience.

- Repository: [Vladimir Iakovlev/thefuck](https://github.com/nvbn/thefuck)
- Tags: deep-dive
- Published: 2026-02-27

---

**Thefuck settings are managed through a hierarchical system centered in [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py), which loads configuration from user config files, environment variables, and command-line arguments into a global `Settings` instance.**

Thefuck, the popular Python command-line correction tool, uses a flexible, multi-layered configuration system that allows users to customize behavior through files, environment variables, or runtime flags. Understanding where these thefuck settings are stored and how they are prioritized is essential for advanced customization and debugging. According to the nvbn/thefuck source code, all configuration flows through the `Settings` class in [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py).

## The Core Settings Architecture

### The Settings Class in conf.py

The configuration system revolves around the `Settings` class defined in **[`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py)**. This class extends Python's built-in `dict` to provide attribute-style access (e.g., `settings.rules`, `settings.debug`).

At line 40 of [`conf.py`](https://github.com/nvbn/thefuck/blob/main/conf.py), the module initializes a global instance named `settings` that the entire application imports and uses:

```python
from thefuck.conf import settings

# Access any configuration value as an attribute

if settings.debug:
    print("Debug mode enabled")

```

The `Settings.init()` method populates this dictionary through three successive loading steps, with each layer overriding the previous one.

## The Three-Layer Configuration Hierarchy

Thefuck applies settings in a specific priority order: command-line arguments override environment variables, which override user config files, which override default values.

### Layer 1: User Configuration File

The primary location for persistent thefuck settings is the user config file at **`~/.config/thefuck/settings.py`** (with fallback support for the legacy path `~/.thefuck/settings.py`).

When the program starts, the `_init_settings_file()` function (lines 46-53) checks for this file and generates a default template with comments if it does not exist. The `_settings_from_file()` function (lines 77-84) then loads the file using `importlib` or `imp` to execute the Python code and extract variables.

Example user configuration file:

```python

# ~/.config/thefuck/settings.py

rules = ['git_push', 'sudo', 'python_command']
require_confirmation = False
wait_command = 2
debug = True

```

### Layer 2: Environment Variables (THEFUCK_*)

Environment variables prefixed with **`THEFUCK_`** provide a method for per-session configuration overrides. The `_settings_from_env()` method (lines 19-24) iterates over the `const.ENV_TO_ATTR` mapping to identify relevant variables.

The conversion logic in `_val_from_env()` (lines 101-118) automatically casts values to appropriate Python types: colon-separated strings become lists, "true"/"false" become booleans, and numeric strings become integers.

```bash

# Override rules list (colon-separated)

export THEFUCK_RULES='git_push:cd_parent:no_sudo'

# Enable debug mode (boolean conversion)

export THEFUCK_DEBUG=true

# Change wait time (integer conversion)

export THEFUCK_WAIT_COMMAND=5

```

### Layer 3: Command-Line Arguments

Runtime flags passed to thefuck take highest priority. The [`argument_parser.py`](https://github.com/nvbn/thefuck/blob/main/argument_parser.py) module defines CLI flags that map directly to settings attributes. The `_settings_from_args()` method (lines 25-37) inspects the parsed `argparse.Namespace` and applies these values to the global settings object.

```bash

# Disable confirmation prompt and enable debug output for this invocation only

thefuck --no-confirmation --debug

```

## Default Settings and Constants

All default values for thefuck settings reside in **[`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py)**. The `DEFAULT_SETTINGS` dictionary (beginning at line 31) defines factory defaults for every configurable option, including `rules`, `priority`, `debug`, `wait_command`, and `require_confirmation`.

The same file defines `ENV_TO_ATTR` (lines 49-63), which maps environment variable names to their corresponding settings attributes and specifies type conversion rules. This mapping ensures that `THEFUCK_RULES` correctly populates `settings.rules` as a list, while `THEFUCK_WAIT_COMMAND` populates `settings.wait_command` as an integer.

## Practical Configuration Examples

### Editing the User Config File

Create or modify `~/.config/thefuck/settings.py` to apply permanent customizations:

```python

# Require explicit confirmation before running corrections

require_confirmation = True

# Only use specific rules

rules = ['git_push', 'apt_get', ' fix_file']

# Wait 3 seconds before executing the corrected command

wait_command = 3

```

### Using Environment Variables

Set variables before invoking the command for temporary overrides:

```bash
export THEFUCK_REQUIRE_CONFIRMATION=false
export THEFUCK_DEBUG=true
thefuck  # Runs with confirmation disabled and debug output enabled

```

### Accessing Settings Programmatically

Any module within thefuck or third-party extensions can import and read the global settings instance:

```python
from thefuck.conf import settings

def my_custom_rule(command):
    if settings.debug:
        print(f"Processing: {command}")
    
    # Access any configured value

    timeout = settings.wait_command
    return True

```

## Summary

- **Primary location**: The `Settings` class in [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py) manages all configuration through a global `settings` instance created at module load time.
- **Configuration files**: Persistent settings live in `~/.config/thefuck/settings.py` (XDG compliant) or the legacy `~/.thefuck/settings.py` path.
- **Environment overrides**: Variables prefixed with `THEFUCK_` override file settings using the mapping defined in [`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py).
- **Runtime flags**: Command-line arguments parsed in [`thefuck/argument_parser.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/argument_parser.py) take highest priority via `_settings_from_args()`.
- **Defaults**: All default values and type mappings reside in [`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py) within the `DEFAULT_SETTINGS` dictionary.

## Frequently Asked Questions

### Where is the thefuck settings file located?

Thefuck stores user configuration at `~/.config/thefuck/settings.py` by default, following the XDG Base Directory specification. If this directory does not exist, it falls back to the legacy path `~/.thefuck/settings.py`. The file is automatically generated with default values and comments on first run if it does not exist.

### How do I override thefuck settings temporarily?

Use environment variables prefixed with `THEFUCK_` to override settings for a single shell session. For example, `export THEFUCK_DEBUG=true` enables debug mode, while `export THEFUCK_RULES='git_push'` restricts which rules are active. These variables override config file values but are themselves overridden by command-line arguments.

### What is the priority order for thefuck configuration sources?

Thefuck applies configuration in the following priority order (lowest to highest): default values from [`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py), user configuration file ([`settings.py`](https://github.com/nvbn/thefuck/blob/main/settings.py)), environment variables (`THEFUCK_*`), and command-line arguments. This means CLI flags always take precedence, followed by environment variables, then file settings.

### How does thefuck convert environment variables to Python types?

The conversion logic in `_val_from_env()` (lines 101-118 of [`thefuck/conf.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/conf.py)) automatically detects types: strings containing colons are split into lists (e.g., `"a:b"` becomes `['a', 'b']`), "true"/"false" strings become booleans, and numeric strings become integers. This mapping is controlled by the `ENV_TO_ATTR` dictionary in [`thefuck/const.py`](https://github.com/nvbn/thefuck/blob/main/thefuck/const.py).