# How the Auto-Rename Feature Handles Filename Conflicts in you-get

> Discover how you-get's auto-rename feature prevents download failures by adding numeric suffixes to filenames when conflicts arise.

- Repository: [Mort Yao/you-get](https://github.com/soimort/you-get)
- Tags: internals
- Published: 2026-03-06

---

**The auto-rename feature in you-get automatically appends incremental numeric suffixes like `(1)`, `(2)` to filenames when conflicts are detected, ensuring downloads never fail due to existing files.**

When downloading videos or other media with `you-get`, the tool must decide what to do when a target filename already exists. The auto-rename feature provides a hands-free solution that generates unique filenames without user intervention. This article examines the conflict detection logic, the algorithm that constructs new names, and the specific implementation in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py).

## How Filename Conflicts Are Detected

Before any download begins, `you-get` constructs the full target path (`filepath`) based on the video title, output directory, and file extension. The program then checks whether a file already exists at that location using standard filesystem operations.

If a conflict is detected, `you-get` evaluates two command-line flags to determine the next action: **`--force`** and **`--auto-rename`** (or `-a`).

## Conflict Resolution Logic: Force vs. Auto-Rename vs. Interactive

The behavior follows a strict priority depending on which flags are passed:

- **`--force` is set**: The existing file is overwritten immediately (after a confirmation prompt in some versions), regardless of the auto-rename setting.
- **`--auto-rename` is not set**: The program pauses and prompts the user interactively to decide whether to overwrite the file.
- **`--auto-rename` is set**: The program bypasses user interaction and automatically generates a new filename using the algorithm described below, then retries the existence check.

## The Auto-Rename Algorithm in src/you_get/common.py

The core renaming logic resides in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) between lines **916–928**. The implementation uses regular expressions to detect and increment numeric suffixes, ensuring that filenames follow the pattern `name (N).ext`.

### Step 1: Splitting the Filename

The algorithm first deconstructs the existing filepath into its base name and extension:

```python
path, ext = os.path.basename(filepath).rsplit('.', 1)

```

This separates `video.mp4` into `path="video"` and `ext="mp4"`.

### Step 2: Detecting Existing Numeric Suffixes

The code compiles a regex pattern to identify suffixes in the format ` (N)` where N is a positive integer:

```python
finder = re.compile(r' \([1-9]\d*?\)$')

```

This pattern specifically looks for a space, opening parenthesis, digits (not starting with zero), and closing parenthesis at the end of the base name.

### Step 3: Generating the New Filename

If no numeric suffix is found, the algorithm appends ` (1)` before the extension:

```python
thisfile = path + ' (1).' + ext

```

If a suffix already exists (e.g., `video (3).mp4`), the code defines a helper function to increment the captured number:

```python
def numreturn(a):
    return ' (' + str(int(a.group()[2:-1]) + 1) + ').'

thisfile = finder.sub(numreturn, path) + ext

```

This transforms `video (3).mp4` into `video (4).mp4`.

### Step 4: Reassembling the Path and Retrying

The new filename is joined back with the original directory, and the existence check loops again:

```python
filepath = os.path.join(os.path.dirname(filepath), thisfile)

```

The loop continues until a non-conflicting name is found, at which point the download proceeds with the newly generated `filepath`.

## Windows-Specific Safeguard

After a download completes, `you-get` performs an additional safety check on Windows systems to handle potential lingering conflicts. In [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) at lines **332–336**, the code verifies write access to the target file:

```python
if os.access(filepath, os.W_OK):
    # proceed with final rename/move

else:
    # apply final fallback name with " (2)" suffix

```

If the file is still inaccessible (locked by another process or existing with restricted permissions), the system appends a final fallback suffix `" (2)"` before calling `os.rename`, ensuring the operation never fails silently.

## Using Auto-Rename from the Command Line

To enable automatic renaming when downloading media, pass the `-a` or `--auto-rename` flag:

```bash
you-get -a https://www.bilibili.com/video/av123456

```

If `video.mp4` already exists in the output directory, `you-get` will automatically save the new file as `video (1).mp4`, then `video (2).mp4`, and so on, without prompting for user input.

## Programmatic Use in Python

When using `you-get` as a library, you can enable the same behavior by setting the global `auto_rename` flag before calling download functions:

```python
import you_get.common as yg

# Enable automatic conflict resolution

yg.auto_rename = True

# Proceed with download

yg.download_urls(
    urls=['https://example.com/video.mp4'],
    title='video',
    ext='mp4',
    output_dir='.',
    merge=False,
    force=False,
)

```

The `download_urls` function will internally invoke the renaming logic in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) whenever it detects an existing file, ensuring the download completes without manual intervention.

## Summary

- **Conflict Detection**: `you-get` checks for existing files before starting downloads and reacts to the `--force` and `--auto-rename` flags.
- **Auto-Rename Logic**: Located in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) (lines 916–928), the feature uses regex pattern `r' \([1-9]\d*?\)$'` to detect and increment numeric suffixes like `(1)`, `(2)`.
- **Algorithm Steps**: Splits filename into base and extension, detects existing numeric suffixes, increments or appends `(1)`, and loops until a unique name is found.
- **Windows Safeguard**: Additional check at lines 332–336 ensures write access before final rename, with fallback to `(2)` suffix if needed.
- **Usage**: Enable via `-a`/`--auto-rename` CLI flag or set `yg.auto_rename = True` when using as a library.

## Frequently Asked Questions

### What happens if both --force and --auto-rename are used together?

When both flags are provided, `--force` takes precedence. According to the logic in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py), the program will overwrite the existing file rather than generating a new name. The auto-rename logic is only triggered when `--force` is not set and a conflict is detected.

### Does auto-rename work on all operating systems?

Yes, the auto-rename implementation in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) uses standard Python `os.path` functions and regular expressions that are platform-independent. However, Windows users benefit from an additional safeguard (lines 332–336) that checks file write permissions before the final rename operation, which handles Windows-specific file locking scenarios.

### Can I customize the numeric suffix format used by auto-rename?

No, the suffix format is hardcoded in the regex pattern `r' \([1-9]\d*?\)$'` and the string concatenation logic within [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py). The format strictly follows the pattern ` (N)` (space, parenthesis, number, parenthesis) before the file extension. To use a different format, you would need to modify the source code in the `numreturn` function and the regex compilation line.

### Is there a limit to how many times auto-rename will increment?

There is no explicit upper bound coded in the rename loop at lines 916–928. The `while` loop continues indefinitely until `os.path.exists(filepath)` returns `False`, meaning it will keep incrementing the numeric suffix (e.g., from `(999)` to `(1000)`) until a unique filename is found. In practice, filesystem limits or path length restrictions would be reached long before any coded limit.