renux

KO | EN

gitlite — search

#javascript #python #hacktoberfest #golang #android #deep-learning #linux #nodejs #windows #cli #vue #ios #mcp #open-source

(★ 24)

A terminal-based bulk file renamer with a TUI

renux Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![PyPI version](https://img.shields.io/pypi/v/renux?style=flat&labelColor=black&color=black)](https://pypi.org/project/renux/)
[![Downloads](https://static.pepy.tech/personalized-badge/renux?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLACK&left_text=downloads)](https://pepy.tech/projects/renux)
[![License](https://img.shields.io/github/license/andrianllmm/renux?style=flat&labelColor=black&color=black)](https://github.com/andrianllmm/renux/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/andrianllmm/renux?style=flat&labelColor=black&color=black)](https://github.com/andrianllmm/renux/stargazers)
[![CI](https://img.shields.io/github/actions/workflow/status/andrianllmm/renux/ci.yml?labelColor=black&color=black&label=CI)](https://github.com/andrianllmm/renux/actions/workflows/ci.yml)

### renux

**A terminal-based bulk file renamer with a TUI**

</div>

###

## About

`renux` is a tool with a text-based (terminal) user interface (TUI) that
automates file renaming. It simplifies this task with features like regex,
placeholders, and text transformations, making it ideal for situations such as
renaming photos, cleaning up download folders, or enforcing consistent naming
conventions.

### Features

- **Regex**: perform advanced renaming with pattern matching, capturing groups,
  and replacements.
- **Text transformations**: apply text transformations like slugify, camelCase
  to snake_case, and more.
- **Counter placeholders**: add incremental counters (e.g., file1.txt,
  file2.txt) with customizable starting points, increments, and padding.
- **Date placeholders**: include file creation/modification dates or the current
  date in filenames with customizable formats.
- **File size placeholders**: include a file's size, auto-scaled to the
  largest sensible unit or a specific one (bytes, KB, MB, GB).
- **Image placeholders**: include an image's width and height in pixels, plus
  EXIF capture date and camera make/model when available.
- **Location placeholders**: include a photo's GPS latitude, longitude, and
  altitude from EXIF data when available.
- **Video placeholders**: include a video's width, height, frame rate, and
  duration.
- **Backup and undo/redo**: save and restore changes to your files.
- **File exclusion**: exclude files from renaming.
- **Keyboard shortcuts**: use hotkeys to quickly apply actions and navigate the
  UI.

## Installation

Using [pipx](https://pipx.pypa.io/stable/) (recommended).

```sh
pipx install renux
```

Alternatively, you can use [pip](https://pip.pypa.io/en/stable/).

### AI Agent Skill

If you use an AI coding agent (Claude Code, etc.), you can install a
[skill](skills/renux) that teaches it how to drive `renux` for bulk-renaming
tasks:

```sh
npx skills add https://github.com/andrianllmm/renux/tree/main/skills/renux
```

## Usage

```sh
renux [directory] [pattern] [replacement]
```

**Arguments**

- `directory`: Directory where files are located (default is the current
  directory or `.`).
- `pattern`: Search pattern, which can be a regular expression (default is '').
- `replacement`: Replacement string for the pattern (default is '').

**Options**

- `-c COUNT`, `--count COUNT`: Max replacements per file (default is 0, meaning
  unlimited).
- `-r`, `--regex`: Treats the pattern as a regular expression (default is True).
- `--case-sensitive`: Makes the search case-sensitive (default is False).
- `--apply-to`: Specifies where the renaming should be applied. Options are:
- `name`: Rename the file's base name (default).
- `ext`: Rename the file's extension.
- `both`: Rename both the name and extension.
- `--exclude PATTERN`: Exclude files matching `PATTERN` (exact name or glob,
  e.g. `README.md`, `*.log`). Repeatable, e.g.
  `--exclude README.md --exclude Dockerfile`. In the TUI, this is a
  comma-separated field in the form.

Patterns are evaluated in order, gitignore-style: prefix a pattern with `!`
to re-include a file matched by an earlier pattern, e.g.
`--exclude "*.txt" --exclude "!foo1.txt"` excludes all `.txt` files except
`foo1.txt`.

- `-y`, `--yes`: Apply the rename immediately without opening the TUI
  (headless mode, useful for scripts/CI).
- `--dry-run`: Preview the rename without opening the TUI or changing any
  files (headless mode).
- `--undo`: Undo the last rename applied to `directory` without opening the
  TUI (headless mode).
- `--redo`: Redo the last undone rename in `directory` without opening the
  TUI (headless mode).

**Tags**

- **Text transformations**: `{string|filter}`
  - `slugify`: Convert into a URL/filename-friendly format (e.g. "hello world" → "hello-world")
  - `lower`: Convert to lowercase
  - `upper`: Convert to uppercase
  - `caps`: Capitalize the first letter
  - `title`: Capitalize each word
  - `camel`: Convert to camel case (e.g. "hello world" → "helloWorld")
  - `pascal`: Convert to pascal case (e.g. "hello world" → "HelloWorld")
  - `snake`: Convert to snake case (e.g. "hello world" → "hello_world")
  - `kebab`: Convert to kebab case (e.g. "hello world" → "hello-world")
  - `swapcase`: Swap the case (e.g. "Hello World" → "hELLO wORLD")
  - `reverse`: Reverse the string (e.g. "Hello World" → "dlroW olleH")
  - `strip`: Remove leading and trailing whitespace
  - `len`: Get the length of the string

- **General**
  - **Counter**: `{counter(start=1,step=1,padding=1)}`, e.g., `{counter(1,2,3)}`
    Insert an incrementing counter. Each placeholder occurrence tracks its own sequence, advancing by `step` after every file.

- **Date**
  - **Now**: `{now(<format>)}`, e.g., `{now(%Y)}`
    The current date/time.
  - **Created At**: `{created_at(<format>)}`
    The file's creation date/time.
  - **Modified At**: `{modified_at(<format>)}`
    The file's last-modified date/time.

- **File**
  - **Size**: `{size(<unit>)}`, e.g., `{size(mb)}`
    The file's size. Auto-scaled to the largest sensible unit unless a unit (b, kb, mb, gb) is given.

- **Image**
  - **Width**: `{width}`
    The image's width in pixels.
  - **Height**: `{height}`
    The image's height in pixels.
  - **Taken At**: `{taken_at(<format>)}`, e.g., `{taken_at(%Y)}`
    The photo's capture date/time from EXIF metadata. Not available for images without EXIF data (e.g. screenshots, re-exported/edited images).
  - **Camera Make**: `{camera_make}`
    The camera manufacturer from EXIF metadata. Not available for images without EXIF data.
  - **Camera Model**: `{camera_model}`
    The camera model from EXIF metadata. Not available for images without EXIF data.

- **Location**
  - **Latitude**: `{latitude}`
    The photo's GPS latitude in decimal degrees. Not available for images without GPS EXIF data.
  - **Longitude**: `{longitude}`
    The photo's GPS longitude in decimal degrees. Not available for images without GPS EXIF data.
  - **Altitude**: `{altitude}`
    The photo's GPS altitude in meters. Not available for images without GPS EXIF data.

- **Video**
  - **Video Width**: `{video_width}`
    The video's width in pixels.
  - **Video Height**: `{video_height}`
    The video's height in pixels.
  - **Frame Rate**: `{frame_rate}`
    The video's frame rate. Not available for all containers (e.g. MP4).
  - **Duration**: `{duration}`
    The video's duration, in seconds.

Run `renux --help` for more details.

### Examples

- Rename files starting with "IMG" to "Image":
  ```sh
  renux my_photos/ IMG_ Image_
  ```
- Rename all `.txt` files to `.bak`:
  ```sh
  renux my_directory/ .txt .bak --apply-to ext
  ```
- Use regex to retain information from the old name:
  ```sh
  renux my_documents "document (\d).pdf" "doc (\1).pdf" -r
  ```
- Append a counter to filenames:
  ```sh
  renux my_files/ file "file_{counter}"
  ```
- Append creation year to filenames:
  ```sh
  renux my_files/ file "file_{created_at(%Y)}"
  ```
- Apply transformations like slugify:
  ```sh
  renux my_files "(.*)" "{filename|slugify}" -r
  ```

## Dev Setup

1. Clone the repo
   ```sh
   git clone https://github.com/andrianllmm/renux.git
   cd renux
   ```
2. Install dependencies with [Poetry](https://python-poetry.org/)
   ```sh
   poetry install
   ```

### Testing

Run tests with [pytest](https://docs.pytest.org/en/stable/):

```sh
poetry run python -m pytest
```

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.

## License

Distributed under the [MIT License](LICENSE).

renux

renux Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

renux

renux Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README