Skip to main content
Libraries are self-contained directories that store all your data, metadata, and thumbnails in one place. Each library lives in a single folder with a .sdlibrary extension. You can move libraries between machines, back them up to external drives, or share them with others by copying the directory. When you open a library, Spacedrive loads its database and configuration into memory and locks it to prevent corruption from concurrent access.

​
Structure

Each library contains library.json for configuration and metadata, database.db for the SQLite database, and a thumbnails/ directory with two-level sharding for performance. The thumbnails directory includes metadata.json for generation settings. A .sdlibrary.lock file appears when the library is open to prevent multiple processes from accessing it simultaneously. Future directories include previews/ for full-size previews, indexes/ for search indexes, and exports/ for temporary exports.

​
Core Components

The LibraryManager creates, opens, and discovers libraries on your system. Each active Library instance holds a database connection and loaded configuration. The LibraryConfig stores settings like thumbnail quality and sync preferences in library.json.

​
Working with Libraries

Create a library with create_library("My Photos", None). Omit the path to use your default libraries directory. Open an existing library with open_library() by providing its path. The manager checks for lock files and loads configuration before returning the instance. Scan your system for libraries with scan_for_libraries(). This searches common locations and returns metadata without opening each library.

​
Thumbnail Management

Libraries store thumbnails using content-addressed storage with two-level directory sharding. Save thumbnails with save_thumbnail(), check existence with has_thumbnail(), and retrieve them with get_thumbnail(). Thumbnails organize automatically into subdirectories based on their content hash.

​
Configuration

The library.json file stores all library settings:
​
library.json
Configuration Object

​
Portability

Self-contained libraries work immediately after copying to a new location with zero configuration. Copy the entire folder to create a complete backup. Store libraries on external drives, network shares, or cloud-synced folders for automatic backup.
Future versions will add new directories for features like search indexes and version history without breaking existing libraries.