{"id":8061,"library":"darker","title":"Darker: Incremental Python Code Formatter","description":"Darker (version 3.0.0) is a Python utility that applies code formatting (using tools like Black, Ruff, isort, Flynt, and pyupgrade) only to regions of Python files that have changed since the last Git commit. This allows for gradual style unification in existing projects without large, disruptive formatting commits. It is actively maintained with regular releases.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/akaihola/darker","tags":["formatter","code-quality","git","black","ruff","isort","pre-commit","incremental-formatting"],"install":[{"cmd":"pip install darker","lang":"bash","label":"Base installation"},{"cmd":"pip install 'darker[black]'","lang":"bash","label":"With Black formatter (recommended for most users)"},{"cmd":"pip install 'darker[ruff]'","lang":"bash","label":"With Ruff formatter"},{"cmd":"pip install 'darker[isort]'","lang":"bash","label":"With isort for import sorting"}],"dependencies":[{"reason":"Primary code formatter, no longer installed by default since v3.0.0.","package":"black","optional":true},{"reason":"Alternative code formatter, supported since v3.0.0.","package":"ruff","optional":true},{"reason":"For sorting imports.","package":"isort","optional":true},{"reason":"For converting old-style format strings to f-strings.","package":"flynt","optional":true},{"reason":"For upgrading Python syntax.","package":"pyupgrade","optional":true}],"imports":[],"quickstart":{"code":"# First, ensure you have a Git repository initialized and a Python file with changes\n# Example setup:\n# mkdir my_project && cd my_project && git init\n# echo \"print ( 'Hello, world' )\" > my_file.py\n# git add my_file.py && git commit -m \"Initial commit\"\n# echo \"def foo ( ):\\n    pass\\nprint ( 'Another line' )\" >> my_file.py\n\n# Format only the modified lines in 'my_file.py'\n# Requires black to be installed, e.g., pip install 'darker[black]'\nimport subprocess\nimport os\n\ndef run_darker(command):\n    try:\n        result = subprocess.run(command, capture_output=True, text=True, check=True)\n        print(result.stdout)\n        if result.stderr:\n            print(f\"Stderr: {result.stderr}\")\n    except subprocess.CalledProcessError as e:\n        print(f\"Command failed with exit code {e.returncode}\\nStdout: {e.stdout}\\nStderr: {e.stderr}\")\n\n# Assuming you are in a git repository with changes in my_file.py\n# This will reformat the added/modified lines in my_file.py\n# For this example to be runnable, ensure 'darker' and 'black' are installed and a Git repo exists.\n# To see an effect, modify my_file.py after an initial commit:\n#   echo \"def some_func (   ):\\n    x  =   1\" >> my_file.py\n# then run `python -m darker my_file.py`\n\nprint(\"Running darker on 'my_file.py'...\")\n# Use python -m darker to ensure it runs from the correct environment\nrun_darker(['python', '-m', 'darker', 'my_file.py'])\n\nprint(\"\\nShowing the diff without applying changes (dry run):\")\nrun_darker(['python', '-m', 'darker', '--diff', 'my_file.py'])\n\nprint(\"\\nApplying darker with isort on 'my_file.py' (if isort installed):\")\nrun_darker(['python', '-m', 'darker', '--isort', 'my_file.py'])\n","lang":"python","description":"To use Darker, navigate to your Git repository and run it on specific files or directories. This example demonstrates basic usage for formatting modified lines in a Python file and showing a diff. Ensure you have `darker` and its desired formatters (e.g., `black`) installed."},"warnings":[{"fix":"Move `skip_string_normalization` and `skip_magic_trailing_comma` from `[tool.darker]` to `[tool.black]` in your `pyproject.toml`.","message":"In Darker 3.0.0, the Black configuration options `skip_string_normalization` and `skip_magic_trailing_comma` are no longer supported under the `[tool.darker]` section in `pyproject.toml`. These options should now be configured directly under `[tool.black]` as per Black's configuration.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Migrate baseline linting workflows to use the `Graylint` package instead of `darker --lint`.","message":"The `--lint` / `-L` command-line option for baseline linting was removed in Darker 3.0.0. This functionality has been moved to the separate `Graylint` package.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Install Darker with the `black` extra: `pip install 'darker[black]'` or install Black separately: `pip install black`.","message":"Black, the default formatter, is no longer installed by default with `pip install darker` since version 3.0.0. If you intend to use Black, you must install it explicitly.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Pin `darker` and its integrated formatters/linters to compatible versions using `~=` in your `requirements.txt` or `pyproject.toml` and review Darker's release notes for known incompatibilities.","message":"Darker accesses internals of Black, Ruff, isort, and Flynt, which can lead to compatibility issues with newer versions of these tools. It is recommended to use the compatible release (`~=`) version specifier for Darker and regularly check release notes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For pre-commit, try `--revision :PRE-COMMIT:` in your hook configuration. Ensure your CI/CD environment correctly sets `PRE_COMMIT_FROM_REF` and `PRE_COMMIT_TO_REF` if relying on Darker's default behavior within a pre-commit context.","message":"When using Darker as a `pre-commit` hook, issues can arise with `git merge-base` or incorrect revision comparisons. Explicitly setting the `--revision` flag (e.g., `--revision :PRE-COMMIT:`) or ensuring `PRE_COMMIT_FROM_REF`/`PRE_COMMIT_TO_REF` environment variables are correctly set might be necessary.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure Darker is installed (`pip install darker`) and your virtual environment is activated, or use `python -m darker` to invoke it directly.","cause":"Darker is not installed or not available in the system's PATH. This can happen if installed in a virtual environment that isn't activated, or if the `scripts` directory isn't in PATH.","error":"Command 'darker' not found"},{"fix":"If you want Darker to apply the formatting, remove the `--check` or `--diff` flag. If you want to accept the current state, commit your code and then run `darker` again to confirm no new changes are detected.","cause":"This is not an error but an informational message, typically when running `darker` in `--check` or `--diff` mode, indicating that changes *would* be applied.","error":"Darker found files that need reformatting. Would format the following files:"},{"fix":"Install Black as an extra for Darker: `pip install 'darker[black]'`, or install Black separately: `pip install black`.","cause":"Since Darker 3.0.0, Black is no longer a default dependency. Darker attempts to run Black but cannot find the `black` executable or module.","error":"Error: Black is not installed. Install it with `pip install 'darker[black]'`"},{"fix":"Move `skip_string_normalization` (and `skip_magic_trailing_comma` if used) from the `[tool.darker]` section to the `[tool.black]` section in your `pyproject.toml`.","cause":"You are using an older configuration for Black options within `[tool.darker]` in your `pyproject.toml` which is no longer supported in Darker 3.0.0+.","error":"DeprecationWarning: The Black option 'skip_string_normalization' in section [tool.darker] is deprecated..."},{"fix":"Verify the file or directory path provided to Darker. Ensure there are no typos and the path is correct relative to where you are running the command.","cause":"Darker was instructed to format a file or directory that does not exist in the specified path.","error":"error: cannot stat 'non_existent_file.py': No such file or directory"}]}