usethis-python · nathanjmcdougall · Aug 3, 2025 · Jun 29, 2025 · Jun 30, 2025 · Jun 30, 2025
diff --git a/README.md b/README.md
@@ -25,9 +25,6 @@ usethis gives detailed messages about what it is doing (and what you need to do
 
 Inspired by an [**R** package of the same name](https://usethis.r-lib.org/index.html), this package brings a similar experience to the Python ecosystem as a CLI tool.
 
-> [!TIP]
-> usethis is great for fresh projects using [uv](https://docs.astral.sh/uv), but also supports updating existing projects. However, this should be considered experimental. If you encounter problems or have feedback, please [open an issue](https://github.com/usethis-python/usethis-python/issues/new?template=idea.md).
-
 ## Highlights
 
 - 🧰 First-class support for state-of-the-practice tooling: uv, Ruff, pytest, pre-commit, and many more.
@@ -40,10 +37,7 @@ Inspired by an [**R** package of the same name](https://usethis.r-lib.org/index.
 ## 🧭 Getting Started
 
 First, it is strongly recommended you [install the uv package manager](https://docs.astral.sh/uv/getting-started/installation/): this is a simple, documented process. If you're already using uv, make sure you're using at least
-version v0.6.8. To check this, run `uv self version` to check (if available, otherwise `uv version`), and run `uv self update` to upgrade.
-
-> [!TIP]
-> At the moment, usethis assumes you will have uv installed in some circumstances. Support for projects that don't use uv is planned for late 2025.
+version v0.6.8 (run `uv --version` to check, and `uv self update` to upgrade).
 
 You can install usethis directly into the project environment:
 
@@ -189,9 +183,8 @@ If you're using Cookiecutter, then you can update to a latest version of a templ
 
 Major features planned for later in 2025 are:
 
-- Support for users who aren't using uv, e.g. poetry users,
-- Support for automated GitHub Actions workflows ([#57](https://github.com/usethis-python/usethis-python/issues/57)), and
-- Support for a typechecker (likely Pyright, [#121](https://github.com/usethis-python/usethis-python/issues/121)).
+- Support for automated GitHub Actions workflows ([#57](https://github.com/usethis-python/usethis-python/issues/57)),
+- Support for a typechecker (likely Pyright, [#121](https://github.com/usethis-python/usethis-python/issues/121)), and
 
 Other features are tracked in the [GitHub Issues](https://github.com/usethis-python/usethis-python/issues) page.
 

diff --git a/docs/cli/reference.md b/docs/cli/reference.md
@@ -40,6 +40,11 @@ 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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 ## `usethis doc`
 
@@ -78,6 +83,11 @@ Supported options:
 - `--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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 See [`usethis tool`](#usethis-tool) for more information.
 
@@ -98,6 +108,11 @@ Supported options:
 - `--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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 See [`usethis tool`](#usethis-tool) for more information.
 
@@ -118,6 +133,11 @@ Supported options:
 - `--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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 See [`usethis tool`](#usethis-tool) for more information.
 
@@ -138,6 +158,11 @@ Supported options:
 - `--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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 See [`usethis tool`](#usethis-tool) for more information.
 
@@ -183,6 +208,11 @@ Supported options:
 - `--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](https://docs.astral.sh/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:
 
@@ -203,6 +233,11 @@ 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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 ## `usethis badge`
 
@@ -229,8 +264,13 @@ Add a README.md file to the project.
 
 Supported options:
 
-- `--quiet` to suppress output
 - `--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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 ## `usethis author`
 
@@ -245,6 +285,11 @@ 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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 ## `usethis docstyle <style>`
 
@@ -267,6 +312,11 @@ 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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 ## `usethis rule <rulecode>`
 
@@ -286,6 +336,11 @@ Supported options:
 - `--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](https://docs.astral.sh/uv) package manager
+  - `none` to not use a package manager backend and display messages for some operations.
 
 ## `usethis status <status>`
 
@@ -303,8 +358,8 @@ Possible values (required):
 
 Supported options:
 
-- `--quiet` to suppress output
 - `--badges` to add an associated badge to the README file
+- `--quiet` to suppress output
 
 ## `usethis list`
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,9 +1,7 @@
 # 🧭 Getting Started
 
 First, it is strongly recommended you [install the uv package manager](https://docs.astral.sh/uv/getting-started/installation/): this is a simple, documented process. If you're already using uv, make sure you're using at least
-version v0.6.8. To check this, run `uv self version` to check (if available, otherwise `uv version`), and run `uv self update` to upgrade.
-
-At the moment, usethis assumes you will have uv installed in some circumstances. Support for projects that don't use uv is planned for late 2025.
+version v0.6.8 (run `uv --version` to check, and `uv self update` to upgrade).
 
 You can install usethis directly into the project environment:
 

diff --git a/docs/index.md b/docs/index.md
@@ -12,8 +12,6 @@ usethis gives detailed messages about what it is doing (and what you need to do
 
 Inspired by an [**R** package of the same name](https://usethis.r-lib.org/index.html), this package brings a similar experience to the Python ecosystem as a CLI tool.
 
-usethis is great for fresh projects using [uv](https://docs.astral.sh/uv), but also supports updating existing projects. However, this should be considered experimental. If you encounter problems or have feedback, please [open an issue](https://github.com/usethis-python/usethis-python/issues/new?template=idea.md).
-
 ## Highlights
 
 - 🧰 First-class support for state-of-the-practice tooling: uv, Ruff, pytest, pre-commit, and many more.

diff --git a/pyproject.toml b/pyproject.toml
@@ -183,29 +183,35 @@ name = "usethis"
 type = "layers"
 layers = [
   "_test | __main__",
-  "_app",
-  "_interface",
-  "_options",
+  "_ui",
+  # Tool implementations
   "_toolset",
   "_core",
   "_tool",
+  # Specific config file and backend implementations
+  "_deps | _init",
   "_config_file",
   "_integrations",
-  "_io | _pipeweld | _subprocess | _console",
-  "_config | errors",
+  "_io | _subprocess | _console",
+  # Global state and constants
+  "_config",
+  "_types | errors",
+  # Completely independent helper modules
+  "_pipeweld",
 ]
 containers = [ "usethis" ]
 exhaustive = true
 exhaustive_ignores = [ "_version" ]
 
 [[tool.importlinter.contracts]]
-name = "usethis._interface"
+name = "usethis._ui"
 type = "layers"
 layers = [
-  # Note; if you're adding an interface, make sure it's in the README too.
-  "author | badge | browse | ci | doc | docstyle | format_ | init | lint | list | readme | rule | show | spellcheck | status | test | tool | version",
+  "app",
+  "interface",
+  "options",
 ]
-containers = [ "usethis._interface" ]
+containers = [ "usethis._ui" ]
 exhaustive = true
 
 [[tool.importlinter.contracts]]
@@ -215,7 +221,6 @@ layers = [
   # docstyle uses (Ruff) tool, badge uses readme
   "badge | docstyle | list | rule",
   "author | browse | ci | readme | show | status | tool",
-  "enums",
 ]
 containers = [ "usethis._core" ]
 exhaustive = true
@@ -250,7 +255,7 @@ name = "usethis._integrations"
 type = "layers"
 layers = [
   "ci | pre_commit",
-  "uv | mkdocs | pytest | pydantic | sonarqube",
+  "backend | mkdocs | pytest | pydantic | sonarqube",
   "project | python",
   "file",
 ]
@@ -268,6 +273,16 @@ layers = [
 containers = [ "usethis._integrations.file" ]
 exhaustive = true
 
+[[tool.importlinter.contracts]]
+name = "usethis._ui.interface"
+type = "layers"
+layers = [
+  # Note; if you're adding an interface, make sure it's in the README too.
+  "author | badge | browse | ci | doc | docstyle | format_ | init | lint | list | readme | rule | show | spellcheck | status | test | tool | version",
+]
+containers = [ "usethis._ui.interface" ]
+exhaustive = true
+
 [[tool.importlinter.contracts]]
 name = "usethis._pipeweld"
 type = "layers"

diff --git a/src/usethis/__main__.py b/src/usethis/__main__.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from usethis._app import app
+from usethis._ui.app import app
 
 app(prog_name="usethis")
 

diff --git a/src/usethis/_config.py b/src/usethis/_config.py
@@ -5,14 +5,18 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from usethis._types.backend import BackendEnum
+
 if TYPE_CHECKING:
     from collections.abc import Generator
 
+
 HOW_DEFAULT = False
 REMOVE_DEFAULT = False
 FROZEN_DEFAULT = False
 OFFLINE_DEFAULT = False
 QUIET_DEFAULT = False
+BACKEND_DEFAULT = "auto"
 
 
 @dataclass
@@ -24,7 +28,8 @@ class UsethisConfig:
         quiet: Suppress all output, regardless of any other options.
         frozen: Do not install dependencies, nor update lockfiles.
         alert_only: Suppress all output except for warnings and errors.
-        disable_uv_subprocess: Raise an error if a uv subprocess invocation is tried.
+        backend: The package manager backend to use. Attempted subprocesses to other
+                 backends will raise an error.
         disable_pre_commit: Disable pre-commit integrations. Assume that pre-commit is
                             never used (unless explicitly requested via a function whose
                             purpose is to modify pre-commit configuration).
@@ -33,11 +38,11 @@ class UsethisConfig:
                            working directory dynamically determined at runtime.
     """
 
-    offline: bool = False
-    quiet: bool = False
-    frozen: bool = False
+    offline: bool = OFFLINE_DEFAULT
+    quiet: bool = QUIET_DEFAULT
+    frozen: bool = FROZEN_DEFAULT
     alert_only: bool = False
-    disable_uv_subprocess: bool = False
+    backend: BackendEnum = BackendEnum(BACKEND_DEFAULT)  # noqa: RUF009
     disable_pre_commit: bool = False
     subprocess_verbose: bool = False
     project_dir: Path | None = None
@@ -50,7 +55,7 @@ def set(  # noqa: PLR0913
         quiet: bool | None = None,
         frozen: bool | None = None,
         alert_only: bool | None = None,
-        disable_uv_subprocess: bool | None = None,
+        backend: BackendEnum | None = None,
         disable_pre_commit: bool | None = None,
         subprocess_verbose: bool | None = None,
         project_dir: Path | str | None = None,
@@ -60,7 +65,7 @@ def set(  # noqa: PLR0913
         old_quiet = self.quiet
         old_frozen = self.frozen
         old_alert_only = self.alert_only
-        old_disable_uv_subprocess = self.disable_uv_subprocess
+        old_backend = self.backend
         old_disable_pre_commit = self.disable_pre_commit
         old_subprocess_verbose = self.subprocess_verbose
         old_project_dir = self.project_dir
@@ -73,8 +78,8 @@ def set(  # noqa: PLR0913
             frozen = old_frozen
         if alert_only is None:
             alert_only = self.alert_only
-        if disable_uv_subprocess is None:
-            disable_uv_subprocess = old_disable_uv_subprocess
+        if backend is None:
+            backend = self.backend
         if disable_pre_commit is None:
             disable_pre_commit = old_disable_pre_commit
         if subprocess_verbose is None:
@@ -86,7 +91,7 @@ def set(  # noqa: PLR0913
         self.quiet = quiet
         self.frozen = frozen
         self.alert_only = alert_only
-        self.disable_uv_subprocess = disable_uv_subprocess
+        self.backend = backend
         self.disable_pre_commit = disable_pre_commit
         self.subprocess_verbose = subprocess_verbose
         if isinstance(project_dir, str):
@@ -97,7 +102,7 @@ def set(  # noqa: PLR0913
         self.quiet = old_quiet
         self.frozen = old_frozen
         self.alert_only = old_alert_only
-        self.disable_uv_subprocess = old_disable_uv_subprocess
+        self.backend = old_backend
         self.disable_pre_commit = old_disable_pre_commit
         self.subprocess_verbose = old_subprocess_verbose
         self.project_dir = old_project_dir
@@ -109,12 +114,4 @@ def cpd(self) -> Path:
         return self.project_dir
 
 
-usethis_config = UsethisConfig(
-    offline=OFFLINE_DEFAULT,
-    quiet=QUIET_DEFAULT,
-    frozen=FROZEN_DEFAULT,
-    alert_only=False,
-    disable_uv_subprocess=False,
-    disable_pre_commit=False,
-    subprocess_verbose=False,
-)
+usethis_config = UsethisConfig()