How to Use PicList for Local File System Storage: Complete Configuration Guide

To use PicList for local file system storage, enable the Local pic-bed in Settings, set the absolute path for baseDir, and optionally configure a customUrl for web access.

PicList is an open-source image management tool that treats your local hard drive as a first-class picture-bed. When you configure PicList for local file system storage, images are written directly to a specified folder on your computer using Node.js file system operations, bypassing cloud dependencies entirely. This guide walks through the GUI setup, JSON configuration, CLI usage, and web server integration based on the actual kuingsmile/piclist source code.

Enabling Local Storage in the PicList GUI

The Local pic-bed is configured through the Settings interface, with UI field definitions found in src/renderer/utils/static.ts around line 17.

Step-by-Step Activation

1. Open Settings → Upload → PicBed → PicBed List (accessed via the gear icon).
2. Click Add and select Local (icon identifier local), with descriptions defined in src/renderer/manage/utils/constants.ts at line 872.
3. Configure the required fields:
   • Base Directory: The absolute file system path where images are stored (e.g., C:\Users\Me\Pictures\PicList).
   • Custom URL: Optional web-accessible URL pointing to the same folder (e.g., http://localhost:8080/piclist).
4. Set Current PicBed to Local in the dropdown menu.
5. Click Apply to save the configuration.

Key Configuration Parameters

The Local pic-bed behavior is controlled by the ILocalConfig interface (located in src/universal/types). These parameters define how PicList interacts with your file system:

• baseDir: Absolute local path for file storage. PicList creates this directory automatically if it does not exist using fs.ensureDirSync.
• customUrl: External URL that maps to baseDir. Essential when serving files via Nginx, Apache, or the built-in web server.
• deleteLocalFile: Boolean flag that removes the local file after successful upload to a remote bed. Default is false.
• webPath: Alternative path prefix used specifically when PicList's built-in web server is enabled (settings.enableWebServer).

Configuring Local Storage via JSON

For advanced users or headless deployments, edit ~/.piclist/config.json directly. The configuration schema is enforced by the configPaths map in src/renderer/utils/configPaths.ts (lines 17-31).

{
  "picBed": {
    "uploader": "local",
    "list": [
      {
        "type": "local",
        "name": "Local",
        "baseDir": "D:/PicListImages",
        "customUrl": "http://192.168.1.50/piclist",
        "webPath": "/piclist"
      }
    ]
  },
  "settings": {
    "enableWebServer": true,
    "webServerHost": "0.0.0.0",
    "webServerPort": 36677,
    "webServerPath": "/piclist",
    "deleteLocalFile": false
  }
}

Uploading Images to Local Storage

GUI Upload Methods

Drag and drop images onto the PicList main window, or paste from the clipboard. The application writes the file to your configured baseDir and returns either the absolute file path or the constructed customUrl + '/' + fileName in the Upload Result dialog.

CLI Upload Commands

If you have the PicList CLI installed, force local storage using the --picbed flag:

piclist upload /path/to/image.jpg --picbed local

This command enters the same upload queue used by the GUI, as implemented in src/main/utils/uploadTaskQueue.ts at line 250.

Remote Access to Local Files

To access locally stored images from other devices, you have two options:

External Web Server: Configure customUrl to point to your existing Nginx or Apache virtual host serving the baseDir directory.

Built-in Web Server: Enable PicList's embedded server by setting settings.enableWebServer to true. The server implementation resides in src/main/server/webServer/index.ts (line 454). Set webServerPath to match your webPath configuration for consistent URL generation.

Technical Implementation Details

When processing a local upload, PicList executes the following flow:

1. Queue Processing: The image enters UploadTaskQueue (src/main/utils/uploadTaskQueue.ts).
2. File Writing: If picBed equals 'local', the Uploader writes the file via fs.ensureFileSync, using the fs-extra library wrappers around Node.js fs APIs (see src/main/utils/static.ts, lines 16-18).
3. Result Generation: The upload result object contains imgUrl, populated with either the absolute path or the customUrl concatenation.

All file system operations use fs-extra, providing promise-based wrappers that ensure directory existence before writing binary image data.

Summary

• Enable the Local pic-bed in Settings → Upload → PicBed List by selecting the local type defined in the source constants.
• Set baseDir to an absolute path where PicList has write permissions; the directory is auto-created if missing via fs-extra.
• Configure customUrl to serve files via an external web server or PicList's built-in server (enableWebServer in src/main/server/webServer/index.ts).
• Upload via drag-and-drop, clipboard paste, or CLI command piclist upload --picbed local.
• Access files directly on disk or through the configured URL endpoint.

Frequently Asked Questions

What file system permissions does PicList require for local storage?

PicList requires read and write permissions for the directory specified in baseDir. The application uses fs-extra to automatically create missing directories, but it cannot write to system-protected folders without elevated privileges. Ensure the PicList process owner has appropriate access rights to the target path.

Can I use PicList local storage without an internet connection?

Yes. Local file system storage operates entirely offline. The upload process writes files using Node.js fs APIs through fs-extra, requiring no network connectivity. However, if you configure a customUrl that points to an external domain, that URL will only resolve when the network path is available.

How do I migrate my PicList local storage to a new computer?

Copy the contents of your configured baseDir directory to the new machine. Update the baseDir path in ~/.piclist/config.json to reflect the new absolute path. If using the built-in web server, verify that settings.webServerHost and webServerPort remain valid on the new network interface.

What is the difference between customUrl and webPath in PicList?

customUrl is the full external URL (including protocol and domain) used to access files, such as http://192.168.1.50/piclist. webPath is the URI path component used exclusively by PicList's built-in web server (e.g., /piclist). When using the embedded server, customUrl typically combines the server host:port with webPath to form complete image URLs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}