# Configuration

Mopidy has a lot of config values you can tweak, but you only need to change a few to get up and running. A complete `mopidy.conf` may be as simple as:

    [mpd]
    hostname = ::

    [scrobbler]
    username = alice
    password = mysecret

## Configuration file location

The configuration file location depends on how you run Mopidy. See either Running in a terminal and Running as a service to find where the configuration file is located on your system.

## Editing the configuration

When you have created the configuration file, open it in a text editor, and add the config values you want to change.

If you want to keep the default value for a config value, you should not add it to the config file, but leave it out so that when we change the default value in a future version, you won’t have to change your configuration accordingly.

## View effective configuration

To see what’s the effective configuration for your Mopidy installation, you can run the `config` subcommand.

If you run Mopidy manually in a terminal, run:

    mopidy config

If you run Mopidy as a system service, run:

    sudo mopidyctl config

This will print your full effective config with passwords masked out so that you safely can share the output with others for debugging.

## Core configuration

You can find a description of all config values belonging to Mopidy’s core below.

This is the default configuration for Mopidy itself:

    [core]
    cache_dir = $XDG_CACHE_DIR/mopidy
    config_dir = $XDG_CONFIG_DIR/mopidy
    data_dir = $XDG_DATA_DIR/mopidy
    max_tracklist_length = 10000
    restore_state = false

    [logging]
    verbosity = 0
    format = %(levelname)-8s %(asctime)s [%(process)d:%(threadName)s] %(name)s\n  %(message)s
    color = true
    config_file =

    [audio]
    mixer = software
    mixer_volume =
    output = autoaudiosink
    buffer_time =

    [proxy]
    scheme =
    hostname =
    port =
    username =
    password =

### Core section

core/cache_dir

  Path to base directory for storing cached data.

  Mopidy and extensions will use this path to cache data that can safely be thrown away.

  If your system is running from an SD card, it can help avoid wear and corruption of your SD card by pointing this config to another location. If you have enough RAM, a tmpfs might be a good choice.

  When running Mopidy as a regular user, this should usually be `$XDG_CACHE_DIR/mopidy`, i.e. `~/.cache/mopidy`.

  When running Mopidy as a system service, this should usually be `/var/cache/mopidy`.

core/config_dir

  Path to base directory for config files.

  When running Mopidy as a regular user, this should usually be `$XDG_CONFIG_DIR/mopidy`, i.e. `~/.config/mopidy`.

  When running Mopidy as a system service, this should usually be `/etc/mopidy`.

core/data_dir

  Path to base directory for persistent data files.

  Mopidy and extensions will use this path to store data that cannot be be thrown away and reproduced without some effort. Examples include Mopidy-Local’s index of your media library and Mopidy-M3U’s stored playlists.

  When running Mopidy as a regular user, this should usually be `$XDG_DATA_DIR/mopidy`, i.e. `~/.local/share/mopidy`.

  When running Mopidy as a system service, this should usually be `/var/lib/mopidy`.

core/max_tracklist_length

  Max length of the tracklist. Defaults to 10000.

  The original MPD server only supports 10000 tracks in the tracklist. Some MPD clients will crash if this limit is exceeded.

core/restore_state

  When set to `true`, Mopidy restores its last state when started. The restored state includes the tracklist, playback history, the playback state, the volume, and mute state.

  Default is `false`.

### Audio section

These are the available audio configurations. For specific use cases, see Audio sinks.

audio/mixer

  Audio mixer to use.

  The default is `software`, which does volume control inside Mopidy before the audio is sent to the audio output. This mixer does not affect the volume of any other audio playback on the system. It is the only mixer that will affect the audio volume if you’re streaming the audio from Mopidy through Shoutcast.

  If you want to disable audio mixing set the value to `none`.

  If you want to use a hardware mixer, you need to install a Mopidy extension which integrates with your sound subsystem. E.g. for ALSA, install Mopidy-ALSAMixer.

