Initialize a new Python project with recommended defaults, including:

• a pyproject.toml file and relevant configuration,
• recommended linters, formatters, spellcheckers, and test frameworks (all opt-out),
• a recommended type checker (opt-in),
• docstring style enforcement (opt-in),
• a recommended git hook framework (opt-in),
• CI services (opt-in),
• declared & installed dependencies via uv add, and
• any other relevant directories or tool-bespoke configuration files.

Supported options:

• --arch to add recommended architecture analysis tools (but the default is --no-arch)

• --doc to add recommended documentation tools (default; or --no-doc to opt-out)

• --format to add recommended formatters (default; or --no-format to opt-out)

• --lint to add recommended linters (default; or --no-lint to opt-out)

• --spellcheck to add a recommended spellchecker (default; or --no-spellcheck to opt-out)

• --test to add a recommended testing framework (default; or --no-test to opt-out)

• --typecheck to add a recommended type checker (but the default is --no-typecheck)

• --hook to add a recommended git hook framework (but the default is --no-hook)

• --docstyle to set a docstring style convention for the project.

  Possible values:

  • numpy for NumPy docstring style
  • google for Google docstring style
  • pep257 for PEP 257 docstring style

• --status to set the development status of the project. Defaults to planning.

  Possible values:

  • planning or 1 for "Development Status :: 1 - Planning"
  • pre-alpha or 2 for "Development Status :: 2 - Pre-Alpha"
  • alpha or 3 for "Development Status :: 3 - Alpha"
  • beta or 4 for "Development Status :: 4 - Beta"
  • production or 5 for "Development Status :: 5 - Production/Stable"
  • mature or 6 for "Development Status :: 6 - Mature"
  • inactive or 7 for "Development Status :: 7 - Inactive"

• --offline to disable network access and rely on caches

• --quiet to suppress output

• --frozen to leave the virtual environment and lockfile unchanged (i.e. do not install dependencies, nor update lockfiles)

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

• --build-backend to specify the build backend for the project. Defaults to hatch.

  Possible values:

  • hatch for Hatchling (default)
  • uv for uv

Add recommended architecture analysis tools to the project (namely, Import Linter), including:

• declared & installed dependencies via uv add,
• relevant configuration, and
• any other relevant directories or tool-bespoke configuration files.

Note if pyproject.toml is not present, it will be created, since this is required for declaring dependencies via uv add.

Supported options:

• --remove to remove the tool instead of adding it

• --how to only print how to use the tool, with no other side effects

• --offline to disable network access and rely on caches

• --frozen to leave the virtual environment and lockfile unchanged

• --quiet to suppress output

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

See usethis tool for more information.

Add recommended documentation tools to the project (namely, MkDocs), including:

• declared & installed dependencies via uv add,
• relevant pyproject.toml configuration, and
• any other relevant directories or tool-bespoke configuration files.

Note if pyproject.toml is not present, it will be created, since this is required for declaring dependencies via uv add.

Supported options:

• --remove to remove the tool instead of adding it
• --how to only print how to use the tool, with no other side effects
• --offline to disable network access and rely on caches
• --frozen to leave the virtual environment and lockfile unchanged
• --quiet to suppress output

See usethis tool for more information.

Add recommended formatters to the project (namely, Ruff and pyproject-fmt), including:

• declared & installed dependencies via uv add,
• relevant pyproject.toml configuration, and
• any other relevant directories or tool-bespoke configuration files.

Note if pyproject.toml is not present, it will be created, since this is required for declaring dependencies via uv add.

Supported options:

• --remove to remove the tool instead of adding it

• --how to only print how to use the tool, with no other side effects

• --offline to disable network access and rely on caches

• --frozen to leave the virtual environment and lockfile unchanged

• --quiet to suppress output

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

See usethis tool for more information.

Add a recommended git hook framework to the project (namely, pre-commit), including:

• declared & installed dependencies via uv add,
• relevant configuration, and
• any other relevant directories or tool-bespoke configuration files.

Note if pyproject.toml is not present, it will be created, since this is required for declaring dependencies via uv add.

Supported options:

• --remove to remove the tool instead of adding it

• --how to only print how to use the tool, with no other side effects

• --offline to disable network access and rely on caches

