PyClean — Python Formatter & Linter for VS Code

Privacy-first Python code beautifier — runs entirely on your machine.
Formats with Black + Ruff, shows an interactive diff before touching your file, and never sends your code anywhere.

Features

• 🧹 One-command cleanup — Ruff auto-fixes lint issues, then Black enforces consistent style.
• 🔍 Safe diff preview — a side-by-side diff opens so you can review every change before it's applied, with clear Accept All / Reject All buttons.
• 🎯 Selection-only mode — format just the lines you selected, not the entire file.
• ✅ Syntax guard — files with syntax errors are never modified; PyClean tells you exactly where the error is.
• 🔒 100% local — no telemetry, no cloud, no accounts.
• ⚡ Auto-detects Python — works with virtualenvs, conda, pyenv, and the official VS Code Python extension.

Requirements

Tip: If you use a virtual environment, activate it or point pyclean.pythonPath at that environment's Python. PyClean uses the same interpreter to invoke Black and Ruff.

Quick Start

1. Open any .py file in VS Code.
2. Press Cmd+Shift+P (macOS) / Ctrl+Shift+P (Windows/Linux).
3. Type PyClean and choose a command.

Commands

All commands are also available via right-click → context menu inside any .py file.
The ✨ sparkle icon appears in the editor title bar for quick one-click access.

Beautify Workflow

Open .py file
     │
     ▼
 Syntax check (py_compile)
     │  ✗ syntax error → stop, show error
     │  ✔
     ▼
 Ruff --fix  (auto-fixable lint, import sorting, …)
     │
     ▼
 Black  (consistent style, line length, …)
     │
     ▼
 Diff preview ─── Accept All ──→ changes written to editor ✔
                └── Reject All ─→ nothing changed ✔

Set pyclean.showDiffBeforeApply: false to skip the diff and apply instantly.

Extension Settings

Search "pyclean" in VS Code Settings (Cmd+, / Ctrl+,):

Troubleshooting

Commands don't appear in Cmd+Shift+P

PyClean commands are filtered to Python files only. Make sure:

• The active editor contains a .py file.
• The language mode (bottom-right of VS Code) shows Python.

"Black not found" / "Ruff not found"

# Install for the Python VS Code is using:
python3 -m pip install black ruff

# Or point PyClean at a specific interpreter:
# Settings → pyclean.pythonPath = /path/to/your/python3

"file has syntax errors — fix them first"

Black and Ruff both refuse to process files with syntax errors, so PyClean stops early. Check the Output panel (View → Output → PyClean) — it shows the exact line and message from Python's compiler.

"Timed out" on large files

Increase pyclean.timeoutMs in Settings (e.g. to 30000 or 60000).

Changes applied to wrong file after diff preview

This was a known issue (VS Code's diff editor deactivated the source file). It is fixed in this version — PyClean now re-focuses the original editor before writing changes.

Installing from Source (Development)

# 1. Unzip / clone the project
cd pyclean-fixed

# 2. Install Node dependencies
npm install

# 3. Compile TypeScript
npm run compile

# 4. Open in VS Code
code .

# 5. Press F5 → Extension Development Host opens
#    Open any .py file and use Cmd+Shift+P → PyClean

Building the .vsix Package

npm run package
# → pyclean-0.1.0.vsix

code --install-extension pyclean-0.1.0.vsix

Project Structure

pyclean-fixed/
├── src/
│   ├── extension.ts    # Entry point — command registration & beautify logic
│   ├── pythonTools.ts  # Python / Black / Ruff subprocess calls
│   ├── utils.ts        # Editor helpers (active editor, selection range)
│   └── preview.ts      # Diff preview with Accept All / Reject All buttons
├── media/
│   └── icon.png
├── .vscode/
│   ├── launch.json     # F5 debug config
│   └── tasks.json      # compile / watch tasks
├── package.json        # Extension manifest + npm scripts
├── tsconfig.json
└── README.md

Changelog

0.1.0

• Fixed: TextEditor#edit not possible on closed editors — PyClean now re-focuses the source editor after the diff view closes before writing changes.
• Added: Clear Accept All / Reject All modal buttons in the diff preview.
• Added: ✨ sparkle icon in editor title bar for one-click beautify.
• Improved: VS Code Marketplace listing — richer description, gallery banner, markdownDescription in all settings.
• Fixed: Beautify no longer blocked by lint issues (only syntax errors block formatting).
• Fixed: Python path auto-detects from VS Code Python extension, then python3, then python.
• Fixed: Ruff exit code 1 (unfixable lint remaining) no longer treated as an error.
• Improved: Cleaner error messages with actionable install instructions.