audio/mixer_volume

  Initial volume for the audio mixer.

  Expects an integer between 0 and 100.

  Setting the config value to blank leaves the audio mixer volume unchanged. For the software mixer blank means 100.

audio/output

  Audio output to use.

  Expects a GStreamer sink. Typical values are `autoaudiosink`, `alsasink`, `osssink`, `oss4sink`, `pulsesink`, and `shout2send`, and additional arguments specific to each sink. You can use the command `gst-inspect-1.0` to see what output properties can be set on the sink. For example: `gst-inspect-1.0 shout2send`

audio/buffer_time

  Buffer size in milliseconds.

  Expects an integer above 0.

  Sets the buffer size of the GStreamer queue. If you experience buffering before track changes, it may help to increase this, possibly by at least a few seconds. The default is letting GStreamer decide the size, which at the time of this writing is 1000.

### Logging section

logging/verbosity

  Controls the detail level of the logging.

  Ranges from `-1` to `4`. Defaults to `0`. Higher value is more verbose.

  - `-1` is equivalent to mopidy -q.

  - `0` is equivalent to mopidy.

  - `1` is equivalent to mopidy -v.

  - `2` is equivalent to mopidy -vv.

  - `3` is equivalent to mopidy -vvv.

  - `4` is equivalent to mopidy -vvvv.

logging/color

  Whether or not to colorize the console log based on log level. Defaults to `true`.

logging/format

  The message format used for logging.

  See the Python logging docs for details on the format.

logging/config_file

  Config file that overrides all logging config values, see the Python logging docs for details.

loglevels/*

  The `loglevels` config section can be used to change the log level for specific parts of Mopidy during development or debugging. Each key in the config section should match the name of a logger. The value is the log level to use for that logger, one of `trace`, `debug`, `info`, `warning`, `error`, or `critical`.

logcolors/*

  The `logcolors` config section can be used to change the log color for specific parts of Mopidy during development or debugging. Each key in the config section should match the name of a logger. The value is the color to use for that logger, one of `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` or `white`.

### Proxy section

Not all parts of Mopidy or all Mopidy extensions respect the proxy server configuration when connecting to the Internet. Currently, this is at least used when Mopidy’s audio subsystem reads media directly from the network, like when listening to Internet radio streams, and by the Mopidy-Spotify extension. With time, we hope that more of the Mopidy ecosystem will respect these configurations to help users on locked down networks.

proxy/scheme

  URI scheme for the proxy server. Typically `http`, `https`, `socks4`, or `socks5`.

proxy/hostname

  Hostname of the proxy server.

proxy/port

  Port number of the proxy server.

proxy/username

  Username for the proxy server, if needed.

proxy/password

  Password for the proxy server, if needed.

## Extension configuration

Each installed Mopidy extension adds its own configuration section to `mopidy.conf`, with one or more config values that you may want to tweak. For an overview of the available config values, please refer to the documentation for each extension. Most extensions can be found in the Mopidy extension registry.

Mopidy extensions are enabled by default when they are installed. If you want to disable an extension without uninstalling it, all extensions support the `enabled` config value even if it isn’t explicitly documented by all extensions. If the `enabled` config value is set to `false` the extension will not be started. For example, to disable the MPD extension, add the following to your `mopidy.conf`:

    [mpd]
    enabled = false

## Adding new configuration values

Mopidy’s config validator will validate all of its own config sections and the config sections belonging to any installed extension. It will raise an error if you add any config values in your config file that Mopidy doesn’t know about. This may sound obnoxious, but it helps us detect typos in your config, and to warn about deprecated config values that should be removed or updated.

If you’re extending Mopidy, and want to use Mopidy’s configuration system, you can add new sections to the config without triggering the config validator. We recommend that you choose a good and unique name for the config section so that multiple extensions to Mopidy can be used at the same time without any danger of naming collisions.