is there a reason why script_location is required for developing with alembic.config.Config, but assumed when just using the commandline alembic

[jvanasco]

An .ini file does not require script_location = alembic when invoking via alembic on the commandline - but it is required when creating loading that file into a config.Config object programmatically.

Is this on purpose or just a quirk?

A workaround is easy, but I'm just wondering if I've hit an antipattern.

CONFIG_file = os.path.join(data_dir, "config.ini")
CONFIG = Config(CONFIG_file)
if not CONFIG.get_section_option("alembic", "script_location"):
    CONFIG.set_section_option("alembic", "script_location", "alembic")

[zzzeek]

script location is always needed otherwise alembic has no way to know anything about the current revision tree

[jvanasco]

I think I may have confused you, and I may have stumbled onto a weird implementation detail

Using alembic programmatically, via configObj = alembic.config.Config(CONFIG_FILE) requires script_location in the .ini

Using the executable alembic, via alembic -c {CONFIG_FILE}, does NOT require script_location in the same .ini - it defaults to "alembic".

I have not been able to find where the executable sets or interprets a default value of 'alembic'.

So it's the same config file, but script_location is required in one context and not required in the other.

[zzzeek]

I think I may have confused you, and I may have stumbled onto a weird implementation detail

well yeah because everything you say there seems exactly backwards! :)

Using alembic programmatically, via configObj = alembic.config.Config(CONFIG_FILE) requires script_location in the .ini

define "required"? Stack trace? there's no such requirement for a config:

[classic@framework alembic:main]$ touch some_config_file.ini    # <--- blank
[classic@framework alembic:main]$ PYTHONPATH=~/dev/sqlalchemy/lib/ python
Python 3.13.7 (main, Aug 14 2025, 00:00:00) [GCC 14.3.1 20250523 (Red Hat 14.3.1-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from alembic import config
>>> cfg = config.Config("some_config_file.ini")
>>>  # all is well!

Using the executable alembic, via alembic -c {CONFIG_FILE}, does NOT require script_location in the same .ini - it defaults to "alembic".

it....doesnt? for operations that need the script location, it will raise:

[classic@framework alembic:main]$ PYTHONPATH=~/dev/sqlalchemy/lib/ python -m alembic  -c some_config_file.ini history  
  FAILED: No 'script_location' key found in configuration.

for operations that dont need it, it is fine:

$ PYTHONPATH=~/dev/sqlalchemy/lib/ python -m alembic  -c some_config_file.ini list_templates
Available templates:

generic - Generic single-database configuration.
multidb - Rudimentary multi-database configuration.
async - Generic single-database configuration with an async dbapi.
pyproject - pyproject configuration, based on the generic configuration.
pyproject_async - pyproject configuration, with an async dbapi.

Templates are used via the 'init' command, e.g.:

  alembic init --template generic ./scripts

I have not been able to find where the executable sets or interprets a default value of 'alembic'.

funny that! :)

[jvanasco]

I only have "sqlalchemy.url" in my "[alembic]" config.

This works as expected:

alembic -c data_testing/config.ini history

Invoking programmatically:

import sys

from alembic.config import Config
from alembic.script import ScriptDirectory

CONFIG_file = sys.argv[1]
fix_script_location = False
if len(sys.argv) == 3:
    fix_script_location = True

CONFIG = Config(CONFIG_file)

if fix_script_location:
    if not CONFIG.get_section_option("alembic", "script_location"):
        CONFIG.set_section_option("alembic", "script_location", "alembic")

script = ScriptDirectory.from_config(CONFIG)

for sc in script.walk_revisions(base="base", head="heads"):
    print(sc.revision)

fails:

jvanasco$ python script_location.py data_testing/config.ini

Traceback (most recent call last):
  File "/Volumes/Development/alembic_test/script_location.py", line 12, in <module>
    script = ScriptDirectory.from_config(CONFIG)
  File "/Users/jvanasco/dev-env/alembic_test-3.10.2/lib/python3.10/site-packages/alembic/script/base.py", line 175, in from_config
    raise util.CommandError(
alembic.util.exc.CommandError: No 'script_location' key found in configuration.

passes:

jvanasco$ python script_location.py data_testing/config.ini fix_script_location

[zzzeek]

I only have "sqlalchemy.url" in my "[alembic]" config.

This works as expected:

alembic -c data_testing/config.ini history

do you have a pyproject.toml with an alembic section floating around?

[jvanasco]

for forks sake, that was it. sorry, again, mike.

this was driving me crazy yesterday, because alembic -c should have raised that same error.

[zzzeek]

yeah i may have made a design error when i made it so that it continues to look for a pyproject.toml even if you gave it the -c argument. it was kind of rough to decide how all of that would work

[jvanasco]

I think you made the right call with the current behavior. That's a common pattern in the Python ecosystem and incredibly useful to provide universal default values. The only issue with it, IMHO, is that there is rarely any logging (if ever) that a file was detected and is being used for values. The most common pattern is for people to not realize this is happening and/or forget that this happens.

I've been bitten by this countless times and should have known better 🤷‍♂️

[CaselIT]

we could definitely add logging for this "loading config from file XYX"