# Reference: project settings

> Neutral description of `.turbo-python/settings.toml`: where it is looked for, what it may contain, and what writes to it.

## Location

| Property | Value |
| --- | --- |
| Directory | `.turbo-python` in the editor's working directory |
| File | `.turbo-python/settings.toml` |
| Search | The working directory only. Parent directories are **not** searched. |
| Read | When the editor starts, and again whenever the file is saved from inside the editor |
| Required | No. A project without one gets the defaults below. |

## Keys

Every key is optional, and every key lives in the `[editor]` table. A key that is absent keeps its default; a key present with any value overrides it, including a value equal to the default.

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | string | the editor's own default (`turbo-classic`) | Name of the colour theme to start in, as listed by `turbo-python -list-themes` |
| `autosave` | boolean | `false` | Whether modified files are written without being asked. The file **Create project settings** writes sets it to `true`; the default here is what applies to a project with no settings file at all. |
| `autosave_delay` | string | `"2s"` | How long after the last keystroke to wait. A Go duration: `"500ms"`, `"2s"`, `"1m"`. Only consulted when `autosave` is true. |

### Example

```toml
[editor]
theme = "turbo-dark"
autosave = true
autosave_delay = "500ms"
```

## Theme precedence

Highest first:

| Source | Wins over |
| --- | --- |
| `-theme` on the command line | everything |
| `theme` in the settings file | the built-in default |
| The built-in default `turbo-classic` | — |

An unknown theme name at any level falls back to the built-in default rather than failing.

## When a change takes effect

The file is read at start-up, and **again every time it is saved from inside the editor** — so a change made in the editor is in force the moment you press `F2`, with no restart.

| Key | Re-applied on save | Why |
| --- | --- | --- |
| `autosave` | yes | |
| `autosave_delay` | yes | |
| `theme` | **no** | Options ▸ Theme is the live way to change it, and already writes the choice back here. A `-theme` flag given on the command line is the more explicit statement for that session and is not overridden by a file being saved. |

| Outcome | Status bar |
| --- | --- |
| Read and applied | `Applied .turbo-python/settings.toml — autosave on (2s)` |
| Read and applied, autosave off | `Applied .turbo-python/settings.toml — autosave off` |
| Saved, but no longer valid TOML | `Saved, but not applied: …` — the previous values stay in force |

Saving is saving, whoever did it: automatic saving writing the settings file re-applies them exactly as `F2` does. Editing the file **outside** the editor is not noticed; nothing watches it.

## Automatic saving

| Behaviour | Detail |
| --- | --- |
| Trigger | The delay elapsing with no edit in any window |
| Scope | Every open file with a name, not only the front one |
| Deadline | One for the whole editor, restarted by any edit in any window |
| Files with no name | Never saved; never asked about |
| Report | `Saved <name>` on the status bar |
| Failure | Reported on the status bar, never in a dialog, and not retried until the next edit |
| Closing a window | Saves instead of asking, when the file has a name |
| Leaving the editor | Saves instead of asking, when the file has a name |

## Writes

The settings file is written by exactly two actions. Nothing else in the editor writes to it, and nothing creates it by itself.

| Action | Effect |
| --- | --- |
| **Options ▸ Create project settings** | Creates `.turbo-python/settings.toml` with the theme in use, `autosave = true`, and explanatory comments. Greyed out once the project has one, so it cannot be chosen twice. |
| **Options ▸ Theme** | Rewrites the `theme` value **only when the file already exists**. Comments, blank lines, key order and any trailing comment on the theme line are kept. |

Both write through a temporary file in the same directory, renamed into place, so an interrupted write leaves the previous file intact.

## Menu items

| Item | Menu | Needs a file | Effect |
| --- | --- | --- | --- |
| Create project settings | Options | refuses the file | As above, then opens the file. Greyed out once the project has one. |
| Project settings… | Options | requires the file | Opens `.turbo-python/settings.toml`. Greyed out until the project has one. |

## Errors

| Message | Cause |
| --- | --- |
| `turbo-python: reading …/settings.toml: …` on standard error | The file is present but is not valid TOML. The editor opens with its defaults. |
| `reading …: autosave_delay "x" is not a duration such as "2s"` | `autosave_delay` is not a Go duration |
| `reading …: autosave_delay must be positive, not "0s"` | `autosave_delay` is zero or negative |
| `Already there: .turbo-python/settings.toml` on the status bar | Creating in a project that already has one. Unreachable from the menu, which greys the item out; still possible for a caller that is not a menu. |
| `Saved, but not applied: …` on the status bar | The settings file was written but no longer parses. The previous values stay in force. |
| `This project has no .turbo-python/settings.toml yet.` | **Project settings…** in a project that has none |
| `Theme set for this session only: …` | The theme changed but the settings file could not be written |

## See also

- [How to give a project its own settings](../how-to/configure-a-project.md)
- [Project settings](../explanation/project-settings.md)
- [Theme file format](themes.md) — a different file, in the same language