• --frozen to leave the virtual environment and lockfile unchanged

• --quiet to suppress output

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

See usethis tool for more information.

Add recommended linters to the project (namely, Ruff and deptry), including:

• declared & installed dependencies with uv add,
• relevant pyproject.toml configuration, and
• any other relevant directories or tool-bespoke configuration files.

Note if pyproject.toml is not present, it will be created, since this is required for declaring dependencies with uv add.

Supported options:

• --remove to remove the tool instead of adding it

• --how to only print how to use the tool, with no other side effects

• --offline to disable network access and rely on caches

• --frozen to leave the virtual environment and lockfile unchanged

• --quiet to suppress output

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

See usethis tool for more information.

Add a recommended spellchecker to the project (namely, codespell), including:

• declared & installed dependencies with uv add,
• relevant pyproject.toml configuration, and
• any other relevant directories or tool-bespoke configuration files.

Note if pyproject.toml is not present, it will be created, since this is required for declaring dependencies with uv add.

Supported options:

• --remove to remove the tool instead of adding it
• --how to only print how to use the tool, with no other side effects
• --offline to disable network access and rely on caches
• --frozen to leave the virtual environment and lockfile unchanged
• --quiet to suppress output
• --backend to specify a package manager backend to use. The default is to auto-detect. Possible values:
  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

See usethis tool for more information.

Add a recommended testing framework to the project (namely pytest), including:

• declared & installed dependencies with uv add,
• relevant pyproject.toml configuration, and
• any other relevant directories or tool-bespoke configuration files.

Note if pyproject.toml is not present, it will be created, since this is required for declaring dependencies with uv add.

Supported options:

• --remove to remove the tool instead of adding it
• --how to only print how to use the tool, with no other side effects
• --offline to disable network access and rely on caches
• --frozen to leave the virtual environment and lockfile unchanged
• --quiet to suppress output
• --backend to specify a package manager backend to use. The default is to auto-detect. Possible values:
  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

See usethis tool for more information.

Add a recommended type checker to the project (namely, ty), including:

• declared & installed dependencies with uv add,
• relevant configuration, and
• any other relevant directories or tool-bespoke configuration files.

Note if pyproject.toml is not present, it will be created, since this is required for declaring dependencies with uv add.

Supported options:

• --remove to remove the tool instead of adding it

• --how to only print how to use the tool, with no other side effects

• --offline to disable network access and rely on caches

• --frozen to leave the virtual environment and lockfile unchanged

• --quiet to suppress output

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

See usethis tool for more information.

Add a new tool to a Python project, including:

• declared & installed dependencies with uv add,
• relevant pyproject.toml configuration,
• any other relevant directories or tool-bespoke configuration files, and
• .pre-commit-config.yaml configuration if using pre-commit.

Note if pyproject.toml is not present, it will be created, since this is required for declaring dependencies with uv add.

• usethis tool codespell - Use the codespell spellchecker: detect common spelling mistakes.
• usethis tool deptry - Use the deptry linter: avoid missing or superfluous dependency declarations.
• usethis tool import-linter - Use Import Linter: enforce a self-imposed architecture on imports.
• usethis tool pre-commit - Use the pre-commit framework to manage and maintain Git hooks. Note that this will also install all the hooks to Git.
• usethis tool pyproject-fmt - Use the pyproject-fmt formatter: opinionated formatting of 'pyproject.toml' files.
• usethis tool ruff - Use Ruff: an extremely fast Python linter and code formatter.
• usethis tool ty - Use ty: an extremely fast Python type checker.

• usethis tool coverage.py - Use Coverage.py: a code coverage measurement tool.
• usethis tool pytest - Use the pytest testing framework.

• usethis tool mkdocs - Use MkDocs: Generate project documentation sites with Markdown.

• usethis tool pyproject.toml - Use a pyproject.toml file to configure the project.
• usethis tool requirements.txt - Use a requirements.txt file exported from the uv lockfile.

Supported options:

• --remove to remove the tool instead of adding it

• --how to only print how to use the tool, with no other side effects

• --no-hook to skip adding or modifying git hook configuration (e.g. pre-commit)

• --offline to disable network access and rely on caches

• --frozen to leave the virtual environment and lockfile unchanged

• --quiet to suppress output

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

