---
title: Using environment variables with PhotoStructure
url: https://photostructure.com/guide/environment-variables/
description: How to override PhotoStructure's settings via environment variables
date: 2020-09-11
keywords: environment-variables, settings, Docker, macOS, Windows, Linux
---


You can use [environment
variables](https://en.wikipedia.org/wiki/Environment_variable) to configure
[PhotoStructure's settings](/advanced-settings/). The
[`defaults.env`](https://github.com/photostructure/photostructure-for-servers/blob/main/defaults.env)
file describes all of PhotoStructure's settings, and how to change each with an
environment variable. This file will also be found in your root app directory
(from version 0.9.0 and later) if you're using a [PhotoStructure for
Servers](/servers/) edition.

- You can edit your `settings.toml` files **and** set environment variables.

- Environment variables **always override** any values found in `settings.toml`.

- As of [version 2.1](/about/2022-release-notes/#v210-alpha1) (due to be released soon), PhotoStructure will read from one or more files specified in your `PS_ENV_FILE` environment variable. See below for details.

## ⚠️ Environment variable overrides and settings.toml values don't mix

PhotoStructure does not write environment variables overrides to your
`settings.toml` files.

This is actually by design: previous versions of PhotoStructure didn't
discriminate between `settings.toml` values and environment variable overrides.
As an example, if you had set `PS_LOG_LEVEL=debug` and then saved your settings
via the web UI, that `debug` value would get persisted and become the new
default log level.

This behavior was surprising and confusing to most beta users. Thanks to the
[principle of least
astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment), we
decided that this was a "bug," not a "feature," and changed PhotoStructure to
keep environment variable overrides separated from values stored in the
`settings.toml` files.

## ✓ Boolean settings

Boolean settings interpret either `true` or `1` as `true`, and `false` or `0`
for `false`.

For example:

```
PS_VERIFY_FILE_COPIES=true
```

## 🔄 Converting between settings names and environment variable names

To avoid name-colliding with other software, all PhotoStructure environment
variables are prefixed with `PS_` and converted to `UPPER_SNAKE_CASE`.

### Examples

- The `PS_LOG_LEVEL` environment variable overrides the `logLevel`
  setting.

- The `PS_LIBRARY_PATH` environment variable overrides the `libraryPath`
  setting.

## ⚠️ Caution: upgrades to your environment variables are not automatic

When you upgrade to a new version of PhotoStructure, your prior `settings.toml`
files are automatically migrated to contain the settings (and defaults) of the
new version, while retaining your custom configurations.

**We cannot do this for environment variables** because we do not know where
your environment variables are coming from. They can be set in many different
ways.

If you use environment variables, you must review our [release
notes](/about/release-notes/) and make suitable settings changes when you
upgrade. We mark any settings that are deleted, renamed, or have changed
semantics.

It also might be helpful to look at differences between version tags [**on
github**](https://github.com/photostructure/photostructure-for-servers/blob/main/defaults.env).

## ⚙️ How to set environment variables per OS

### PhotoStructure for Desktops on macOS

If you're using PhotoStructure for Desktops on macOS, you can set environment variables with `launchctl setenv`.

To disable video transcoding, for example, open a terminal and run:

```sh
launchctl setenv PS_TRANSCODE_VIDEOS false
```

To get the current value, use `launchctl getenv`:

```sh
launchctl getenv PS_TRANSCODE_VIDEOS
```

To unset (and use PhotoStructure's default), use `launchctl unsetenv`:

```sh
launchctl unsetenv PS_TRANSCODE_VIDEOS
```

### PhotoStructure for Servers on Linux and macOS

Add environment variables to the relevant RC script for your shell. If you're using
[bash](<https://en.wikipedia.org/wiki/Bash_(Unix_shell)>), that's `~/.profile`:

```sh
export PS_LOG_LEVEL=info
```

### PhotoStructure on Windows

1. Hit the <key>Windows</key> key, and type "environment",
2. select "Edit the system environment variables" control panel,
3. click the `Environment Variables...` button in the bottom right, and
4. click the top `New...` button. Pick the top `New...` button if you're using PhotoStructure for Desktops. If you're running PhotoStructure as a system service, pick the bottom `New...` button.

### Docker

With [docker](/server/photostructure-for-docker/), use
[**`--env`**
](https://docs.docker.com/engine/reference/commandline/run/#options) or [**`--env-file`**
](https://docs.docker.com/engine/reference/commandline/run/#options):

```sh
docker run --name photostructure --env PS_LOG_LEVEL=info ...
```

With [Docker Compose](/server/docker-compose-wizard/), use the
[**`environment`**](https://docs.docker.com/compose/compose-file/compose-file-v2/#environment) or [**`env_file`**](https://docs.docker.com/compose/compose-file/compose-file-v2/#env_file)
configuration option

```sh
...
    environment:
      - "PS_LOG_LEVEL=info"
...
```

<a id="alternative-coming-in-v21-support-for-env-files"></a>
<a id="PS_ENV_FILE"></a>
<a id="PS_ENV"></a>
<a id="psenv"></a>

## 📄 Support for `.env` files

Version 2023 and later added support for reading `.env` files via the new `PS_ENV_FILE` environment variable.

On startup, PhotoStructure will attempt to read .env files from the following paths:

1. `/.psenv` (if exists and is readable)
2. `$HOME/.psenv` (if exists and is readable)
3. `$PS_ENV` (if set to a full pathname that is readable)
4. `$PS_ENV_FILE` (if set to a full pathname that is readable)

PhotoStructure reads from `$PSENV`, `$PS_ENV`, and `$PS_ENV_FILE` to accommodate typos.

Note that if the same key is defined in multiple `.env` files, the last defined value will "win."

### `.env` file format

PhotoStructure reads standard `.env`-formatted files.

- Any `#` outside of quotes is considered the start of a comment.
- Values should be wrapped in double-quotes.
- Newlines can be encoded as "\n", or as actual newlines in the text file.
- Save your .env as UTF8 without a BOM.

```sh
# This is a comment.
PS_LIBRARY_DIR="/path/to your/library"
PS_LOG_LEVEL="info"
# You can add backslash-n as a newline character like this
MULTI_LINE0="first line\nsecond line"
# Or if you prefer (but this is not valid shell):
MULTI_LINE1="this is
also a valid
multi line value"

```

Note that parameter expansion or other shell constructs, like conditionals, are not supported.

## See also

- [Advanced settings](/advanced-settings/)