🕷️ Crawler Inspector

URL Lookup

Direct Parameter Lookup

Raw Queries and Responses

1. Shard Calculation

Query:

Response:

Calculated Shard: 10 (from laksa035)

2. Crawled Status Check

Query:

curl -X POST \
  'http://laksa010.int.ahrefs:8124/' \
  -H 'Content-Type: text/plain' \
  -H 'X-ClickHouse-Database: crawler3' \
  -H 'Authorization: Basic YXBpOg==' \
  -d 'SELECT getAhrefsURLFromUnparsed(src_unparsed) AS found_url, ifNull(toUnixTimestamp(download_stamp), 0) AS crawl_time, ifNull(toUnixTimestamp(props_url_first_seen), 0) AS first_indexed_time, download_http_code AS http_code, src_unparsed AS src_unparsed, src_root_hash AS src_root_hash, history_drop_reason AS history_drop_reason, meta_title AS meta_title, meta_descriptions AS meta_descriptions, attrs_boilerpipe_text AS attrs_boilerpipe_text, attrs_markdown AS attrs_markdown, attrs_readable_markdown AS attrs_readable_markdown, meta_canonical AS meta_canonical FROM crawler3.page_info_local FINAL PREWHERE (src_root_hash, src_unparsed) IN ((getAhrefsRootHashFromUnparsed(getAhrefsUnparsedNoserviceFromURL(\'https://docs.astral.sh/uv/pip/environments/\')), getAhrefsUnparsedNoserviceFromURL(\'https://docs.astral.sh/uv/pip/environments/\'))) FORMAT JSONEachRow'

Response:

