What causes "No local config file found" in python-poetry/poetry?

Drop `--local` to migrate the global config instead: `poetry config --migrate`.

python-poetry/poetry · error · RuntimeError

No local config file found

Error message

No local config file found

What it means

RuntimeError raised in `_migrate` (config.py:430-433) when `poetry config --migrate --local` is run but no `poetry.toml` exists in the project root. The local migration target is `path.parent / 'poetry.toml'`; absence makes migration meaningless.

Source

Thrown at src/poetry/console/commands/config.py:433

                message = (
                    f"<c1>{k + key}</c1> = <c2>{json.dumps(raw_val)}</c2>  # {value}"
                )
            else:
                message = f"<c1>{k + key}</c1> = <c2>{json.dumps(value)}</c2>"

            self.line(message)

    def _migrate(self) -> None:
        from poetry.config.file_config_source import FileConfigSource
        from poetry.locations import CONFIG_DIR
        from poetry.toml.file import TOMLFile

        config_file = TOMLFile(CONFIG_DIR / "config.toml")

        if self.option("local"):
            config_file = TOMLFile(self.poetry.file.path.parent / "poetry.toml")
            if not config_file.exists():
                raise RuntimeError("No local config file found")

        config_source = FileConfigSource(config_file)

        self.io.write_line("Checking for required migrations ...")

        required_migrations = [
            migration
            for migration in CONFIG_MIGRATIONS
            if migration.dry_run(config_source, io=self.io)
        ]

        if not required_migrations:
            self.io.write_line("Already up to date.")
            return

        if not self.io.is_interactive() or self.confirm(
            "Proceed with migration?: ", False
        ):

View on GitHub (pinned to 92b74dcfe3)

Solutions

Drop `--local` to migrate the global config instead: `poetry config --migrate`.
If a local config is intended, create `poetry.toml` first (e.g. `poetry config --local virtualenvs.in-project true`).
Run from the directory that actually contains `poetry.toml`.

Example fix

# before
poetry config --migrate --local   # no poetry.toml present
# after
poetry config --migrate            # migrate global config

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
local = Path.cwd() / "poetry.toml"
if not local.exists():
    raise SystemExit("no poetry.toml here; drop --local or create one first")

Type guard

def has_local_config(cwd: str | None = None) -> bool:
    from pathlib import Path
    return (Path(cwd or ".") / "poetry.toml").exists()

Prevention

Reserve `--local` for projects that already use a `poetry.toml`.
Create the file via `poetry config --local <key> <value>` first.
Document whether your project uses global or local config.

When it happens

Trigger: Running `poetry config --migrate --local` in a project that has never had a local `poetry.toml`.

Common situations: Running `--migrate --local` out of habit; expecting `pyproject.toml` to count as the local config (it does not — only `poetry.toml` does); wrong working directory.

Related errors

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/bacf3b16b06bcb76.json. Report an issue: GitHub.