How to give a project its own settings

This guide shows how to pin a theme and turn on automatic saving for one project, so everyone who opens it gets the same editor. It assumes you already have Turbo Python installed.

Create the settings file

Start the editor from the project's own directory, then choose Options ▸ Create project settings.

That writes .turbo-python/settings.toml, filled in with the theme you are using right now, and opens it for editing — coloured, because Turbo Python colours TOML:

# turbo-python project settings.
#
# These apply to everyone who opens this project in turbo-python. Delete this file
# and the editor falls back to its own defaults.

[editor]

# The colour theme to start in. `turbo-python -list-themes` lists them all.
# A -theme flag on the command line overrides this.
theme = "turbo-classic"

# Write modified files by themselves, a short while after you stop typing.
# On, because a project that has gone to the trouble of having a settings file
# has said what it wants; set it to false and save, and it stops at once.
autosave = true

# How long that while is. Any Go duration: "500ms", "2s", "1m".
autosave_delay = "2s"

The file is read when the editor starts, and again every time you save it — so a change is in force the moment you press F2. The status bar confirms it: Applied .turbo-python/settings.toml — autosave on (2s).

That covers the settings this file holds, not the theme: Options ▸ Theme is the live way to change that, and writes your choice back here for you.

The menu item you just used is now greyed out, and Options ▸ Project settings… beside it is not. That is the rule for all three of the project's files: you can create the one you have not got, and open the one you have.

Automatic saving

It is already on: the file you were just given says autosave = true.

Any file with a name is written two seconds after you stop typing. The status bar says Saved main.py when it happens. Nothing is written while you are still typing — each keystroke pushes the wait out again.

Two things change as a consequence, both on purpose:

Closing a window stops asking whether to save. It was going to be saved anyway.
Leaving the editor stops asking too, for the same reason.

A file that has never been named is the exception: automatic saving never opens a dialog, so an untitled window keeps its * and is still asked about when you close it.

To turn it off, set autosave to false and save; the status bar answers autosave off, and it stops there and then. To wait longer or less, change autosave_delay:

autosave_delay = "500ms"

Pin the theme

Set theme to any name from turbo-python -list-themes, or simply pick one with Options ▸ Theme — with a settings file present, choosing a theme writes it into the file for you, keeping your comments and layout as they were.

Try a different theme without changing the file

Pass -theme on the command line. It wins over the project's choice for that run only:

turbo-python -theme turbo-dark main.py

Edit the file later

Options ▸ Project settings… opens it again. It is greyed out in a project that has none.

Variants

You start the editor from a subdirectory. The settings are not found: only ./.turbo-python is looked at, with no walk up towards the project root. Start from the project's own directory, or pass -theme for that run.
The file has a mistake in it. The editor says so on standard error and opens with its defaults, so you can fix the file in the editor itself.
You share the project. .turbo-python/settings.toml is an ordinary file; commit it to agree on a theme across a team, or add it to .gitignore to keep it to yourself.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83


# How to give a project its own settings

This guide shows how to pin a theme and turn on automatic saving for one project, so everyone who opens it gets the same editor. It assumes you already have Turbo Python installed.

## Create the settings file

Start the editor **from the project's own directory**, then choose **Options ▸ Create project settings**.

That writes `.turbo-python/settings.toml`, filled in with the theme you are using right now, and opens it for editing — coloured, because Turbo Python colours TOML:

```toml
# turbo-python project settings.
#
# These apply to everyone who opens this project in turbo-python. Delete this file
# and the editor falls back to its own defaults.

[editor]

# The colour theme to start in. `turbo-python -list-themes` lists them all.
# A -theme flag on the command line overrides this.
theme = "turbo-classic"

# Write modified files by themselves, a short while after you stop typing.
# On, because a project that has gone to the trouble of having a settings file
# has said what it wants; set it to false and save, and it stops at once.
autosave = true

# How long that while is. Any Go duration: "500ms", "2s", "1m".
autosave_delay = "2s"
```

The file is read when the editor starts, and **again every time you save it** — so a change is in force the moment you press `F2`. The status bar confirms it: `Applied .turbo-python/settings.toml — autosave on (2s)`.

That covers the settings this file holds, not the theme: **Options ▸ Theme** is the live way to change that, and writes your choice back here for you.

The menu item you just used is now greyed out, and **Options ▸ Project settings…** beside it is not. That is the rule for all three of the project's files: you can create the one you have not got, and open the one you have.

## Automatic saving

It is already on: the file you were just given says `autosave = true`.

Any file with a name is written two seconds after you stop typing. The status bar says `Saved main.py` when it happens. Nothing is written while you are still typing — each keystroke pushes the wait out again.

Two things change as a consequence, both on purpose:

- **Closing a window stops asking** whether to save. It was going to be saved anyway.
- **Leaving the editor stops asking** too, for the same reason.

A file that has never been named is the exception: automatic saving never opens a dialog, so an untitled window keeps its `*` and is still asked about when you close it.

To turn it off, set `autosave` to `false` and save; the status bar answers `autosave off`, and it stops there and then. To wait longer or less, change `autosave_delay`:

```toml
autosave_delay = "500ms"
```

## Pin the theme

Set `theme` to any name from `turbo-python -list-themes`, or simply pick one with **Options ▸ Theme** — with a settings file present, choosing a theme writes it into the file for you, keeping your comments and layout as they were.

## Try a different theme without changing the file

Pass `-theme` on the command line. It wins over the project's choice for that run only:

```bash
turbo-python -theme turbo-dark main.py
```

## Edit the file later

**Options ▸ Project settings…** opens it again. It is greyed out in a project that has none.

## Variants

- **You start the editor from a subdirectory.** The settings are not found: only `./.turbo-python` is looked at, with no walk up towards the project root. Start from the project's own directory, or pass `-theme` for that run.
- **The file has a mistake in it.** The editor says so on standard error and opens with its defaults, so you can fix the file in the editor itself.
- **You share the project.** `.turbo-python/settings.toml` is an ordinary file; commit it to agree on a theme across a team, or add it to `.gitignore` to keep it to yourself.

## See also

- Every key, with its type and default: [Project settings reference](../reference/project-settings.md)
- Why the file is not searched for in parent directories, and why autosave waits: [Project settings](../explanation/project-settings.md)
- Writing a theme to pin: [How to write your own theme](write-a-theme.md)