# 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)