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

> Learn how to use PicList for local file system storage. Follow our guide to configure Local pic-bed, set baseDir, and optionally enable customUrl for web access.

- Repository: [Kuingsmile/piclist](https://github.com/kuingsmile/piclist)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/src/renderer/utils/configPaths.ts) (lines 17-31).

```json
{
  "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:

```bash
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`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/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.