Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc(configuration): improve documentation #6254

Merged
merged 2 commits into from
Aug 28, 2022
Merged

doc(configuration): improve documentation #6254

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c882f78
doc(configuration): improve documentation
mkniewallner Aug 27, 2022
59717b0
doc(configuration): a-z sort options
mkniewallner Aug 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 83 additions & 54 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ You can override the Cache directory by setting the `POETRY_CACHE_DIR` environme

### `cache-dir`

**Type**: string
**Type**: `string`

The path to the cache directory used by Poetry.

Expand All @@ -159,7 +159,9 @@ Defaults to one of the following directories:

### `experimental.system-git-client`

**Type**: boolean
**Type**: `boolean`

**Default**: `false`

*Introduced in 1.2.0*

Expand All @@ -169,33 +171,30 @@ Poetry uses `dulwich` by default for git related tasks to not rely on the availa

If you encounter any problems with it, set to `true` to use the system git backend.

Defaults to `false`.

### `installer.parallel`

**Type**: boolean
### `installer.max-workers`

Use parallel execution when using the new (`>=1.1.0`) installer.
Defaults to `true`.
**Type**: `int`

### `installer.max-workers`
**Default**: `number_of_cores + 4`

**Type**: int
*Introduced in 1.2.0*

Set the maximum number of workers while using the parallel installer. Defaults to `number_of_cores + 4`.
Set the maximum number of workers while using the parallel installer.
The `number_of_cores` is determined by `os.cpu_count()`.
If this raises a `NotImplentedError` exception `number_of_cores` is assumed to be 1.
If this raises a `NotImplementedError` exception, `number_of_cores` is assumed to be 1.

If this configuration parameter is set to a value greater than `number_of_cores + 4`,
the number of maximum workers is still limited at `number_of_cores + 4`.

{{% note %}}
This configuration will be ignored when `installer.parallel` is set to false.
This configuration is ignored when `installer.parallel` is set to `false`.
{{% /note %}}

### `installer.no-binary`

**Type**: string | bool
**Type**: `string | boolean`

**Default**: `false`

*Introduced in 1.2.0*

Expand Down Expand Up @@ -240,22 +239,33 @@ Unless this is required system-wide, if configured globally, you could encounter
across all your projects if incorrectly set.
{{% /warning %}}

### `installer.parallel`

**Type**: `boolean`

**Default**: `true`

*Introduced in 1.1.4*

Use parallel execution when using the new (`>=1.1.0`) installer.

### `virtualenvs.create`

**Type**: boolean
**Type**: `boolean`

**Default**: `true`

Create a new virtual environment if one doesn't already exist.
Defaults to `true`.

If set to `false`, poetry will install dependencies into the current python environment.

### `virtualenvs.in-project`

**Type**: boolean
**Type**: `boolean`

**Default**: `None`

Create the virtualenv inside the project's root directory.
Defaults to `None`.

If not set explicitly, `poetry` by default will create virtual environment under
`{cache-dir}/virtualenvs` or use the `{project-dir}/.venv` directory when one is available.
Expand All @@ -265,35 +275,27 @@ If set to `true`, the virtualenv will be created and expected in a folder named

If set to `false`, `poetry` will ignore any existing `.venv` directory.

### `virtualenvs.path`

**Type**: string

