CLI reference

tn-venv [OPTIONS] [DEST]

DEST is the environment directory. It defaults to .venv, so bare tn-venv is a complete command. Exit codes are documented in Exit codes.

Interpreter

-p SPEC, --python SPEC

Interpreter to build from. SPEC may be a filesystem path, a version (3, 3.12, 3.12.1), a command name (python3.12), or an implementation-qualified version (pypy3.10, cpython-3.12-64). Repeatable; the first satisfiable spec wins. Default: the interpreter running tn-venv. See Choosing an interpreter.

Environment: TN_VENV_PYTHON (comma-separated). Config key: python.

--list-pythons

Probe and print every discoverable interpreter, then exit. CLI only.

Creator

--clear

Delete DEST entirely before creating. Read-only files are handled. Environment: TN_VENV_CLEAR. Config key: clear.

--upgrade

Upgrade an existing environment in place: refresh binaries, pyvenv.cfg, activation scripts, and pip; keep site-packages. Creating a missing destination with --upgrade simply creates it. Environment: TN_VENV_UPGRADE. Config key: upgrade.

--system-site-packages / --no-system-site-packages

Give the environment access to the base installation’s site-packages (default: isolated). Recorded as include-system-site-packages in pyvenv.cfg. Environment: TN_VENV_SYSTEM_SITE_PACKAGES. Config key: system-site-packages.

--copies / --no-copies

Copy interpreter binaries instead of symlinking them. Default on Windows. Passing both --symlinks and --copies is a configuration error (exit code 2). Environment: TN_VENV_COPIES. Config key: copies.

--scm-ignore {git,none}

Write a source-control ignore file into the environment. git (the default) writes a .gitignore containing *. none writes nothing. Environment: TN_VENV_SCM_IGNORE. Config key: scm-ignore.

Seeder

--seeder {pip,none}

Which installer to seed with. Default: pip. Environment: TN_VENV_SEEDER. Config key: seeder.

--no-pip, --without-pip

Skip seeding entirely; equivalent to --seeder none and takes precedence over it. Environment: TN_VENV_NO_PIP. Config key: no-pip.

--pip [VERSION]

Pip version to install. With no value, installs the latest release (equivalent to latest). With a value, pins pip==VERSION. The special value bundled keeps the ensurepip-provided version (the default). Environment: TN_VENV_PIP. Config key: pip.

--upgrade-pip / --no-upgrade-pip

Upgrade pip to the latest release from the index after ensurepip. Takes precedence over --pip VERSION. Environment: TN_VENV_UPGRADE_PIP. Config key: upgrade-pip.

--setuptools [VERSION]

Install setuptools — unpinned with no value, or setuptools==VERSION. Not bundled by ensurepip on Python ≥ 3.12. Environment: TN_VENV_SETUPTOOLS. Config key: setuptools.

--wheel [VERSION]

Install wheel — unpinned with no value, or wheel==VERSION. Environment: TN_VENV_WHEEL. Config key: wheel.

--extra-search-dir DIR

Additional directory of wheels/sdists for pip to search (PIP_FIND_LINKS). Repeatable. Environment: TN_VENV_EXTRA_SEARCH_DIR (comma-separated). Config key: extra-search-dir.

--offline / --no-offline

Never reach the network: sets PIP_NO_INDEX=1 for all pip invocations. Environment: TN_VENV_OFFLINE. Config key: offline.

--with PKG, --seed-package PKG

Install PKG into the environment after seeding. Any pip requirement specifier is accepted. Repeatable. Environment: TN_VENV_SEED_PACKAGES (comma-separated). Config key: with / seed-packages.

-r FILE, --requirements FILE

Install from a pip requirements file after seeding. Repeatable; a missing file is a SeedError (exit code 1). Environment: TN_VENV_REQUIREMENTS (comma-separated). Config key: requirements.

Activation

--activators LIST

Comma-separated activation scripts to generate: bash, batch, powershell, fish, csh, nushell, python, plus pseudo-names all and default; prefix a name with - to exclude it from the default set. Repeatable. Default: everything supported on the host platform. Environment: TN_VENV_ACTIVATORS. Config key: activators.

--prompt TEXT

Prompt string shown while the environment is active. Default: the environment folder name. A custom prompt is recorded in pyvenv.cfg. Environment: TN_VENV_PROMPT. Config key: prompt.

Behaviour

-q, --quiet

Decrease verbosity; repeatable. -q shows errors only. Environment: TN_VENV_QUIET (integer). Config key: quiet.

-v, --verbose

Increase verbosity; repeatable. -v adds per-step detail, -vv echoes every subprocess and its output. Environment: TN_VENV_VERBOSE (integer). Config key: verbose.

--color / --no-color

Force colored output on or off. Default: auto-detect (TTY, NO_COLOR/FORCE_COLOR honored, VT processing enabled on Windows). Environment: TN_VENV_COLOR, TN_VENV_FORCE_COLOR. Config key: color.

--dry-run

Print the fully resolved configuration and exit without creating anything. CLI only.

--config FILE

Use this config file instead of discovering one. CLI only; the env-var equivalent is TN_VENV_CONFIG_FILE.

--no-config

Ignore all config files and TN_VENV_* environment variables. CLI only.

--version

Print the tn-venv version and exit.

-h, --help

Print help and exit.