varname

library1.0.0pypypi✓ verified 86d ago

Varname is a Python library that provides 'dark magics' to retrieve the names of variables, arguments, and expressions at runtime. It's currently at version 0.15.1, offering functions like `varname()`, `nameof()`, and `argname()` to simplify introspection and debugging. The library maintains an active release cadence, with recent updates focusing on improved expression parsing and Python version compatibility.

testing

pip install varname

github ↗package ↗

INSTALL

IMPORT

SIG · VARNAME

varname

testingpythonv1.0.0

Install

1.7s avg

Import

58ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.061s · 18.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.7s · import 0.056s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

varname

✓ from varname import varname

nameof

✓ from varname import nameof

✗ from varname.core import nameof

`nameof` is directly available from the top-level package since 0.15.0, after being deprecated and re-introduced.

argname

✓ from varname import argname

jsobj

✓ from varname.helpers import jsobj

exec_code

✓ from varname.helpers import exec_code

✗ exec(code_string)

Use `exec_code` instead of Python's built-in `exec` when using `varname` to ensure source code is available at runtime.

Wrapper

✓ from varname.helpers import Wrapper

Useful for explicitly retaining variable names in dynamic contexts like loops.

This quickstart demonstrates the core `varname()` functionality, including the enhanced subscript support introduced in v0.15.1, and basic usage of `nameof()` and `argname()`.

import varname def func(): # varname() retrieves the name of the variable it's assigned to. return varname() x = 0 a = [object] * 5 # Before v0.15.1, this might raise ImproperUseError. # Now, it correctly prints 'a[x + 1]' (which evaluates to a[1]). a[x + 1] = func() print(f"Value at a[1]: {a[1]}") # Demonstrating other new subscript supports from v0.15.1 b = [] b.append(func()) print(f"Element in b: {b[0]}") # prints 'b.append(func())' # Using nameof to get an argument's name def process(my_arg): return varname.nameof(my_arg) result = process(x) print(f"Name of argument 'x': {result}") # Using argname to get argument names within a function def greet(name, message): return varname.argname('name', 'message') arg_names = greet('Alice', 'Hello') print(f"Argument names in greet: {arg_names}") # {'name': 'name', 'message': 'message'}

Debug

Known issues

breakingIn `varname` versions 0.13.0 and later, calling `varname()` on an attribute chain like `a.b` will return the full chain `"a.b"` instead of just the root variable name `"a"`.

fix

Adjust code expecting only the root variable name for attribute chains. If the old behavior is strictly required, pin `varname<0.13.0`.

affects: >=0.13.0

deprecated`nameof` was deprecated in version 0.14.0 (warned in 0.13.4), leading to its removal in that version. It was subsequently re-introduced in version 0.15.0.

fix

If you were on `0.14.0` and `nameof` was removed, upgrade to `varname>=0.15.0` to regain its functionality. If you were considering migrating from `nameof` due to the deprecation warning in `0.13.4`, note that it has been brought back.

affects: 0.14.0

gotchaPrior to version 0.15.1, using `varname()` within complex subscript assignments (e.g., `a[x + 1] = func()`) would raise an `ImproperUseError` due to limitations in parsing complex expressions.

fix

Upgrade to `varname>=0.15.1` for enhanced subscript support that handles dynamic indexing and more complex expressions.

affects: <0.15.1

gotcha`varname` relies heavily on AST analysis via the `executing` package, which may not work reliably with environments using other AST manipulation techniques or dynamic code execution like Python's built-in `exec()` function, `macropy`, `birdseye`, or `reticulate`.

fix

Avoid using `varname` in code executed via `exec()`. For such scenarios, use `varname.helpers.exec_code()` instead of the built-in `exec()` to ensure source code is available at runtime, which `varname` can then analyze.

affects: All versions

Errors

Common errors & fixes

ImproperUseError: varname() is used improperly.

This error often occurs when `varname()` is called within complex expressions, especially in versions prior to 0.15.1 when used in array/list subscripts or other non-direct assignments.

fix

Upgrade to `varname>=0.15.1` for better support of complex expressions. If upgrading is not an option, simplify the expression where `varname()` is called, or assign its result to a simple variable first.

AttributeError: module 'varname' has no attribute 'nameof'

This specific error indicates that you are likely using `varname==0.14.0`, where the `nameof` function was temporarily removed after deprecation.

fix

Upgrade to `varname>=0.15.0` to restore `nameof` functionality, as it was re-introduced in this version. Alternatively, refactor your code to use `varname.argname()` which can often achieve similar results, or use `varname()` if appropriate.

NameError: name 'my_variable' is not defined (when using varname inside certain loops or comprehensions)

`varname` can sometimes struggle to reliably retrieve variable names when they are created dynamically, assigned implicitly within loops (e.g., in a list comprehension or tight loop constructs), or when the assignment context is not a direct variable assignment.

fix

For scenarios where `varname.varname()` struggles, consider using `varname.helpers.Wrapper` to explicitly associate a value with its variable name. Example: `from varname.helpers import Wrapper; a = Wrapper(''); mydict = {val.name: val.value for val in [a]}`.

TypeError: exec_code() got an unexpected keyword argument 'sourcefile'

This may occur if `varname.helpers.exec_code()` is called with incorrect arguments or an older signature. The `sourcefile` argument, while present in some internal uses, might not be intended for direct user calls or its position changed.

fix

Ensure you are passing `code`, `globals` (e.g., `globals().copy()`), `locals` (e.g., `locals().copy()`) and any other specified arguments according to the current `varname` documentation. Avoid passing `sourcefile` unless explicitly required and documented for public API usage.

Upgrade

Version history

1.0.0latest on PyPI · released Apr 16, 2026

Audit

Dependencies

executingrequiredCore dependency for AST analysis, updated to v2.2.1 to fix Python 3.13 issues.

asttokensrequiredUsed for AST parsing, updated to version 3.0.0 in varname 0.14.0.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/pwwang/python-varname ↗

packagehttps://pypi.org/project/varname/ ↗