Directory where virtual environments will be created.
Defaults to `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows).
### `virtualenvs.options.always-copy`

### `virtualenvs.prompt`
**Type**: `boolean`

**Type**: string
**Default**: `false`

Format string defining the prompt to be displayed when the virtual environment is activated.
The variables `project_name` and `python_version` are available for formatting.
Defaults to `"{project_name}-py{python_version}"`.
*Introduced in 1.2.0*

### `virtualenvs.options.always-copy`
If set to `true` the `--always-copy` parameter is passed to `virtualenv` on creation of the virtual environment, so that
all needed files are copied into it instead of symlinked.

**Type**: boolean
### `virtualenvs.options.no-pip`

If set to `true` the `--always-copy` parameter is passed to `virtualenv` on creation of the venv. Thus all needed files are copied into the venv instead of symlinked.
Defaults to `false`.
**Type**: `boolean`

### `virtualenvs.options.no-pip`
**Default**: `false`

**Type**: boolean
*Introduced in 1.2.0*

If set to `true` the `--no-pip` parameter is passed to `virtualenv` on creation of the venv. This means when a new
virtual environment is created, `pip` will not be installed in the environment.
Defaults to `false`.
If set to `true` the `--no-pip` parameter is passed to `virtualenv` on creation of the virtual environment. This means
when a new virtual environment is created, `pip` will not be installed in the environment.

{{% note %}}
Poetry, for its internal operations, uses the `pip` wheel embedded in the `virtualenv` package installed as a dependency
Expand All @@ -306,12 +308,15 @@ packages. This is desirable for production environments.

### `virtualenvs.options.no-setuptools`

**Type**: boolean
**Type**: `boolean`

**Default**: `false`

*Introduced in 1.2.0*

If set to `true` the `--no-setuptools` parameter is passed to `virtualenv` on creation of the venv. This means when a new
virtual environment is created, `setuptools` will not be installed in the environment. Poetry, for its internal operations,
does not require `setuptools` and this can safely be set to `true`.
Defaults to `false`.
If set to `true` the `--no-setuptools` parameter is passed to `virtualenv` on creation of the virtual environment. This
means when a new virtual environment is created, `setuptools` will not be installed in the environment. Poetry, for its
internal operations, does not require `setuptools` and this can safely be set to `true`.

{{% warning %}}
Some development tools like IDEs, make an assumption that `setuptools` (and other) packages are always present and
Expand All @@ -320,44 +325,68 @@ available within a virtual environment. This can cause some features in these to

### `virtualenvs.options.system-site-packages`

**Type**: boolean
**Type**: `boolean`

**Default**: `false`

Give the virtual environment access to the system site-packages directory.
Applies on virtualenv creation.
Defaults to `false`.

### `virtualenvs.path`

**Type**: `string`

**Default**: `{cache-dir}/virtualenvs`

Directory where virtual environments will be created.

### `virtualenvs.prefer-active-python` (experimental)

**Type**: boolean
**Type**: `boolean`

**Default**: `false`

*Introduced in 1.2.0*

Use currently activated Python version to create a new virtual environment.
If set to `false`, Python version used during Poetry installation is used.

### `virtualenvs.prompt`

Use currently activated Python version to create a new venv.
Defaults to `false`, which means Python version used during Poetry installation is used.
**Type**: `string`

**Default**: `{project_name}-py{python_version}`

*Introduced in 1.2.0*

Format string defining the prompt to be displayed when the virtual environment is activated.
The variables `project_name` and `python_version` are available for formatting.

### `repositories.<name>`

**Type**: string
**Type**: `string`

Set a new alternative repository. See [Repositories]({{< relref "repositories" >}}) for more information.

### `http-basic.<name>`:

**Types**: string, string
**Type**: `(string, string)`

Set repository credentials (`username` and `password`) for `<name>`.
See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
for more information.

### `pypi-token.<name>`:

**Type**: string
**Type**: `string`

Set repository credentials (using an API token) for `<name>`.
See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
for more information.

### `certificates.<name>.cert`:

**Type**: string | bool
**Type**: `string | boolean`

Set custom certificate authority for repository `<name>`.
See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}})
Expand All @@ -368,7 +397,7 @@ repository.

### `certificates.<name>.client-cert`:

**Type**: string
**Type**: `string`

Set client certificate for repository `<name>`.
See [Repositories - Configuring credentials - Custom certificate authority]({{< relref "repositories#custom-certificate-authority-and-mutual-tls-authentication" >}})
Expand Down