{"found_url":"https:\/\/docs.astral.sh\/uv\/pip\/environments\/","crawl_time":1775811906,"first_indexed_time":1721821000,"http_code":200,"src_unparsed":"sh,astral!docs,\/uv\/pip\/environments\/ s443","src_root_hash":"2731251898944797010","history_drop_reason":null,"meta_title":"Using environments | uv","meta_descriptions":["uv is an extremely fast Python package and project manager, written in Rust."],"attrs_boilerpipe_text":"Each Python installation has an environment that is active when Python is used. Packages can be\ninstalled into an environment to make their modules available from your Python scripts. Generally,\nit is considered best practice not to modify a Python installation's environment. This is especially\nimportant for Python installations that come with the operating system which often manage the\npackages themselves. A virtual environment is a lightweight way to isolate packages from a Python\ninstallation's environment. Unlike\npip\n, uv requires using a virtual environment by default.\nCreating a virtual environment\nuv supports creating virtual environments, e.g., to create a virtual environment at\n.venv\n:\n$\nuv\nvenv\nA specific name or path can be specified, e.g., to create a virtual environment at\nmy-name\n:\n$\nuv\nvenv\nmy-name\nA Python version can be requested, e.g., to create a virtual environment with Python 3.11:\n$\nuv\nvenv\n--python\n3\n.11\nNote this requires the requested Python version to be available on the system. However, if\nunavailable, uv will download Python for you. See the\nPython version\ndocumentation for more details.\nUsing a virtual environment\nWhen using the default virtual environment name, uv will automatically find and use the virtual\nenvironment during subsequent invocations.\n$\nuv\nvenv\n$\n# Install a package in the new virtual environment\n$\nuv\npip\ninstall\nruff\nThe virtual environment can be \"activated\" to make its packages available:\nmacOS and Linux\nWindows\n$\nsource\n.venv\/bin\/activate\nPS>\n.\nvenv\n\\\nScripts\n\\\nactivate\nNote\nThe default activation script on Unix is for POSIX compliant shells like\nsh\n,\nbash\n, or\nzsh\n.\nThere are additional activation scripts for common alternative shells.\nfish\ncsh \/ tcsh\nNushell\n$\nsource\n.venv\/bin\/activate.fish\n$\nsource\n.venv\/bin\/activate.csh\n$\nuse\n.venv\n\\S\ncripts\n\\a\nctivate.nu\nDeactivating an environment\nTo exit a virtual environment, use the\ndeactivate\ncommand:\n$\ndeactivate\nUsing arbitrary Python environments\nSince uv has no dependency on Python, it can install into virtual environments other than its own.\nFor example, setting\nVIRTUAL_ENV=\/path\/to\/venv\nwill cause uv to install into\n\/path\/to\/venv\n,\nregardless of where uv is installed. Note that if\nVIRTUAL_ENV\nis set to a directory that is\nnot\na\nPEP 405 compliant\nvirtual environment,\nit will be ignored.\nuv can also install into arbitrary, even non-virtual environments, with the\n--python\noption. For\nexample,\nuv pip install --python \/path\/to\/python\nwill install into the environment linked to the\n\/path\/to\/python\ninterpreter regardless of whether or not it is a virtual environment. The\n--python\noption also accepts a path to the root directory of a virtual environment.\nFor convenience,\nuv pip install --system\nwill install into the system Python environment. Using\n--system\nis roughly equivalent to\nuv pip install --python $(which python)\n, but note that\nexecutables that are linked to virtual environments will be skipped. Although we generally recommend\nusing virtual environments for dependency management,\n--system\nis appropriate in continuous\nintegration and containerized environments.\nThe\n--system\nflag is also used to opt in to mutating system environments. For example, the\n--python\nargument can be used to request a Python version (e.g.,\n--python 3.12\n), and uv will\nsearch for an interpreter that meets the request. If uv finds a system interpreter (e.g.,\n\/usr\/lib\/python3.12\n), then the\n--system\nflag is required to allow modification of this\nnon-virtual Python environment. Without the\n--system\nflag, uv will ignore any interpreters that\nare not in virtual environments. Conversely, when the\n--system\nflag is provided, uv will ignore\nany interpreters that\nare\nin virtual environments.\nInstalling into system Python across platforms and distributions is notoriously difficult. uv\nsupports the common cases, but will not work in all cases. For example, installing into system\nPython on Debian prior to Python 3.10 is unsupported due to the\ndistribution's patching of\ndistutils\n(but not\nsysconfig\n)\n.\nWhile we always recommend the use of virtual environments, uv considers them to be required in these\nnon-standard environments.\nIf uv is installed in a Python environment, e.g., with\npip\n, it can still be used to modify other\nenvironments. However, when invoked with\npython -m uv\n, uv will default to using the parent\ninterpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for\ngeneral usage.\nuv itself does not depend on Python, but it does need to locate a Python environment to (1) install\ndependencies into the environment and (2) build source distributions.\nDiscovery of Python environments\nWhen running a command that mutates an environment such as\nuv pip sync\nor\nuv pip install\n, uv\nwill search for a virtual environment in the following order:\nAn activated virtual environment based on the\nVIRTUAL_ENV\nenvironment variable.\nAn activated Conda environment based on the\nCONDA_PREFIX\nenvironment variable.\nA virtual environment at\n.venv\nin the current directory, or in the nearest parent directory.\nIf no virtual environment is found, uv will prompt the user to create one in the current directory\nvia\nuv venv\n.\nIf the\n--system\nflag is included, uv will skip virtual environments search for an installed Python\nversion. Similarly, when running a command that does not mutate the environment such as\nuv pip compile\n, uv does not\nrequire\na virtual environment — however, a Python interpreter is\nstill required. See the documentation on\nPython discovery\nfor details on the\ndiscovery of installed Python versions.","attrs_markdown":"[Skip to content](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-python-environments)\n\n[![logo](https:\/\/docs.astral.sh\/uv\/assets\/logo-letter.svg)](https:\/\/docs.astral.sh\/uv\/ \"uv\")\n\nuv\n\nUsing environments\n\nInitializing search\n\n[uv](https:\/\/github.com\/astral-sh\/uv \"Go to repository\")\n\n[![logo](https:\/\/docs.astral.sh\/uv\/assets\/logo-letter.svg)](https:\/\/docs.astral.sh\/uv\/ \"uv\")  uv\n\n[uv](https:\/\/github.com\/astral-sh\/uv \"Go to repository\")\n\n- [Introduction](https:\/\/docs.astral.sh\/uv\/)\n- [Getting started](https:\/\/docs.astral.sh\/uv\/getting-started\/)\n  Getting started\n  \n  - [Installation](https:\/\/docs.astral.sh\/uv\/getting-started\/installation\/)\n  - [First steps](https:\/\/docs.astral.sh\/uv\/getting-started\/first-steps\/)\n  - [Features](https:\/\/docs.astral.sh\/uv\/getting-started\/features\/)\n  - [Getting help](https:\/\/docs.astral.sh\/uv\/getting-started\/help\/)\n- [Guides](https:\/\/docs.astral.sh\/uv\/guides\/)\n  Guides\n  \n  - [Installing Python](https:\/\/docs.astral.sh\/uv\/guides\/install-python\/)\n  - [Running scripts](https:\/\/docs.astral.sh\/uv\/guides\/scripts\/)\n  - [Using tools](https:\/\/docs.astral.sh\/uv\/guides\/tools\/)\n  - [Working on projects](https:\/\/docs.astral.sh\/uv\/guides\/projects\/)\n  - [Publishing packages](https:\/\/docs.astral.sh\/uv\/guides\/package\/)\n  - [Migration](https:\/\/docs.astral.sh\/uv\/guides\/migration\/)\n    Migration\n    \n    - [From pip to a uv project](https:\/\/docs.astral.sh\/uv\/guides\/migration\/pip-to-project\/)\n  - [Integrations](https:\/\/docs.astral.sh\/uv\/guides\/integration\/)\n    Integrations\n    \n    - [Docker](https:\/\/docs.astral.sh\/uv\/guides\/integration\/docker\/)\n    - [Jupyter](https:\/\/docs.astral.sh\/uv\/guides\/integration\/jupyter\/)\n    - [marimo](https:\/\/docs.astral.sh\/uv\/guides\/integration\/marimo\/)\n    - [GitHub Actions](https:\/\/docs.astral.sh\/uv\/guides\/integration\/github\/)\n    - [GitLab CI\/CD](https:\/\/docs.astral.sh\/uv\/guides\/integration\/gitlab\/)\n    - [Pre-commit](https:\/\/docs.astral.sh\/uv\/guides\/integration\/pre-commit\/)\n    - [PyTorch](https:\/\/docs.astral.sh\/uv\/guides\/integration\/pytorch\/)\n    - [FastAPI](https:\/\/docs.astral.sh\/uv\/guides\/integration\/fastapi\/)\n    - [Azure Artifacts](https:\/\/docs.astral.sh\/uv\/guides\/integration\/azure\/)\n    - [Google Artifact Registry](https:\/\/docs.astral.sh\/uv\/guides\/integration\/google\/)\n    - [AWS CodeArtifact](https:\/\/docs.astral.sh\/uv\/guides\/integration\/aws\/)\n    - [JFrog Artifactory](https:\/\/docs.astral.sh\/uv\/guides\/integration\/jfrog\/)\n    - [Renovate](https:\/\/docs.astral.sh\/uv\/guides\/integration\/renovate\/)\n    - [Dependabot](https:\/\/docs.astral.sh\/uv\/guides\/integration\/dependabot\/)\n    - [AWS Lambda](https:\/\/docs.astral.sh\/uv\/guides\/integration\/aws-lambda\/)\n    - [Coiled](https:\/\/docs.astral.sh\/uv\/guides\/integration\/coiled\/)\n- [Concepts](https:\/\/docs.astral.sh\/uv\/concepts\/)\n  Concepts\n  \n  - [Projects](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/)\n    Projects\n    \n    - [Structure and files](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/layout\/)\n    - [Creating projects](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/init\/)\n    - [Managing dependencies](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/dependencies\/)\n    - [Running commands](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/run\/)\n    - [Locking and syncing](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/sync\/)\n    - [Configuring projects](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/config\/)\n    - [Building distributions](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/build\/)\n    - [Exporting lockfiles](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/export\/)\n    - [Using workspaces](https:\/\/docs.astral.sh\/uv\/concepts\/projects\/workspaces\/)\n  - [Tools](https:\/\/docs.astral.sh\/uv\/concepts\/tools\/)\n  - [Python versions](https:\/\/docs.astral.sh\/uv\/concepts\/python-versions\/)\n  - [Configuration files](https:\/\/docs.astral.sh\/uv\/concepts\/configuration-files\/)\n  - [Package indexes](https:\/\/docs.astral.sh\/uv\/concepts\/indexes\/)\n  - [Resolution](https:\/\/docs.astral.sh\/uv\/concepts\/resolution\/)\n  - [Build backend](https:\/\/docs.astral.sh\/uv\/concepts\/build-backend\/)\n  - [Authentication](https:\/\/docs.astral.sh\/uv\/concepts\/authentication\/)\n    Authentication\n    \n    - [The auth CLI](https:\/\/docs.astral.sh\/uv\/concepts\/authentication\/cli\/)\n    - [HTTP credentials](https:\/\/docs.astral.sh\/uv\/concepts\/authentication\/http\/)\n    - [Git credentials](https:\/\/docs.astral.sh\/uv\/concepts\/authentication\/git\/)\n    - [TLS certificates](https:\/\/docs.astral.sh\/uv\/concepts\/authentication\/certificates\/)\n    - [Third-party services](https:\/\/docs.astral.sh\/uv\/concepts\/authentication\/third-party\/)\n  - [Caching](https:\/\/docs.astral.sh\/uv\/concepts\/cache\/)\n  - [Preview features](https:\/\/docs.astral.sh\/uv\/concepts\/preview\/)\n  - [The pip interface](https:\/\/docs.astral.sh\/uv\/pip\/)\n    The pip interface\n    \n    - Using environments\n      [Using environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/)\n      Table of contents\n      \n      - [Creating a virtual environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#creating-a-virtual-environment)\n      - [Using a virtual environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-a-virtual-environment)\n      - [Deactivating an environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#deactivating-an-environment)\n      - [Using arbitrary Python environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-arbitrary-python-environments)\n      - [Discovery of Python environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#discovery-of-python-environments)\n    - [Managing packages](https:\/\/docs.astral.sh\/uv\/pip\/packages\/)\n    - [Inspecting environments](https:\/\/docs.astral.sh\/uv\/pip\/inspection\/)\n    - [Declaring dependencies](https:\/\/docs.astral.sh\/uv\/pip\/dependencies\/)\n    - [Locking environments](https:\/\/docs.astral.sh\/uv\/pip\/compile\/)\n    - [Compatibility with pip](https:\/\/docs.astral.sh\/uv\/pip\/compatibility\/)\n- [Reference](https:\/\/docs.astral.sh\/uv\/reference\/)\n  Reference\n  \n  - [Commands](https:\/\/docs.astral.sh\/uv\/reference\/cli\/)\n  - [Settings](https:\/\/docs.astral.sh\/uv\/reference\/settings\/)\n  - [Environment variables](https:\/\/docs.astral.sh\/uv\/reference\/environment\/)\n  - [Storage](https:\/\/docs.astral.sh\/uv\/reference\/storage\/)\n  - [Installer options](https:\/\/docs.astral.sh\/uv\/reference\/installer\/)\n  - [Troubleshooting](https:\/\/docs.astral.sh\/uv\/reference\/troubleshooting\/)\n    Troubleshooting\n    \n    - [Build failures](https:\/\/docs.astral.sh\/uv\/reference\/troubleshooting\/build-failures\/)\n    - [Reproducible examples](https:\/\/docs.astral.sh\/uv\/reference\/troubleshooting\/reproducible-examples\/)\n  - [Internals](https:\/\/docs.astral.sh\/uv\/reference\/internals\/)\n    Internals\n    \n    - [Resolver](https:\/\/docs.astral.sh\/uv\/reference\/internals\/resolver\/)\n    - [Workspace Metadata](https:\/\/docs.astral.sh\/uv\/reference\/internals\/metadata\/)\n  - [Benchmarks](https:\/\/docs.astral.sh\/uv\/reference\/benchmarks\/)\n  - [Policies](https:\/\/docs.astral.sh\/uv\/reference\/policies\/)\n    Policies\n    \n    - [Versioning](https:\/\/docs.astral.sh\/uv\/reference\/policies\/versioning\/)\n    - [Platform support](https:\/\/docs.astral.sh\/uv\/reference\/policies\/platforms\/)\n    - [Python support](https:\/\/docs.astral.sh\/uv\/reference\/policies\/python\/)\n    - [Rust support](https:\/\/docs.astral.sh\/uv\/reference\/policies\/rust\/)\n    - [License](https:\/\/docs.astral.sh\/uv\/reference\/policies\/license\/)\n\nTable of contents\n\n- [Creating a virtual environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#creating-a-virtual-environment)\n- [Using a virtual environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-a-virtual-environment)\n- [Deactivating an environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#deactivating-an-environment)\n- [Using arbitrary Python environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-arbitrary-python-environments)\n- [Discovery of Python environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#discovery-of-python-environments)\n\n1. [Introduction](https:\/\/docs.astral.sh\/uv\/)\n2. [Concepts](https:\/\/docs.astral.sh\/uv\/concepts\/)\n3. [The pip interface](https:\/\/docs.astral.sh\/uv\/pip\/)\n\n# [Using Python environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-python-environments)\nEach Python installation has an environment that is active when Python is used. Packages can be installed into an environment to make their modules available from your Python scripts. Generally, it is considered best practice not to modify a Python installation's environment. This is especially important for Python installations that come with the operating system which often manage the packages themselves. A virtual environment is a lightweight way to isolate packages from a Python installation's environment. Unlike `pip`, uv requires using a virtual environment by default.\n\n## [Creating a virtual environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#creating-a-virtual-environment)\nuv supports creating virtual environments, e.g., to create a virtual environment at `.venv`:\n```\n$ uv venv\n```\nA specific name or path can be specified, e.g., to create a virtual environment at `my-name`:\n```\n$ uv venv my-name\n```\nA Python version can be requested, e.g., to create a virtual environment with Python 3.11:\n```\n$ uv venv --python 3.11\n```\nNote this requires the requested Python version to be available on the system. However, if unavailable, uv will download Python for you. See the [Python version](https:\/\/docs.astral.sh\/uv\/concepts\/python-versions\/) documentation for more details.\n\n## [Using a virtual environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-a-virtual-environment)\nWhen using the default virtual environment name, uv will automatically find and use the virtual environment during subsequent invocations.\n```\n\n```\nThe virtual environment can be \"activated\" to make its packages available:\n\nmacOS and Linux\n\nWindows\n\n```\n$ source .venv\/bin\/activate\n```\n```\nPS> .venv\\Scripts\\activate\n```\n\nNote\n\nThe default activation script on Unix is for POSIX compliant shells like `sh`, `bash`, or `zsh`. There are additional activation scripts for common alternative shells.\n\nfish\n\ncsh \/ tcsh\n\nNushell\n\n```\n$ source .venv\/bin\/activate.fish\n```\n```\n$ source .venv\/bin\/activate.csh\n```\n```\n$ use .venv\\Scripts\\activate.nu\n```\n## [Deactivating an environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#deactivating-an-environment)\nTo exit a virtual environment, use the `deactivate` command:\n```\n$ deactivate\n```\n## [Using arbitrary Python environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-arbitrary-python-environments)\nSince uv has no dependency on Python, it can install into virtual environments other than its own. For example, setting `VIRTUAL_ENV=\/path\/to\/venv` will cause uv to install into `\/path\/to\/venv`, regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to a directory that is **not** a [PEP 405 compliant](https:\/\/peps.python.org\/pep-0405\/#specification) virtual environment, it will be ignored.\n\nuv can also install into arbitrary, even non-virtual environments, with the `--python` option. For example, `uv pip install --python \/path\/to\/python` will install into the environment linked to the `\/path\/to\/python` interpreter regardless of whether or not it is a virtual environment. The `--python` option also accepts a path to the root directory of a virtual environment.\n\nFor convenience, `uv pip install --system` will install into the system Python environment. Using `--system` is roughly equivalent to `uv pip install --python $(which python)`, but note that executables that are linked to virtual environments will be skipped. Although we generally recommend using virtual environments for dependency management, `--system` is appropriate in continuous integration and containerized environments.\n\nThe `--system` flag is also used to opt in to mutating system environments. For example, the `--python` argument can be used to request a Python version (e.g., `--python 3.12`), and uv will search for an interpreter that meets the request. If uv finds a system interpreter (e.g., `\/usr\/lib\/python3.12`), then the `--system` flag is required to allow modification of this non-virtual Python environment. Without the `--system` flag, uv will ignore any interpreters that are not in virtual environments. Conversely, when the `--system` flag is provided, uv will ignore any interpreters that *are* in virtual environments.\n\nInstalling into system Python across platforms and distributions is notoriously difficult. uv supports the common cases, but will not work in all cases. For example, installing into system Python on Debian prior to Python 3.10 is unsupported due to the [distribution's patching of `distutils` (but not `sysconfig`)](https:\/\/ffy00.github.io\/blog\/02-python-debian-and-the-install-locations\/). While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments.\n\nIf uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify other environments. However, when invoked with `python -m uv`, uv will default to using the parent interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for general usage.\n\nuv itself does not depend on Python, but it does need to locate a Python environment to (1) install dependencies into the environment and (2) build source distributions.\n\n## [Discovery of Python environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#discovery-of-python-environments)\nWhen running a command that mutates an environment such as `uv pip sync` or `uv pip install`, uv will search for a virtual environment in the following order:\n\n- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.\n- An activated Conda environment based on the `CONDA_PREFIX` environment variable.\n- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.\n\nIf no virtual environment is found, uv will prompt the user to create one in the current directory via `uv venv`.\n\nIf the `--system` flag is included, uv will skip virtual environments search for an installed Python version. Similarly, when running a command that does not mutate the environment such as `uv pip compile`, uv does not *require* a virtual environment — however, a Python interpreter is still required. See the documentation on [Python discovery](https:\/\/docs.astral.sh\/uv\/concepts\/python-versions\/#discovery-of-python-versions) for details on the discovery of installed Python versions.\n\nMarch 24, 2026\n\nBack to top\n\n[Previous The pip interface](https:\/\/docs.astral.sh\/uv\/pip\/)\n\n[Next Managing packages](https:\/\/docs.astral.sh\/uv\/pip\/packages\/)\n\nMade with  [Material for MkDocs](https:\/\/squidfunk.github.io\/mkdocs-material\/)","attrs_readable_markdown":"Each Python installation has an environment that is active when Python is used. Packages can be installed into an environment to make their modules available from your Python scripts. Generally, it is considered best practice not to modify a Python installation's environment. This is especially important for Python installations that come with the operating system which often manage the packages themselves. A virtual environment is a lightweight way to isolate packages from a Python installation's environment. Unlike `pip`, uv requires using a virtual environment by default.\n\n## [Creating a virtual environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#creating-a-virtual-environment)\nuv supports creating virtual environments, e.g., to create a virtual environment at `.venv`:\n```\n$ uv venv\n```\nA specific name or path can be specified, e.g., to create a virtual environment at `my-name`:\n```\n$ uv venv my-name\n```\nA Python version can be requested, e.g., to create a virtual environment with Python 3.11:\n```\n$ uv venv --python 3.11\n```\nNote this requires the requested Python version to be available on the system. However, if unavailable, uv will download Python for you. See the [Python version](https:\/\/docs.astral.sh\/uv\/concepts\/python-versions\/) documentation for more details.\n\n## [Using a virtual environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-a-virtual-environment)\nWhen using the default virtual environment name, uv will automatically find and use the virtual environment during subsequent invocations.\n```\n\n```\nThe virtual environment can be \"activated\" to make its packages available:\n\nmacOS and LinuxWindows\n\n```\n$ source .venv\/bin\/activate\n```\n```\nPS> .venv\\Scripts\\activate\n```\n\nNote\n\nThe default activation script on Unix is for POSIX compliant shells like `sh`, `bash`, or `zsh`. There are additional activation scripts for common alternative shells.\n\nfishcsh \/ tcshNushell\n\n```\n$ source .venv\/bin\/activate.fish\n```\n```\n$ source .venv\/bin\/activate.csh\n```\n```\n$ use .venv\\Scripts\\activate.nu\n```\n## [Deactivating an environment](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#deactivating-an-environment)\nTo exit a virtual environment, use the `deactivate` command:\n```\n$ deactivate\n```\n## [Using arbitrary Python environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#using-arbitrary-python-environments)\nSince uv has no dependency on Python, it can install into virtual environments other than its own. For example, setting `VIRTUAL_ENV=\/path\/to\/venv` will cause uv to install into `\/path\/to\/venv`, regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to a directory that is **not** a [PEP 405 compliant](https:\/\/peps.python.org\/pep-0405\/#specification) virtual environment, it will be ignored.\n\nuv can also install into arbitrary, even non-virtual environments, with the `--python` option. For example, `uv pip install --python \/path\/to\/python` will install into the environment linked to the `\/path\/to\/python` interpreter regardless of whether or not it is a virtual environment. The `--python` option also accepts a path to the root directory of a virtual environment.\n\nFor convenience, `uv pip install --system` will install into the system Python environment. Using `--system` is roughly equivalent to `uv pip install --python $(which python)`, but note that executables that are linked to virtual environments will be skipped. Although we generally recommend using virtual environments for dependency management, `--system` is appropriate in continuous integration and containerized environments.\n\nThe `--system` flag is also used to opt in to mutating system environments. For example, the `--python` argument can be used to request a Python version (e.g., `--python 3.12`), and uv will search for an interpreter that meets the request. If uv finds a system interpreter (e.g., `\/usr\/lib\/python3.12`), then the `--system` flag is required to allow modification of this non-virtual Python environment. Without the `--system` flag, uv will ignore any interpreters that are not in virtual environments. Conversely, when the `--system` flag is provided, uv will ignore any interpreters that *are* in virtual environments.\n\nInstalling into system Python across platforms and distributions is notoriously difficult. uv supports the common cases, but will not work in all cases. For example, installing into system Python on Debian prior to Python 3.10 is unsupported due to the [distribution's patching of `distutils` (but not `sysconfig`)](https:\/\/ffy00.github.io\/blog\/02-python-debian-and-the-install-locations\/). While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments.\n\nIf uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify other environments. However, when invoked with `python -m uv`, uv will default to using the parent interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for general usage.\n\nuv itself does not depend on Python, but it does need to locate a Python environment to (1) install dependencies into the environment and (2) build source distributions.\n\n## [Discovery of Python environments](https:\/\/docs.astral.sh\/uv\/pip\/environments\/#discovery-of-python-environments)\nWhen running a command that mutates an environment such as `uv pip sync` or `uv pip install`, uv will search for a virtual environment in the following order:\n\n- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.\n- An activated Conda environment based on the `CONDA_PREFIX` environment variable.\n- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.\n\nIf no virtual environment is found, uv will prompt the user to create one in the current directory via `uv venv`.\n\nIf the `--system` flag is included, uv will skip virtual environments search for an installed Python version. Similarly, when running a command that does not mutate the environment such as `uv pip compile`, uv does not *require* a virtual environment — however, a Python interpreter is still required. See the documentation on [Python discovery](https:\/\/docs.astral.sh\/uv\/concepts\/python-versions\/#discovery-of-python-versions) for details on the discovery of installed Python versions.","meta_canonical":null}

