Installation Issues with `organize-tool` on Windows from Scratch i.e. w/o dev env

[florianklumb]

1. Dependency on Recent Python and Rust Toolchain

   • organize-tool requires Python 3.9+
   • Some dependencies, particularly pydantic-core, are Rust-based and require compiling native Rust extensions during installation.

2. Rust and Build Tools Requirement

   • To build those Rust extensions, a full Rust toolchain including Cargo is necessary.
   • On Windows, cargo (Rust’s package manager) does not get fully installed automatically by pip’s on-the-fly Rust install.
   • The installation fails if Rust and Cargo are not installed manually beforehand.

3. Visual C++ Build Tools Requirement

   • In addition to Rust, the Microsoft Visual C++ Build Tools are required on Windows to provide the necessary linker and compiler for building native extensions.
   • The full Visual Studio IDE is not needed, but the build tools must be installed separately.

4. Version Compatibility Issues

   • For the latest Python 3.14 version, some Rust-based dependencies like pydantic-core do not yet officially support Python 3.14 causing build failures:
     • The Rust binding PyO3 checks Python version compatibility and blocks build for unreleased Python versions.
     • This leads to build errors even if Rust and build tools are installed correctly.

5. Documentation / User Guidance Gaps

   • The current installation documents lack clear guidance about these prerequisites on Windows for non-developer users.
   • Many users expecting a pure Python package face frustrations due to the Rust/native dependencies and tooling required.
   • Including a note about mandatory Rust + Visual C++ Build Tools installation and Python version compatibility could reduce confusion and support burden.

---

Suggested Improvements

• Provide precompiled wheels for Windows to avoid build from source.
• Add comprehensive installation prerequisites in documentation highlighting:
  • Rust and cargo manual install required on Windows for building native extensions.
  • Requirement of Visual C++ Build Tools for native compilation on Windows.
  • Supported Python versions clearly stated (possibly delays support for bleeding-edge Python versions or provide workarounds).
• Offer fallback options or builds that don’t require Rust in simpler usage scenarios.
• Enhance error messages to guide users toward installing missing tooling.

---

Organize-tool Windows Installation Manual

Step 1: Install Python 3.11 (Recommended)

Note: Python 3.14 currently causes build issues with some dependencies.

1. Download Python 3.11 from the official site:
   https://www.python.org/downloads/release/python-311x/
2. Run the installer.
3. Crucially, CHECK the box Add Python 3.11 to PATH before proceeding.
4. Choose “Install Now” with default options.
5. Wait for the installation to complete.
6. Verify installation in a new Command Prompt:

   python --version
   pip --version
   

---

Step 2: Install Microsoft Visual C++ Build Tools

Rust and some Python packages require this compiler/linker on Windows.

1. Download the Build Tools for Visual Studio from:
   https://visualstudio.microsoft.com/downloads/
2. Scroll down and select Build Tools for Visual Studio in the Tools section.
3. Run the installer.
4. Select the Desktop development with C++ workload.
5. Complete installation and restart PC if prompted.

---

Step 3: Install Rust and Cargo

Full Rust toolchain is required to build Rust native extensions.

1. Download Rust installer from:
   https://rustup.rs/
2. Run the installer and follow prompts.
3. This installs rustc (compiler) and cargo (package manager) system-wide.
4. Verify in a new Command Prompt:

   rustc --version
   cargo --version
   

---

Step 4: Install organize-tool

1. Open a new Command Prompt.
2. Run the install command with Python 3.11 active and Rust + Build Tools installed:

   pip install -U organize-tool
   

3. This will download all required dependencies, compile the Rust components via Cargo, and install the tool.

---

Step 5: Usage Basics

• After installation, run:

  organize -h
  

  to see command-line help and start organizing files.

Troubleshooting

• If installs fail at building Rust components, ensure Build Tools and Rust are correctly installed and on PATH.
• Avoid using bleeding-edge Python versions (like 3.14) due to compatibility issues with Rust-based libraries. Python 3.11 is stable and well-supported.