Upgrading from 1.0

Prior to version 1.1, beets used a completely different system for configuration. The config file was in “INI” syntax instead of YAML and the various files used by beets were (messily) stored in $HOME instead of a centralized beets directory. If you’re upgrading from version 1.0 or earlier, your configuration syntax (and paths) need to be updated to work with the latest version.

Fortunately, this should require very little effort on your part. When you first run beets 1.1, it will look for an old-style .beetsconfig to migrate. If it finds one (and there is no new-style config.yaml yet), beets will warn you and then transparently convert one to the other. At this point, you’ll likely want to:

  • Look at your new configuration file (find out where in Configuration) to make sure everything was migrated correctly.
  • Remove your old configuration file (~/.beetsconfig on Unix; %APPDATA%\beetsconfig.ini on Windows) to avoid confusion in the future.

You might be interested in the Changelog to see which configuration option names have changed.

What’s Migrated

Automatic migration is most important for the configuration file, since its syntax is completely different, but two other files are also moved. This is to consolidate everything beets needs in a single directory instead of leaving it messily strewn about in your home directory.

First, the library database file was at ~/.beetsmusic.blb on Unix and %APPDATA%\beetsmusic.blb on Windows. This file will be copied to library.db in the same directory as your new configuration file. Finally, the runtime state file, which keeps track of interrupted and incremental imports, was previously known as ~/.beetsstate; it is copied to a file called state.pickle.

Feel free to remove the old files once they’ve been copied to their new homes.

Manual Migration

If you find you need to re-run the migration process, just type beet migrate in your shell. This will migrate the configuration file, the database, and the runtime state file all over again. Unlike automatic migration, no step is suppressed if the file already exists. If you already have a config.yaml, for example, it will be renamed to make room for the newly migrated configuration.