{"id":51460629,"url":"https://github.com/mitsuki31/xls2csv","last_synced_at":"2026-07-06T05:01:02.558Z","repository":{"id":352190171,"uuid":"1214218898","full_name":"mitsuki31/xls2csv","owner":"mitsuki31","description":"Simple but professional CLI tool to convert Excel files to CSV","archived":false,"fork":false,"pushed_at":"2026-04-25T18:38:05.000Z","size":73,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-25T20:27:16.293Z","etag":null,"topics":["cli","cli-app","csv","csv-export","excel","excel-automation","python-cli","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mitsuki31.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T09:17:43.000Z","updated_at":"2026-04-25T18:38:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mitsuki31/xls2csv","commit_stats":null,"previous_names":["mitsuki31/xls2csv"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mitsuki31/xls2csv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitsuki31%2Fxls2csv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitsuki31%2Fxls2csv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitsuki31%2Fxls2csv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitsuki31%2Fxls2csv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitsuki31","download_url":"https://codeload.github.com/mitsuki31/xls2csv/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitsuki31%2Fxls2csv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35178403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-app","csv","csv-export","excel","excel-automation","python-cli","python3"],"created_at":"2026-07-06T05:01:01.885Z","updated_at":"2026-07-06T05:01:02.543Z","avatar_url":"https://github.com/mitsuki31.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xls2csv\n\nA minimal CLI tool to convert Excel files into CSV format written in Python v3.\n\nDesigned for reliability in operational environments where redundant, portable backups (CSV) are required alongside primary spreadsheet workflows.\n\n---\n\n## Overview\n\nIn many office and accounting workflows, data is often stored in Excel and synced via cloud providers (e.g. OneDrive). While convenient, this setup introduces a single point of failure.\n\nThis tool provides a simple fallback mechanism:\n\n- Convert Excel files into plain CSV\n- Export all sheets or specific ones\n- Batch process entire directories\n- Generate consistent, scriptable outputs\n\nThe focus is not feature richness, but **predictable, safe conversion**.\n\n\u003e [!IMPORTANT]  \n\u003e In case you didn't know, converting Excel files to CSV format **will lose the formatting, formulas, etc**.\n\u003e\n\u003e It will only stores the calculated values of the cells.\n\nBy converting to CSV, you can have an emergency backup of your Excel data that can be saved locally (e.g., USB drive).\n\n---\n\n## Features\n\n- **Lightweight** – Designed with minimal dependencies for easy setup and maintenance\n- **Excel to CSV Conversion** – Convert a single Excel file into CSV format\n- **Batch Processing** – Convert entire folders of Excel files in one command\n\n### Supported Excel Files\n\n| File Type                     | Extension | Supported |\n| ----------------------------- | :-------- | :-------: |\n| Excel 97-2003 Workbook        | `.xls`    | ❌        |\n| Excel Workbook                | `.xlsx`   | ✅        |\n| Excel Macro-Enabled Workbook  | `.xlsm`   | ✅        |\n| Excel Binary Workbook         | `.xlsb`   | ✅        |\n| Excel Open XML Spreadsheet    | `.ods`    | ❌        |\n\n### Export Options\n\n- Active sheet (default behavior)\n- Specific sheet using `--sheet`\n- All sheets using `--all-sheets`\n\n### Output Flexibility\n\n- Save to a file in single-file mode\n- Save to a directory in batch mode\n- Optional template-based naming for generated files (`--template`)\n\n### Additional Benefits\n\n- **Cross-platform support** – Works seamlessly on Windows, Linux, and macOS\n- **Memory efficient** – Uses read-only processing to keep memory usage low\n\n---\n\n## Project Inspiration\n\nThis project originated from a practical issue encountered while managing financial data backups in a local workflow.\n\n\u003e [!IMPORTANT]  \n\u003e Please take as important note, **DO NOT** upload any sensitive files such as company financial data\n\u003e either to public or private repository which may be violating the company policy and I'm not responsible for that.\n\nAn initial approach involved using Git for versioning Excel files. However, since Excel formats (e.g., `.xlsx`) are binary, even small changes resulted in large diffs and rapid growth of the `.git` directory when committed directly without [**Git LFS**](https://git-lfs.com/). This made the repository inefficient and difficult to maintain over time.\n\nTo address this, a simple conversion step was introduced: transform Excel files into CSV before committing. Unlike binary formats, CSV files are text-based, enabling meaningful diffs, smaller repository size, and better traceability of changes.\n\nWhat began as a small utility script evolved into a dedicated CLI tool focused on one purpose—providing a reliable way to generate lightweight, version-friendly backups from spreadsheet data.\n\n---\n\n## Installation\n\n### Prerequisites\n\nEnsure you have [**Python 3.10**](https://www.python.org/downloads/) ([see release notes](https://www.python.org/downloads/release/python-31020/)) or higher installed.\n\nThat's all you need, really.\n\n### Option 1 — Recommended (`pipx`)\n\n[`pipx`](https://pipx.pypa.io/stable/) is a tool for installing and running Python applications in isolated environments. Best for Ubuntu 23.04+, Debian 12+, and Fedora 38+ (these are distros that adopts [PEP 668](https://peps.python.org/pep-0668/)).\n\n#### Install `pipx`\n\nFor Unix users:\n\n```bash\nsudo apt install pipx\n```\n\n\u003e [!NOTE]  \n\u003e For **Termux** (Android) users, you don't need to use `sudo` to install package.  \n\u003e Just run `pkg install pipx` instead.\n\nFor Windows users:\n\n```powershell\npython -m pip install pipx \u0026\u0026 python -m pipx ensurepath\n```\n\n\u003e Or, check [`pipx` installation guide](https://pipx.pypa.io/stable/how-to/install-pipx/) for more information on how to install `pipx`.\n\n#### Install `xls2csv`\n\n```bash\npipx install git+https://github.com/mitsuki31/xls2csv.git@latest\n```\n\n#### Verify installation\n\n```bash\nxls2csv --version\n```\n\n---\n\n### Option 2 — `pip` (global or user install)\n\n\u003e [!WARNING]  \n\u003e Recommended to use `pipx` instead, `pip` can sometimes cause dependency conflicts in some environments.\n\n```bash\npip install git+https://github.com/mitsuki31/xls2csv.git@latest\n```\n\u003e You may need `--user` depending on your environment.\n\nAfter installation:\n\n```bash\nxls2csv --version\n```\n\n---\n\n## Usage\n\n### Basic syntax\n\n```bash\nxls2csv [OPTIONS] INPUT_PATH\n```\n\n`INPUT_PATH` determines behavior:\n\n- File → single conversion\n- Directory → batch conversion\n\nSee [options](#options--behavior) for more detailed information.\n\n\u003e [!NOTE]  \n\u003e - Sheet names are sanitized for filesystem compatibility\n\u003e   - For example: `April/2026` → `April_2026`\n\u003e - Empty or invalid Excel files will raise errors\n\u003e - CSV encoding is set to UTF-8\n\u003e - Read-only Excel loading for lower memory usage\n\n---\n\n## Examples\n\n### Convert single file\n\n```bash\nxls2csv report.xlsx\n```\n\n\u003e [!NOTE]  \n\u003e If you don't specify the output file, it will be saved in the same folder as the input file.\n\n### Convert to specific output file\n\n```bash\nxls2csv report.xlsx -o output.csv\n```\n\n\u003e [!NOTE]  \n\u003e The `-o` / `--output` option accepts either a file path or a directory:  \n\u003e - If a file extension is provided (e.g. `a/b/c.csv`), the output is written to that file.  \n\u003e - If no extension is provided, the value is treated as a directory.\n\n### Convert all sheets\n\n```bash\nxls2csv report.xlsx --all-sheets\n```\n\n### Convert specific sheet\n\n```bash\nxls2csv report.xlsx -s 2026-01\n```\n\n### Batch convert a folder\n\n```bash\nxls2csv ./reports\n```\n\n### Batch with output directory\n\n```bash\nxls2csv ./reports -o ./out\n```\n\n### Convert with template\n\n```bash\nxls2csv report.xlsx -t 'output-%(name)-%(sheet).csv'\n```\n\n---\n\n## Options \u0026 Behavior\n\n| Option                         | Description                                                            |\n| ------------------------------ | ---------------------------------------------------------------------- |\n| `-o, --output`                 | Output file (single mode) or directory                                 |\n| `-t, --template`               | Template for output file name (default: `'%(name)-[%(sheet)].%(ext)'`) |\n| `-s, --sheet`                  | Convert specific sheet                                                 |\n| `--all-sheets`                 | Export all sheets                                                      |\n| `-f`, `--force`, `--overwrite` | Overwrite existing files                                               |\n| `-v`, `--version`              | Show version information                                               |\n| `--help`                       | Show help message                                                      |\n\n---\n\n### Single file mode\n\n| Input         | Output                |\n| ------------- | --------------------- |\n| No `-o`       | Same folder as source |\n| `-o file.csv` | Exact file            |\n| `-o folder/`  | File inside folder    |\n\n---\n\n### Batch mode\n\n| Input         | Output                |\n| ------------- | --------------------- |\n| No `-o`       | Same folder           |\n| `-o folder/`  | All files saved there |\n| `-o file.csv` | ❌ Invalid             |\n\n---\n\n### Output File Placeholder\n\nYou can specify a placeholder in the output file name using `--template` option.\n\n| Placeholder  | Description                                              |\n|--------------|----------------------------------------------------------|\n| `%(name)`    | The filename of the input file                          |\n| `%(sheet)`   | The sheet name of the input file                        |\n| `%(ext)`     | The extension of the output file (always `csv`)         |\n| `%(date)`    | The current date in `YYYY-MM-DD` format                 |\n| `%(year)`    | The current year in `YYYY` format                       |\n| `%(month)`   | The current month in `MM` format                        |\n| `%(day)`     | The current day in `DD` format                          |\n| `%(day_s)`   | The current day of the week in `DDD` format (e.g., Mon) |\n\nExample:\n\n```bash\nxls2csv report.xlsx -t 'output-%(name)-%(sheet).%(ext)'\n```\n\n\u003e [!TIP]  \n\u003e The `%(date)` placeholder is a shortcut for `'%(year)-%(month)-%(day)'`.\n\n\u003e [!NOTE]  \n\u003e Default template string for the output file is `'%(name)-[%(sheet)].%(ext)'`.\n\u003e\n\u003e Example output file:\n\u003e ```text\n\u003e report-[Sheet1].csv\n\u003e ```\n\n---\n\n## Development\n\n### Setup virtual environment\n\n- Unix\n  ```bash\n  ./setup.sh \u0026\u0026 . .venv/bin/activate\n  ```\n\n- Windows (PowerShell)\n  ```pwsh\n  .\\setup.ps1\n  ```\n\n### Install dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Run the CLI\n\n```bash\nxls2csv --version\n```\n\n---\n\n## Testing\n\nAll tests are located in the `tests/` directory. To run all tests, use `pytest`:\n\n```bash\npytest -vv\n```\n\n---\n\n## License\n\n\u0026copy; 2026 [Ryuu Mitsuki](https://github.com/mitsuki31).\nLicensed under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitsuki31%2Fxls2csv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitsuki31%2Fxls2csv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitsuki31%2Fxls2csv/lists"}