View on GitHub


Tool to automatically replace 'import *' in Python files with explicit imports


Actions Status PyPI version Anaconda-Server Badge PyPI platforms Downloads Conda Downloads Ruff

Tool to automatically replace import * imports in Python files with explicit imports


Install removestar globally to use it through CLI using pypi -

pip install removestar

or conda -

conda install -c conda-forge removestar

or add removestar in .pre-commit-config.yaml -

- repo:
  rev: "1.5"
    - id: removestar
      args: [-i] # See docs for all args (-i edits file in-place)
      additional_dependencies: # The libraries or packages your code imports
        - ... # Should be . if running inside a library (to install the library itself in the environment)


pre-commit hook

Once removestar is added in .pre-commit-config.yaml, executing the following will always run it (and other pre-commits) before every commit -

pre-commit install

Optionally, the pre-commits (including removestar) can be manually triggered for all the files using -

pre-commit run --all-files


# scripts

$ removestar # Shows diff but does not edit

$ removestar -i # Edits in-place

$ removestar -i module/ # Modifies every Python file in module/ recursively

# notebooks

$ removestar file.ipynb # Shows diff but does not edit file.ipynb

$ removestar -i file.ipynb # Edits file.ipynb in-place

Why is import * so bad?

Doing from module import * is generally frowned upon in Python. It is considered acceptable when working interactively at a python prompt, or in files (removestar skips files by default).

Some reasons why import * is bad:

Here are some official Python references stating not to use import * in files:

Unfortunately, if you come across a file in the wild that uses import *, it can be hard to fix it, because you need to find every name in the file that is imported from the *. Removestar makes this easy by finding which names come from * imports and replacing the import lines in the file automatically.

One exception where import * can be bneficial: At the early stages of code development, a definite set of required functions can be difficult to determine. In such a context, wildcard imports could be beneficial by avoiding constantly curating the set of required functions. For example, at the development stage usage of from os.path import * can save time from curating required functions. Post-development, the wld card imports could be determined using removestar. Having said that, because of the multiple said reasons, wildcard imports should be avoided.


Suppose you have a module mymod like



# mymod/
from .b import *

def func(x):
    return x + y
# mymod/
x = 1
y = 2

Then removestar works like:

$ removestar mymod/

--- original/mymod/
+++ fixed/mymod/
@@ -1,5 +1,5 @@
 # mymod/
-from .b import *
+from .b import y

 def func(x):
     return x + y

This does not edit by default. The -i flag causes it to edit in-place:

$ removestar -i mymod/
$ cat mymod/
# mymod/
from .b import y

def func(x):
    return x + y

Command line options

$ removestar --help
usage: removestar [-h] [-i] [--version] [--no-skip-init]
                  [--no-dynamic-importing] [-v] [-q]
                  [--max-line-length MAX_LINE_LENGTH]
                  PATH [PATH ...]

Tool to automatically replace "import *" imports with explicit imports

Requires pyflakes.


$ removestar # Shows diff but does not edit

$ removestar -i # Edits in-place

$ removestar -i module/ # Modifies every Python file in module/ recursively

positional arguments:
  PATH                  Files or directories to fix

optional arguments:
  -h, --help            show this help message and exit
  -i, --in-place        Edit the files in-place. (default: False)
  --version             Show removestar version number and exit.
  --no-skip-init        Don't skip files (they are skipped by
                        default) (default: True)
                        Don't dynamically import modules to determine the list
                        of names. This is required for star imports from
                        external modules and modules in the standard library.
                        (default: True)
  -v, --verbose         Print information about every imported name that is
                        replaced. (default: False)
  -q, --quiet           Don't print any warning messages. (default: False)
  --max-line-length MAX_LINE_LENGTH
                        The maximum line length for replaced imports before
                        they are wrapped. Set to 0 to disable line wrapping.
                        (default: 100)

Whitelisting star imports

removestar does not replace star import lines that are marked with Flake8 noqa comments that permit star imports (F401 or F403).

For example, the star imports in this module would be kept:

from os import *  # noqa: F401
from .b import *  # noqa

def func(x):
    return x + y

Current limitations


See the issue tracker. Pull requests are welcome.


See the CHANGELOG file.