3. Robots.txt Check

Query:

Response:

4. Spam/Ban Check

Query:

Response:

5. Seen Status Check

ℹ️ Skipped - page is already crawled

📄

INDEXABLE

✅

CRAWLED

4 days ago

🤖

ROBOTS ALLOWED

Page Info Filters

Filter	Status	Condition	Details
HTTP status	PASS	`download_http_code = 200`	HTTP 200
Age cutoff	PASS	`download_stamp > now() - 6 MONTH`	0.2 months ago
History drop	PASS	`isNull(history_drop_reason)`	No drop reason
Spam/ban	PASS	`fh_dont_index != 1 AND ml_spam_score = 0`	ml_spam_score=0
Canonical	PASS	`meta_canonical IS NULL OR = '' OR = src_unparsed`	Not set

Page Details

Property	Value
URL	https://docs.astral.sh/uv/pip/environments/
Last Crawled	2026-04-10 09:05:06 (4 days ago)
First Indexed	2024-07-24 11:36:40 (1 year ago)
HTTP Status Code	200
Meta Title	Using environments \| uv
Meta Description	uv is an extremely fast Python package and project manager, written in Rust.
Meta Canonical	null
Boilerpipe Text	Each Python installation has an environment that is active when Python is used. Packages can be installed into an environment to make their modules available from your Python scripts. Generally, it is considered best practice not to modify a Python installation's environment. This is especially important for Python installations that come with the operating system which often manage the packages themselves. A virtual environment is a lightweight way to isolate packages from a Python installation's environment. Unlike pip , uv requires using a virtual environment by default. Creating a virtual environment uv supports creating virtual environments, e.g., to create a virtual environment at .venv : $ uv venv A specific name or path can be specified, e.g., to create a virtual environment at my-name : $ uv venv my-name A Python version can be requested, e.g., to create a virtual environment with Python 3.11: $ uv venv --python 3 .11 Note this requires the requested Python version to be available on the system. However, if unavailable, uv will download Python for you. See the Python version documentation for more details. Using a virtual environment When using the default virtual environment name, uv will automatically find and use the virtual environment during subsequent invocations. $ uv venv $ # Install a package in the new virtual environment $ uv pip install ruff The virtual environment can be "activated" to make its packages available: macOS and Linux Windows $ source .venv/bin/activate PS> . venv \ Scripts \ activate Note The default activation script on Unix is for POSIX compliant shells like sh , bash , or zsh . There are additional activation scripts for common alternative shells. fish csh / tcsh Nushell $ source .venv/bin/activate.fish $ source .venv/bin/activate.csh $ use .venv \S cripts \a ctivate.nu Deactivating an environment To exit a virtual environment, use the deactivate command: $ deactivate Using arbitrary Python environments Since uv has no dependency on Python, it can install into virtual environments other than its own. For example, setting VIRTUAL_ENV=/path/to/venv will cause uv to install into /path/to/venv , regardless of where uv is installed. Note that if VIRTUAL_ENV is set to a directory that is not a PEP 405 compliant virtual environment, it will be ignored. uv can also install into arbitrary, even non-virtual environments, with the --python option. For example, uv pip install --python /path/to/python will install into the environment linked to the /path/to/python interpreter regardless of whether or not it is a virtual environment. The --python option also accepts a path to the root directory of a virtual environment. For convenience, uv pip install --system will install into the system Python environment. Using --system is roughly equivalent to uv pip install --python $(which python) , but note that executables that are linked to virtual environments will be skipped. Although we generally recommend using virtual environments for dependency management, --system is appropriate in continuous integration and containerized environments. The --system flag is also used to opt in to mutating system environments. For example, the --python argument can be used to request a Python version (e.g., --python 3.12 ), and uv will search for an interpreter that meets the request. If uv finds a system interpreter (e.g., /usr/lib/python3.12 ), then the --system flag is required to allow modification of this non-virtual Python environment. Without the --system flag, uv will ignore any interpreters that are not in virtual environments. Conversely, when the --system flag is provided, uv will ignore any interpreters that are in virtual environments. Installing into system Python across platforms and distributions is notoriously difficult. uv supports the common cases, but will not work in all cases. For example, installing into system Python on Debian prior to Python 3.10 is unsupported due to the distribution's patching of distutils (but not sysconfig ) . While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments. If uv is installed in a Python environment, e.g., with pip , it can still be used to modify other environments. However, when invoked with python -m uv , uv will default to using the parent interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for general usage. uv itself does not depend on Python, but it does need to locate a Python environment to (1) install dependencies into the environment and (2) build source distributions. Discovery of Python environments When running a command that mutates an environment such as uv pip sync or uv pip install , uv will search for a virtual environment in the following order: An activated virtual environment based on the VIRTUAL_ENV environment variable. An activated Conda environment based on the CONDA_PREFIX environment variable. A virtual environment at .venv in the current directory, or in the nearest parent directory. If no virtual environment is found, uv will prompt the user to create one in the current directory via uv venv . If the --system flag is included, uv will skip virtual environments search for an installed Python version. Similarly, when running a command that does not mutate the environment such as uv pip compile , uv does not require a virtual environment — however, a Python interpreter is still required. See the documentation on Python discovery for details on the discovery of installed Python versions.
Markdown	[Skip to content](https://docs.astral.sh/uv/pip/environments/#using-python-environments) [![logo](https://docs.astral.sh/uv/assets/logo-letter.svg)](https://docs.astral.sh/uv/ "uv") uv Using environments Initializing search [uv](https://github.com/astral-sh/uv "Go to repository") [![logo](https://docs.astral.sh/uv/assets/logo-letter.svg)](https://docs.astral.sh/uv/ "uv") uv [uv](https://github.com/astral-sh/uv "Go to repository") - [Introduction](https://docs.astral.sh/uv/) - [Getting started](https://docs.astral.sh/uv/getting-started/) Getting started - [Installation](https://docs.astral.sh/uv/getting-started/installation/) - [First steps](https://docs.astral.sh/uv/getting-started/first-steps/) - [Features](https://docs.astral.sh/uv/getting-started/features/) - [Getting help](https://docs.astral.sh/uv/getting-started/help/) - [Guides](https://docs.astral.sh/uv/guides/) Guides - [Installing Python](https://docs.astral.sh/uv/guides/install-python/) - [Running scripts](https://docs.astral.sh/uv/guides/scripts/) - [Using tools](https://docs.astral.sh/uv/guides/tools/) - [Working on projects](https://docs.astral.sh/uv/guides/projects/) - [Publishing packages](https://docs.astral.sh/uv/guides/package/) - [Migration](https://docs.astral.sh/uv/guides/migration/) Migration - [From pip to a uv project](https://docs.astral.sh/uv/guides/migration/pip-to-project/) - [Integrations](https://docs.astral.sh/uv/guides/integration/) Integrations - [Docker](https://docs.astral.sh/uv/guides/integration/docker/) - [Jupyter](https://docs.astral.sh/uv/guides/integration/jupyter/) - [marimo](https://docs.astral.sh/uv/guides/integration/marimo/) - [GitHub Actions](https://docs.astral.sh/uv/guides/integration/github/) - [GitLab CI/CD](https://docs.astral.sh/uv/guides/integration/gitlab/) - [Pre-commit](https://docs.astral.sh/uv/guides/integration/pre-commit/) - [PyTorch](https://docs.astral.sh/uv/guides/integration/pytorch/) - [FastAPI](https://docs.astral.sh/uv/guides/integration/fastapi/) - [Azure Artifacts](https://docs.astral.sh/uv/guides/integration/azure/) - [Google Artifact Registry](https://docs.astral.sh/uv/guides/integration/google/) - [AWS CodeArtifact](https://docs.astral.sh/uv/guides/integration/aws/) - [JFrog Artifactory](https://docs.astral.sh/uv/guides/integration/jfrog/) - [Renovate](https://docs.astral.sh/uv/guides/integration/renovate/) - [Dependabot](https://docs.astral.sh/uv/guides/integration/dependabot/) - [AWS Lambda](https://docs.astral.sh/uv/guides/integration/aws-lambda/) - [Coiled](https://docs.astral.sh/uv/guides/integration/coiled/) - [Concepts](https://docs.astral.sh/uv/concepts/) Concepts - [Projects](https://docs.astral.sh/uv/concepts/projects/) Projects - [Structure and files](https://docs.astral.sh/uv/concepts/projects/layout/) - [Creating projects](https://docs.astral.sh/uv/concepts/projects/init/) - [Managing dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/) - [Running commands](https://docs.astral.sh/uv/concepts/projects/run/) - [Locking and syncing](https://docs.astral.sh/uv/concepts/projects/sync/) - [Configuring projects](https://docs.astral.sh/uv/concepts/projects/config/) - [Building distributions](https://docs.astral.sh/uv/concepts/projects/build/) - [Exporting lockfiles](https://docs.astral.sh/uv/concepts/projects/export/) - [Using workspaces](https://docs.astral.sh/uv/concepts/projects/workspaces/) - [Tools](https://docs.astral.sh/uv/concepts/tools/) - [Python versions](https://docs.astral.sh/uv/concepts/python-versions/) - [Configuration files](https://docs.astral.sh/uv/concepts/configuration-files/) - [Package indexes](https://docs.astral.sh/uv/concepts/indexes/) - [Resolution](https://docs.astral.sh/uv/concepts/resolution/) - [Build backend](https://docs.astral.sh/uv/concepts/build-backend/) - [Authentication](https://docs.astral.sh/uv/concepts/authentication/) Authentication - [The auth CLI](https://docs.astral.sh/uv/concepts/authentication/cli/) - [HTTP credentials](https://docs.astral.sh/uv/concepts/authentication/http/) - [Git credentials](https://docs.astral.sh/uv/concepts/authentication/git/) - [TLS certificates](https://docs.astral.sh/uv/concepts/authentication/certificates/) - [Third-party services](https://docs.astral.sh/uv/concepts/authentication/third-party/) - [Caching](https://docs.astral.sh/uv/concepts/cache/) - [Preview features](https://docs.astral.sh/uv/concepts/preview/) - [The pip interface](https://docs.astral.sh/uv/pip/) The pip interface - Using environments [Using environments](https://docs.astral.sh/uv/pip/environments/) Table of contents - [Creating a virtual environment](https://docs.astral.sh/uv/pip/environments/#creating-a-virtual-environment) - [Using a virtual environment](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment) - [Deactivating an environment](https://docs.astral.sh/uv/pip/environments/#deactivating-an-environment) - [Using arbitrary Python environments](https://docs.astral.sh/uv/pip/environments/#using-arbitrary-python-environments) - [Discovery of Python environments](https://docs.astral.sh/uv/pip/environments/#discovery-of-python-environments) - [Managing packages](https://docs.astral.sh/uv/pip/packages/) - [Inspecting environments](https://docs.astral.sh/uv/pip/inspection/) - [Declaring dependencies](https://docs.astral.sh/uv/pip/dependencies/) - [Locking environments](https://docs.astral.sh/uv/pip/compile/) - [Compatibility with pip](https://docs.astral.sh/uv/pip/compatibility/) - [Reference](https://docs.astral.sh/uv/reference/) Reference - [Commands](https://docs.astral.sh/uv/reference/cli/) - [Settings](https://docs.astral.sh/uv/reference/settings/) - [Environment variables](https://docs.astral.sh/uv/reference/environment/) - [Storage](https://docs.astral.sh/uv/reference/storage/) - [Installer options](https://docs.astral.sh/uv/reference/installer/) - [Troubleshooting](https://docs.astral.sh/uv/reference/troubleshooting/) Troubleshooting - [Build failures](https://docs.astral.sh/uv/reference/troubleshooting/build-failures/) - [Reproducible examples](https://docs.astral.sh/uv/reference/troubleshooting/reproducible-examples/) - [Internals](https://docs.astral.sh/uv/reference/internals/) Internals - [Resolver](https://docs.astral.sh/uv/reference/internals/resolver/) - [Workspace Metadata](https://docs.astral.sh/uv/reference/internals/metadata/) - [Benchmarks](https://docs.astral.sh/uv/reference/benchmarks/) - [Policies](https://docs.astral.sh/uv/reference/policies/) Policies - [Versioning](https://docs.astral.sh/uv/reference/policies/versioning/) - [Platform support](https://docs.astral.sh/uv/reference/policies/platforms/) - [Python support](https://docs.astral.sh/uv/reference/policies/python/) - [Rust support](https://docs.astral.sh/uv/reference/policies/rust/) - [License](https://docs.astral.sh/uv/reference/policies/license/) Table of contents - [Creating a virtual environment](https://docs.astral.sh/uv/pip/environments/#creating-a-virtual-environment) - [Using a virtual environment](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment) - [Deactivating an environment](https://docs.astral.sh/uv/pip/environments/#deactivating-an-environment) - [Using arbitrary Python environments](https://docs.astral.sh/uv/pip/environments/#using-arbitrary-python-environments) - [Discovery of Python environments](https://docs.astral.sh/uv/pip/environments/#discovery-of-python-environments) 1. [Introduction](https://docs.astral.sh/uv/) 2. [Concepts](https://docs.astral.sh/uv/concepts/) 3. [The pip interface](https://docs.astral.sh/uv/pip/) # [Using Python environments](https://docs.astral.sh/uv/pip/environments/#using-python-environments) Each Python installation has an environment that is active when Python is used. Packages can be installed into an environment to make their modules available from your Python scripts. Generally, it is considered best practice not to modify a Python installation's environment. This is especially important for Python installations that come with the operating system which often manage the packages themselves. A virtual environment is a lightweight way to isolate packages from a Python installation's environment. Unlike `pip`, uv requires using a virtual environment by default. ## [Creating a virtual environment](https://docs.astral.sh/uv/pip/environments/#creating-a-virtual-environment) uv supports creating virtual environments, e.g., to create a virtual environment at `.venv`: ``` $ uv venv ``` A specific name or path can be specified, e.g., to create a virtual environment at `my-name`: ``` $ uv venv my-name ``` A Python version can be requested, e.g., to create a virtual environment with Python 3.11: ``` $ uv venv --python 3.11 ``` Note this requires the requested Python version to be available on the system. However, if unavailable, uv will download Python for you. See the [Python version](https://docs.astral.sh/uv/concepts/python-versions/) documentation for more details. ## [Using a virtual environment](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment) When using the default virtual environment name, uv will automatically find and use the virtual environment during subsequent invocations. ``` ``` The virtual environment can be "activated" to make its packages available: macOS and Linux Windows ``` $ source .venv/bin/activate ``` ``` PS> .venv\Scripts\activate ``` Note The default activation script on Unix is for POSIX compliant shells like `sh`, `bash`, or `zsh`. There are additional activation scripts for common alternative shells. fish csh / tcsh Nushell ``` $ source .venv/bin/activate.fish ``` ``` $ source .venv/bin/activate.csh ``` ``` $ use .venv\Scripts\activate.nu ``` ## [Deactivating an environment](https://docs.astral.sh/uv/pip/environments/#deactivating-an-environment) To exit a virtual environment, use the `deactivate` command: ``` $ deactivate ``` ## [Using arbitrary Python environments](https://docs.astral.sh/uv/pip/environments/#using-arbitrary-python-environments) Since uv has no dependency on Python, it can install into virtual environments other than its own. For example, setting `VIRTUAL_ENV=/path/to/venv` will cause uv to install into `/path/to/venv`, regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to a directory that is not a [PEP 405 compliant](https://peps.python.org/pep-0405/#specification) virtual environment, it will be ignored. uv can also install into arbitrary, even non-virtual environments, with the `--python` option. For example, `uv pip install --python /path/to/python` will install into the environment linked to the `/path/to/python` interpreter regardless of whether or not it is a virtual environment. The `--python` option also accepts a path to the root directory of a virtual environment. For convenience, `uv pip install --system` will install into the system Python environment. Using `--system` is roughly equivalent to `uv pip install --python $(which python)`, but note that executables that are linked to virtual environments will be skipped. Although we generally recommend using virtual environments for dependency management, `--system` is appropriate in continuous integration and containerized environments. The `--system` flag is also used to opt in to mutating system environments. For example, the `--python` argument can be used to request a Python version (e.g., `--python 3.12`), and uv will search for an interpreter that meets the request. If uv finds a system interpreter (e.g., `/usr/lib/python3.12`), then the `--system` flag is required to allow modification of this non-virtual Python environment. Without the `--system` flag, uv will ignore any interpreters that are not in virtual environments. Conversely, when the `--system` flag is provided, uv will ignore any interpreters that are in virtual environments. Installing into system Python across platforms and distributions is notoriously difficult. uv supports the common cases, but will not work in all cases. For example, installing into system Python on Debian prior to Python 3.10 is unsupported due to the [distribution's patching of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/). While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments. If uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify other environments. However, when invoked with `python -m uv`, uv will default to using the parent interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for general usage. uv itself does not depend on Python, but it does need to locate a Python environment to (1) install dependencies into the environment and (2) build source distributions. ## [Discovery of Python environments](https://docs.astral.sh/uv/pip/environments/#discovery-of-python-environments) When running a command that mutates an environment such as `uv pip sync` or `uv pip install`, uv will search for a virtual environment in the following order: - An activated virtual environment based on the `VIRTUAL_ENV` environment variable. - An activated Conda environment based on the `CONDA_PREFIX` environment variable. - A virtual environment at `.venv` in the current directory, or in the nearest parent directory. If no virtual environment is found, uv will prompt the user to create one in the current directory via `uv venv`. If the `--system` flag is included, uv will skip virtual environments search for an installed Python version. Similarly, when running a command that does not mutate the environment such as `uv pip compile`, uv does not require a virtual environment — however, a Python interpreter is still required. See the documentation on [Python discovery](https://docs.astral.sh/uv/concepts/python-versions/#discovery-of-python-versions) for details on the discovery of installed Python versions. March 24, 2026 Back to top [Previous The pip interface](https://docs.astral.sh/uv/pip/) [Next Managing packages](https://docs.astral.sh/uv/pip/packages/) Made with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
Readable Markdown	Each Python installation has an environment that is active when Python is used. Packages can be installed into an environment to make their modules available from your Python scripts. Generally, it is considered best practice not to modify a Python installation's environment. This is especially important for Python installations that come with the operating system which often manage the packages themselves. A virtual environment is a lightweight way to isolate packages from a Python installation's environment. Unlike `pip`, uv requires using a virtual environment by default. ## [Creating a virtual environment](https://docs.astral.sh/uv/pip/environments/#creating-a-virtual-environment) uv supports creating virtual environments, e.g., to create a virtual environment at `.venv`: ``` $ uv venv ``` A specific name or path can be specified, e.g., to create a virtual environment at `my-name`: ``` $ uv venv my-name ``` A Python version can be requested, e.g., to create a virtual environment with Python 3.11: ``` $ uv venv --python 3.11 ``` Note this requires the requested Python version to be available on the system. However, if unavailable, uv will download Python for you. See the [Python version](https://docs.astral.sh/uv/concepts/python-versions/) documentation for more details. ## [Using a virtual environment](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment) When using the default virtual environment name, uv will automatically find and use the virtual environment during subsequent invocations. ``` ``` The virtual environment can be "activated" to make its packages available: macOS and LinuxWindows ``` $ source .venv/bin/activate ``` ``` PS> .venv\Scripts\activate ``` Note The default activation script on Unix is for POSIX compliant shells like `sh`, `bash`, or `zsh`. There are additional activation scripts for common alternative shells. fishcsh / tcshNushell ``` $ source .venv/bin/activate.fish ``` ``` $ source .venv/bin/activate.csh ``` ``` $ use .venv\Scripts\activate.nu ``` ## [Deactivating an environment](https://docs.astral.sh/uv/pip/environments/#deactivating-an-environment) To exit a virtual environment, use the `deactivate` command: ``` $ deactivate ``` ## [Using arbitrary Python environments](https://docs.astral.sh/uv/pip/environments/#using-arbitrary-python-environments) Since uv has no dependency on Python, it can install into virtual environments other than its own. For example, setting `VIRTUAL_ENV=/path/to/venv` will cause uv to install into `/path/to/venv`, regardless of where uv is installed. Note that if `VIRTUAL_ENV` is set to a directory that is not a [PEP 405 compliant](https://peps.python.org/pep-0405/#specification) virtual environment, it will be ignored. uv can also install into arbitrary, even non-virtual environments, with the `--python` option. For example, `uv pip install --python /path/to/python` will install into the environment linked to the `/path/to/python` interpreter regardless of whether or not it is a virtual environment. The `--python` option also accepts a path to the root directory of a virtual environment. For convenience, `uv pip install --system` will install into the system Python environment. Using `--system` is roughly equivalent to `uv pip install --python $(which python)`, but note that executables that are linked to virtual environments will be skipped. Although we generally recommend using virtual environments for dependency management, `--system` is appropriate in continuous integration and containerized environments. The `--system` flag is also used to opt in to mutating system environments. For example, the `--python` argument can be used to request a Python version (e.g., `--python 3.12`), and uv will search for an interpreter that meets the request. If uv finds a system interpreter (e.g., `/usr/lib/python3.12`), then the `--system` flag is required to allow modification of this non-virtual Python environment. Without the `--system` flag, uv will ignore any interpreters that are not in virtual environments. Conversely, when the `--system` flag is provided, uv will ignore any interpreters that are in virtual environments. Installing into system Python across platforms and distributions is notoriously difficult. uv supports the common cases, but will not work in all cases. For example, installing into system Python on Debian prior to Python 3.10 is unsupported due to the [distribution's patching of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-debian-and-the-install-locations/). While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments. If uv is installed in a Python environment, e.g., with `pip`, it can still be used to modify other environments. However, when invoked with `python -m uv`, uv will default to using the parent interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for general usage. uv itself does not depend on Python, but it does need to locate a Python environment to (1) install dependencies into the environment and (2) build source distributions. ## [Discovery of Python environments](https://docs.astral.sh/uv/pip/environments/#discovery-of-python-environments) When running a command that mutates an environment such as `uv pip sync` or `uv pip install`, uv will search for a virtual environment in the following order: - An activated virtual environment based on the `VIRTUAL_ENV` environment variable. - An activated Conda environment based on the `CONDA_PREFIX` environment variable. - A virtual environment at `.venv` in the current directory, or in the nearest parent directory. If no virtual environment is found, uv will prompt the user to create one in the current directory via `uv venv`. If the `--system` flag is included, uv will skip virtual environments search for an installed Python version. Similarly, when running a command that does not mutate the environment such as `uv pip compile`, uv does not require a virtual environment — however, a Python interpreter is still required. See the documentation on [Python discovery](https://docs.astral.sh/uv/concepts/python-versions/#discovery-of-python-versions) for details on the discovery of installed Python versions.
Shard	10 (laksa)
Root Hash	2731251898944797010
Unparsed URL	sh,astral!docs,/uv/pip/environments/ s443