Ollama File Renamer
English | Русский
Rename messy files by their content with a local Ollama model. new2.txt becomes
docs-update-backend-migration-plan.txt, new6.txt becomes sql-create-index-orders-slow-reports.txt. It runs as a desktop window
or a command-line tool, needs no API keys, and copies every original to a backup folder before touching it.
It's for anyone with a folder of notes, snippets and drafts named Untitled, new, copy (3): developers,
writers, people who dump quick notes into one inbox folder.
Features
- Runs on your machine: file contents go only to your own Ollama.
- Originals are copied to
backup_<timestamp>/inside the folder first, and a rename never overwrites an existing file (it adds-1,-2, ...). - In the desktop window you pick a folder, see exactly which files will change, then watch each row get its new name.
- It groups the folder into patterns (
new*.txt,Untitled*.md); you choose one or type a prefix and extension. - Works with any model you have installed in Ollama. Reasoning models work too: their
<think>output is stripped. - The CLI can rename several files at once (
-p 4). - Reads text files and the text layer of PDFs (
--ext .pdf). Scanned PDFs without text and other binary files are skipped with a reason, and so are empty files.
Install
You need Ollama running with one model pulled:
ollama pull qwen2.5-coder:7b
Then install the app with one command. It installs uv, Python and ollama-rename
into your user folder, no admin rights needed.
macOS / Linux
curl -LsSf https://raw.githubusercontent.com/octrow/ollama-rename-files/main/install.sh | sh
Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/octrow/ollama-rename-files/main/install.ps1 | iex"
Prefer to read it first? Download install.sh or install.ps1, look through it, then run it.
Run it again to update; sh install.sh --uninstall (or $env:INSTALL_UNINSTALL = "1" on Windows) removes the app.
From PyPI
Already have Python 3.10+? Install it from PyPI:
uv tool install ollama-rename-files # or: pipx install ollama-rename-files
Update with uv tool upgrade ollama-rename-files (pipx upgrade ollama-rename-files).
Standalone build
No Python needed: download the archive for your system from the
latest release (Linux x86_64 and arm64, macOS on
Apple silicon, Windows), unpack it and run ollama-rename gui from the unpacked folder. The builds aren't signed,
so macOS asks you to allow the app in System Settings → Privacy & Security on the first run.
From source
git clone https://github.com/octrow/ollama-rename-files.git
cd ollama-rename-files
uv sync
uv run ollama-rename gui
Usage
Desktop window
ollama-rename gui
Browse to a folder, pick a discovered pattern or type a prefix and extension, and the window lists exactly which files will change. Choose an installed model and click Rename N files: each row fills in with its new name as the model answers, and Stop halts the run after the current file.
The window shows a local page served at http://127.0.0.1:5000 (change with --port or FILE_RENAMER_PORT). If that
port is taken by another app, the next free one is used. If File Renamer itself is already running there, you get its
link and a Restart it? [y/N] prompt (No by default, and always No without a terminal). ollama-rename gui --browser
serves the page without opening a window.
On Linux the window needs Qt or GTK bindings for Python. Without them ollama-rename gui opens the same page in
your default browser. For a native window in a source checkout: uv pip install "pywebview[qt]", or install the
system GTK bindings (python3-gi). Windows and macOS work out of the box.
Command line
# Interactive: asks for the folder, the file pattern, the model and the context length.
# Options you pass on the command line are not asked again. Lists the files and asks before renaming.
ollama-rename
# A folder, a model and 500 characters of each file; asks only for the file pattern
ollama-rename -d ~/notes/inbox -m qwen2.5-coder:7b -c 500
# No prompts: every new*.txt file in the folder
ollama-rename -a -d ~/notes/inbox --prefix new --ext .txt
# Four files at a time; asks for everything but the folder
ollama-rename -d ~/notes/inbox -p 4
| Option | Short | Description |
|---|---|---|
--auto |
-a |
Run without interactive prompts. Requires -d. |
--directory |
-d |
Folder with the files to rename. |
--model |
-m |
Ollama model to use (default qwen2.5-coder:7b). |
--context |
-c |
How many characters of each file to send to the model (default 2048). |
--prefix |
File name prefix to match (default new): new takes new1.txt and new.txt, not newsletter.txt. Used with --ext as the pattern. |
|
--ext |
File extension to match, with the dot (default .txt). |
|
--parallel |
-p |
Files renamed at the same time. 0 (default) means one by one. |
Ollama on another machine or port? Set OLLAMA_HOST, e.g. OLLAMA_HOST=http://192.168.1.20:11434 ollama-rename.
How it works
- Finds the files in the folder that match the pattern: the prefix as a whole word (
newtakesnew1.txt, notnewsletter.txt) and the extension. A prefix typed in the desktop window matches any name that starts with it. - Creates
backup_<timestamp>/in that folder and copies each file there before renaming it. - Sends the first
--contextcharacters of the file (for a PDF, of its extracted text) to your local Ollama model. - Picks the name out of the reply (skipping chatter like "Here is a name:") and cleans it: lowercase, safe
characters, at most 128 characters. Names in any script work:
заметка-про-бэкап.txt. - Renames the file, keeping its original extension and never overwriting an existing file.
- Logs every action and prints which files failed and why.
Names follow the pattern <type>-<action>-<component>-<short-description>, for example:
task-fix-backend-resolve-database-connection-issue.txtdoc-update-project-architecture-notes.md
The prompt is tuned for software-project notes: type is task, issue, doc, snippet, review or idea. It lives in
PROMPT_TEMPLATE in rename_files.py if you want other names.
How it differs from ai-renamer
ai-renamer is a popular Node.js CLI that does the same job and more: it also renames images and videos, and it talks to Ollama, LM Studio and OpenAI. Pick it if you rename photos or want a cloud model.
Ollama File Renamer is narrower: text files, PDFs and local Ollama only. What it adds is a desktop window with a preview of
the exact files that will change, a backup copy of every original, renames that never overwrite, and pattern
discovery so you rename new*.txt without touching the rest of the folder.
Development
uv sync
uv run pytest
uv run ruff check .
See CONTRIBUTING.md. Security reports go through SECURITY.md.
License
Metadata
Release files for ollama-rename-files 0.3.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ollama_rename_files-0.3.6.tar.gz | 113.9 kB | With provenance | Details for ollama_rename_files-0.3.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ollama_rename_files-0.3.6-py3-none-any.whl | Python 3 | none | any | Details for ollama_rename_files-0.3.6-py3-none-any.whl |
Total release size: 139.1 kB
Release files / ollama_rename_files-0.3.6.tar.gz
| Download URL | ollama_rename_files-0.3.6.tar.gz |
|---|---|
| Size | 113.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
60b7bb7621cc33048621383aba793992abde868b9e1008651c806ae4f2ea6b51
|
|
BLAKE2b-256 checksum How to use checksums |
140861969af499324ea37e40b35c4f8f57413d20282e4a0be0f8914f8ad1aa5c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logRelease files / ollama_rename_files-0.3.6-py3-none-any.whl
| Download URL | ollama_rename_files-0.3.6-py3-none-any.whl |
|---|---|
| Size | 25.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9719aeecb464c707404aad2f312b46a4f218619b15c1427b3f5901802a043982
|
|
BLAKE2b-256 checksum How to use checksums |
37927029a76fb0bbc87f1056db369f1b928d836b82c53360ebfe514fb526b4f2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logSecurity for ollama-rename-files 0.3.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ollama_rename_files-0.3.6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.