Skip to content

README_EN.md

Latest commit

 

History

History
153 lines (107 loc) · 5.71 KB

README_EN.md

File metadata and controls

153 lines (107 loc) · 5.71 KB
Win Folder Manager

PyPI version PyPI Downloads Docker Pulls Build Status Python Versions License

A lightweight, web-based manager for Windows folder customization.

中文文档 | Wiki | Features • Installation • Usage • Docker • Development

Win Folder Manager allows you to easily customize Windows folders through a clean Web UI. Set custom icons, aliases (localized names), and info tips without manually editing hidden system files.

✨ Features

  • 🖼️ Custom Icons: Easily set folder icons (supports absolute and relative paths).
  • 🏷️ Folder Aliases: Rename folders visually in Explorer without changing the actual directory name.
  • ℹ️ Info Tips: Add custom hover text descriptions to folders.
  • 🤖 AI Auto-naming: Integrate with various AI models (e.g., OpenAI, DeepSeek) to automatically generate Emoji icons and aliases based on folder names.
  • 🎨 Auto Icon Conversion: Upload images (PNG/JPG, etc.) directly; they are automatically converted to .ico format and archived.
  • 🔄 Batch Operations: Convert absolute icon paths to relative paths in batch for portability.
  • 📂 Quick Actions: Open folders in Explorer or CMD directly from the UI.
  • 🚀 Web Interface: Simple Flask-based UI accessible from your browser.
  • 💾 Persistent Config: Configuration saved automatically in %APPDATA%.

📸 Screenshots

Core Concept: The physical path remains unchanged (English), but displays as a localized alias (Chinese) in Explorer.

Home Dashboard Edit Attributes
Configuration Explorer Preview

📦 Installation

Method 1: Download via GitHub Releases (Recommended)

This is the easiest way to use the application, no Python environment required.

  1. Visit the Releases page.
  2. Download the latest WinFolderManager.exe file.
  3. Double-click to run.

Method 2: Install via PyPI (Recommended)

pip install win-folder-manager

Method 3: Install from Source

git clone https://github.com/LinJHS/win-folder-manager.git
cd win-folder-manager
pip install .

Note: If you are developing on Linux or Docker, use requirements-docker.txt to avoid pywin32 installation errors:

pip install -r requirements-docker.txt

🚀 Usage

Once installed, simply run:

win-folder-manager

Or using the python module directly:

python -m manager

The application will start a local web server (default: http://127.0.0.1:6800) and automatically open your default browser.

Command Line Options

You can customize the startup behavior with the following arguments:

  • -p, --port: Specify the server port (default: 6800)
  • --host: Specify the host to bind to (default: 127.0.0.1)
  • --no-browser: Do not open the browser automatically on start
  • --debug: Run in Flask debug mode

Examples:

# Run on port 9000
win-folder-manager -p 9000

# Allow external access
win-folder-manager --host 0.0.0.0

# Start server only, without opening browser
win-folder-manager --no-browser

Configuration

The configuration file is stored at: %APPDATA%\win-folder-manager\config.json

You can configure the root path to scan for folders directly in the Web UI.

🐳 Docker Support (Not Recommended)

⚠️ Warning: The core functionality of this application (modifying folder icons and attributes) relies heavily on Windows System APIs and file system features (like the attrib command). Running in Docker (Linux container) will result in core features being unavailable, serving only as a file browser. Unless you know exactly what you are doing, it is strongly recommended to run natively on Windows.

You can run Win Folder Manager using Docker.

docker run -d \
  -p 6800:6800 \
  -v /path/to/your/folders:/data \
  -v win-folder-manager-config:/root/.config/win-folder-manager \
  linjhs/win-folder-manager

🛠️ Development

  1. Clone the repository 
    git clone https://github.com/LinJHS/win-folder-manager.git
  2. Install dependencies 
    pip install -r requirements.txt
  3. Run locally 
    python -m manager

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.