---
title: PhotoStructure's advanced settings
url: https://photostructure.com/getting-started/advanced-settings/
description: How to view and edit PhotoStructure's advanced settings.
date: 2020-06-30
keywords: library, settings
---


PhotoStructure's settings page is simple and only offers a handful of
configuration options.

There are _many_ configurable settings within PhotoStructure, though,
including:

- how "nice" PhotoStructure is with your system's CPU: should it auto-pause
  imports if CPU exceeds 75% (which is the default), or is it running on a
  server, and can use 100% of the CPU?

- is it OK to send [error reports](/faq/error-reports/)? (this defaults to true,
  but you can opt-out of sending error reports via this setting)

- what [filters are enabled to allow or reject files from being imported into
  your library](/faq/why-is-my-file-missing/)?

- what sizes of preview images should be generated during import?

- should we [transcode
  videos](/getting-started/how-much-disk-space-do-i-need-for-my-photostructure-library/#how-can-i-minimize-the-disk-space-that-photostructure-uses)
  on import?

<a id="omg-why-2"></a>

## 👥 Twice the fun with TWO settings files

Note that PhotoStructure has **two settings files**:

1. "system settings," and
2. "library settings."

Breaking out the settings into two files is somewhat inconvenient, and certainly
unconventional, but it allows for [PhotoStructure libraries](/faq/library/) to
be portable across computers by keeping library-specific settings with the
library, and system-specific settings on each computer.

## System settings

**System settings are specific to a computer.** Examples include what paths to
scan, where to save logfiles, and what percent of the CPU can be used during
imports.

The **system settings** will be found in your PhotoStructure application
settings directory.

- Linux: `~/.config/PhotoStructure/settings.toml`
- macOS: `~/Library/Application Support/PhotoStructure/settings.toml`
- Windows: `%APPDATA%\PhotoStructure\settings.toml`
- Docker: your bind-mount for `/ps/config/settings.toml`

## Library settings

**Library settings are specific to your library.** Most settings are library
settings. Examples include what preview image sizes to create, what pattern to
use for automatic organization, and what taggers should be enabled during
imports.

The **library settings** will be found in
(your library directory)`/.photostructure/settings.toml`. Note that the
`.photostructure` directory in your library will be hidden. If you don't see
this directory:

- On macOS, hold down <key>⌘</key> and <key>shift</key> then touch <key>.</key>
  (the period key).

- On Windows, click File > "Change folder and search options". Select the View
  tab. In Advanced Settings > Hidden files and folders, select "Show hidden
  files, folders, and drives". Click OK.

- On Ubuntu, click the hamburger menu in the titlebar and select "Show Hidden
  Files".

## Editing TOML

The settings files are formatted as [TOML](https://github.com/toml-lang/toml),
but you only need to know a couple things:

- Lines that start with a `#` are comments, and ignored

- Every OS has a text editor that can edit these files. TextEdit on macOS and
  Notepad on Windows work just fine, but make sure you overwrite
  `settings.toml`: if you write to `settings.toml.txt`, that will be ignored.

- Most settings have reasonable defaults, which are provided after the
  description. Remove the `#` from the beginning of the line with the default
  to override.

- The order of settings doesn't matter.

So, for example, to change the `logWebRequests` system setting to `true`, change
this:

```toml
# Write an access log for all web requests?
#
# logWebRequests = false
```

to this (note the "# " has been deleted, and "false" was changed to "true"):

```toml
# Write an access log for all web requests?
#
logWebRequests = true
```

<a id="all"></a>

## I haven't installed PhotoStructure yet. What are all the settings I can play with?

[A complete list is
here](https://github.com/photostructure/photostructure-for-servers/blob/main/defaults.env).

If you are testing an alpha or beta build, switch to the `alpha` or `beta`
branch to make sure you're looking at the correct defaults.

Know that there are a _lot_ of settings! We've attempted to pick defaults that
will work for most people: basically if there's been a heuristic or judgement
call, it's been shoved into settings rather than hard-coding the value. There
won't be a surprise test on any of this, next Tuesday, _honest_.

If you find any values whose default values don't work for you, please tell us
via chat, email, or reddit: we want PhotoStructure to "just work" for most
people!

## If PhotoStructure writes settings only _after_ I start, how do I configure things beforehand?

Many settings impact what photos and videos are imported into your library, and
how they are imported (like disabling video transcoding, for example).

### Solution 1: Use `PS_START_PAUSED`

You can "pause" PhotoStructure's initial import by setting the `PS_START_PAUSED`
environment variable to `true` ([see instructions here for how to set
environment variables on your
platform](/faq/environment-variables/#how-to-set-environment-variables)).

1. Set the environment variable
2. Install and launch PhotoStructure
3. Fill out the initial welcome page
4. Click start, and then [quit PhotoStructure](/faq/how-to-start-and-stop-photostructure/)
5. Edit the system or library settings to taste. Remember to save your changes.
6. Un-set `PS_START_PAUSED` (or set it to `false`)
7. Restart PhotoStructure

### Solution 2: Use environment variable overrides

All settings can be overridden with [environment
variables](/faq/environment-variables): just set them before starting
PhotoStructure, and your overridden values will be used instead of
PhotoStructure's defaults.

### Solution 3: Use "rebuild"

If you already installed and started playing with PhotoStructure, but found that
there's several settings you want to change, _don't panic_, just:

1. Shut down PhotoStructure
2. Edit the system or library settings to taste. Remember to save your changes.
3. Restart PhotoStructure
4. From the navigation menu, select "Rebuild".

This can take a while, depending on the size of your library.

<a id="duration"></a>

## ⏱️ Duration settings

**This section only applies to PhotoStructure version 2.1 and later!**

Prior versions of PhotoStructure required duration settings to be set in
milliseconds, but it's hard (at least for me) to see `3600000` and see an
hour--my eyes go wobbly after the fourth zero.

Version 2.1 supports friendlier values for these duration settings, like
`statTimeoutMs`, which all end with "Ms" (short for **M**illi**s**econds).

Duration settings may now use any of the following formats:

### 1. Numeric values

These will always be interpreted to be in milliseconds:

- `60000` is 1 minute
- `1200000` is 20 minutes
- `3600000` is 1 hour
- `86400000` is 1 day

### 2. ISO 8601 duration strings

The [ISO 8601 duration
standard](https://en.wikipedia.org/wiki/ISO_8601#Durations) is a bit ungainly,
but at least it's a standard:

- `PT1M` is 1 minute
- `PT20M` is 20 minutes
- `PT1H` is 1 hour
- `P1D` is 1 day
- `p4dt5h6m7.890s` is 4 days, 5 hours, 6 minutes, 7 seconds, and 890 milliseconds.

### 3. Friendly duration strings

This duration format is `([value] [unit])*`, where "value" is numeric, and
"unit" is one of

- `years`, `year`, or `y`
- `weeks`, `week`, or `w`
- `days`, `day`, or `d`
- `hours`, `hour`, or `h`
- `minutes`, `minute`, or `m`
- `seconds`, `second`, or `s`
- `milliseconds`, `millisecond`, `ms`, or just omit the unit.

Note:

- Casing doesn't matter--`Years`, `YEARS`, `years`, `Y`, and `y` are all equivalent.
- Use whatever unit variant you'd like--the long and short versions (`hours` vs `hour` vs `h`) are all equivalent.
- Note that there isn't a "month" unit: `m` means minutes.
- Fractional values are supported, but only by using "." as a decimal separator (like `2.5 days`).
- Whitespace and commas around values and units are ignored.

So, for the above examples:

- `1m` or `1 minute` is 1 minute
- `20m` or `20 minutes` is 20 minutes
- `1h` or `1 hour` is 1 hour
- `1d` or `1 day` is 1 day
- `4d5h6m7s890`, `4d 5h 6m 7s 890ms`, or `4 days, 5 hours, 6 minutes, 7.890 seconds` is 4 days, 5 hours, 6 minutes, 7 seconds, and 890 milliseconds.

### How PhotoStructure parses durations

PhotoStructure will first attempt to parse duration settings values as
numeric, then as ISO 8601, then as a friendly duration string.

PhotoStructure stores durations using friendly duration strings.

## A couple things to note

- **PhotoStructure should be shut down before you edit settings**.

- The settings files will only exist on your system after you've installed
  PhotoStructure and clicked "Start" on the welcome page.

- If you'd like to see a comprehensive list of settings, see [here](#all).

## Automatic upgrades

New versions of PhotoStructure frequently add new system or library settings.

- PhotoStructure upgrades your `settings.toml` files automatically.

- Prior settings files are archived in a backup directory.

- Custom values are retained, but any comments you may have added will not be
  preserved.

## See also

- [Using environment variables with PhotoStructure](/guide/environment-variables/)