For usethis tool ruff, in addition to the above options, you can also specify:

• --linter to add or remove specifically the linter component of Ruff (default; or --no-linter to opt-out)
• --formatter to add or remove specifically the formatter component of Ruff (default; or --no-formatter to opt-out)

Add badges to the README file.

Currently supported badges:

• usethis badge bitbucket -
• usethis badge pre-commit -
• usethis badge pypi -
• usethis badge ruff -
• usethis badge socket -
• usethis badge ty -
• usethis badge usethis -
• usethis badge uv -

Supported options:

• --show to show the badge URL instead of adding (or removing) it
• --remove to remove the badge instead of adding it
• --offline to disable network access and rely on caches
• --quiet to suppress output

Add a README.md file to the project.

Supported options:

• --badges to also add badges to the README.md file

• --quiet to suppress output

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

Set new author information for the project.

Required options:

• --name for the new author's name

Other supported options:

• --email to set the author email address

• --overwrite to overwrite all existing author information

• --quiet to suppress output

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

Set a docstring style convention for the project, and enforce it with Ruff.

Defaults to the Google docstring style.

Possible style options:

• numpy for NumPy docstring style
• google for Google docstring style
• pep257 for PEP 257 docstring style

Example:

usethis docstyle google

Supported options:

• --offline to disable network access and rely on caches

• --quiet to suppress output

• --frozen to leave the virtual environment and lockfile unchanged (i.e. do not install dependencies, nor update lockfiles)

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

Add (or manage configuration) of Ruff and Deptry rules in pyproject.toml.

See the Ruff documentation for a list of available rules, and the Deptry documentation for a list of available rules.

Example:

usethis rule RUF001

Supported options:

• --remove to remove the rule selection or ignore status.

• --ignore to add the rule to the ignore list (or remove it if --remove is specified).

• --offline to disable network access and rely on caches

• --quiet to suppress output

• --backend to specify a package manager backend to use. The default is to auto-detect.

  Possible values:

  • auto to auto-detect the backend (default)
  • uv to use the uv package manager
  • none to not use a package manager backend and display messages for some operations.

Set the development status of the project via trove classifiers.

Possible values (required):

• usethis status planning or usethis status 1 for "Development Status :: 1 - Planning"
• usethis status pre-alpha or usethis status 2 for "Development Status :: 2 - Pre-Alpha"
• usethis status alpha or usethis status 3 for "Development Status :: 3 - Alpha"
• usethis status beta or usethis status 4 for "Development Status :: 4 - Beta"
• usethis status production or usethis status 5 for "Development Status :: 5 - Production/Stable"
• usethis status mature or usethis status 6 for "Development Status :: 6 - Mature"
• usethis status inactive or usethis status 7 for "Development Status :: 7 - Inactive"

Supported options:

• --badges to add an associated badge to the README file
• --quiet to suppress output

Display a table of all available tools and their current usage status.

Display the current version of usethis.

Show a piece of information about the project.

Currently supported subcommands:

• usethis show backend to show the inferred project manager backend, e.g. 'uv' or 'none'. This is the default backend used, i.e. when --backend=auto is specified.
• usethis show name to show the name of the project.
• usethis show sonarqube to show appropriate contents of a sonar-project.properties file for SonarQube analysis.

Show the contents of a sonar-project.properties file for SonarQube analysis.

If a sonar-project.properties file already exists in the project root, its contents are returned as-is. In this case, the --project-key option and tool.usethis.sonarqube.project-key in pyproject.toml are both ignored.

If no sonar-project.properties file exists, the contents are constructed from pyproject.toml configuration. In this case, a project key is required:

• If --project-key is provided, it is used.
• Otherwise, tool.usethis.sonarqube.project-key from pyproject.toml is used.

Additional configuration in pyproject.toml:

• tool.usethis.sonarqube.verbose (bool, default false) — sets sonar.verbose.
• tool.usethis.sonarqube.exclusions (list of strings, default []) — sets sonar.exclusions.
• tool.coverage.xml.output (string, required) — sets sonar.python.coverage.reportPaths.

Supported options:

• --output-file to write the output to a file instead of stdout.

Display or open the PyPI landing page associated with another project.

Example:

usethis browse pypi numpy

Supported options:

• --browser to open the link in the browser automatically.