How can I prevent Click from expanding environment variables in command-line arguments?

Click itself doesn’t “magically” expand environment variables—you get the expansion because something in the conversion chain is calling Python’s own variable‐expansion (usually via os.path.expandvars) on values that look like paths. (This sometimes happens if you’re using a Click type that “resolves” paths.) In your example the argument is declared with type str so Click isn’t doing any conversion on its own; yet if you’re seeing expansion it means something is applying os.path.expandvars to your value.

There are a couple of ways to work around this:

---

1. Escape the Dollar Sign

If you want the literal "$M0/…" you can pass an escaped dollar sign. One common technique is to double the dollar sign so that when expansion occurs, your intended literal remains. For example:

BASHCopied
➜ Desktop python foo.py '$$M0/.viola/2025-01-25-17-20-23-307878'

When os.path.expandvars processes that string it will leave the "$M0" intact (or, more precisely, it won’t find an environment variable named an empty string before “M0”).

---

2. Use a Custom Parameter Type

If the expansion is happening because you’re using a type (like click.Path) that calls os.path.expandvars, you can bypass that by writing your own parameter type that just returns the string unmodified. For example:

PYTHONCopied
import click

class RawStr(click.ParamType):
    name = "raw"

    def convert(self, value, param, ctx):
        # Simply return the given value without any transformation.
        return value

raw = RawStr()

@click.command()
@click.argument("message", type=raw)
def main(message):
    click.echo(message)

if __name__ == '__main__':
    main()

Using this custom type, Click won’t try to resolve or expand the variable.

---

What to Check

Before applying one of the workarounds, double‑check that you’re not inadvertently using a type (like click.Path) or setting (for example, auto_envvar_prefix on a group) that instructs Click to expand environment variables. If you are simply using type=str then it really should be receiving the literal string from the shell. (Remember that in many shells environment variables aren’t expanded if you use single quotes.)

So the remedy is either to

• pass the value with an extra dollar sign (or otherwise escape it),
• or use a custom parameter type that doesn’t process the value further.

Choose the approach that best fits your application.