In this tutorial we will show you how to import existing environments into a Pixi workspace.
In case some words used in the tutorial don't make sense to you, you may get value from first
reading some of our other tutorials, like [our first workspace walthrough](../first_workspace.md) and
[our guide to multi-environment workspaces](./multi_environment.md).

## `pixi import`

Within any Pixi workspace, you can use [`pixi import`](https://pixi.sh/latest/reference/cli/pixi/import/)
to import an environment from a given file. At the time of writing, we support two import
file formats: `conda-env` and `pypi-txt`. Running `pixi import` without providing a `format` will try
each format in turn until one succeeds, or return an error if all formats fail.

If you don't already have a Pixi workspace, you can create one with [`pixi init`](https://pixi.sh/latest/reference/cli/pixi/init/).

### `conda-env` format

The `conda-env` format is for files in the conda ecosystem (typically called `environment.yml`) following
[the syntax specified in the conda docs](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually).
Suppose our environment to import is specified in this file:

```yaml title="environment.yml"
name: simple-env
channels: ["conda-forge"]
dependencies:
- python
- pip:
  - httpx
```

We can then run `pixi import --format=conda-env environment.yml` to import the environment
into our workspace. By default, since our `environment.yml` has a `name` field, this creates a `feature`
of the same name (or uses the feature of that name if it already exists), and creates an `environment`
containing that feature (with [`no-default-feature`](https://pixi.sh/latest/reference/pixi_manifest/#the-environments-table) set):

```toml title="pixi.toml"
[feature.simple-env]
channels = ["conda-forge"]

[feature.simple-env.dependencies]
python = "*"

[feature.simple-env.pypi-dependencies]
httpx = "*"

[environments]
simple-env = { features = ["simple-env"], no-default-feature = true }
```

It is then possible to define tasks for the imported environment, run commands in that
environment, and launch a [`pixi shell`](https://pixi.sh/latest/reference/cli/pixi/shell)
in that environment — see the [getting started guide](../getting_started.md) for links to start learning about these topics!

For files without a `name` field, or to override the default behavior, you can specify custom
`--feature` and `--environment` names. This also allows importing into existing features and
environments (including the `default` feature and environment). For example,
given this other environment file to import:

```yaml title="env2.yml"
channels: ["conda-forge"]
dependencies:
- numpy
```

Running `pixi import --format=conda-env --feature=numpy --environment=simple-env env2.yml` will import
the environment into a new feature called "numpy", and include that feature in the existing
`simple-env` environment (effectively merging the environments from our two input files):

```toml title="pixi.toml"
[feature.simple-env]
channels = ["conda-forge"]

[feature.simple-env.dependencies]
python = "*"

[feature.simple-env.pypi-dependencies]
httpx = "*"

[feature.numpy]
channels = ["conda-forge"]

[feature.numpy.dependencies]
numpy = "*"

[environments]
simple-env = { features = ["simple-env", "numpy"], no-default-feature = true }
```

It is also possible to specify platforms for the feature via the `--platform` argument. For example,
`pixi import --format=conda-env --feature=unix --platform=linux-64 --platform=osx-arm64 environment.yml`
adds the following to our workspace manifest:

```toml title="pixi.toml"
[feature.unix]
platforms = ["linux-64", "osx-arm64"]
channels = ["conda-forge"]

[feature.unix.target.linux-64.dependencies]
python = "*"

[feature.unix.target.osx-arm64.dependencies]
python = "*"

[environments]
unix = { features = ["unix"], no-default-feature = true }
```

### `pypi-txt` format

The `pypi-txt` format is for files in the PyPI ecosystem following [the requirements file format specification in the `pip` docs](https://pip.pypa.io/en/stable/reference/requirements-file-format/).

Suppose our environment to import is specified in this file:

```yaml title="requirements.txt"
cowpy
array-api-extra>=0.8
```

We can then run `pixi import --format=pypi-txt --feature=my-feature1 requirements.txt` to import the
environment into our workspace. It is necessary to specify a `feature` or `environment`
name (or both) via the arguments of the same names. If only one of these names is provided, a matching
name is used for the other field. Hence, the following lines are added to our workspace manifest:

```toml title="pixi.toml"
[feature.my-feature1.pypi-dependencies]
cowpy = "*"
array-api-extra = ">=0.8"

[environments]
my-feature1 = { features = ["my-feature1"], no-default-feature = true }
```

Any dependencies listed in the file are added as [`pypi-dependencies`](https://pixi.sh/latest/reference/pixi_manifest/#pypi-dependencies).
An environment will be created with [`no-default-feature`](https://pixi.sh/latest/reference/pixi_manifest/#the-environments-table)
set if the given environment name does not already exist.

It is then possible to define tasks for that environment, run commands in that
environment, and launch a [`pixi shell`](https://pixi.sh/latest/reference/cli/pixi/shell) in that
environment — see the [getting started guide](../getting_started.md) for links to start learning about these topics!

Just like the `conda-env` format, it is possible to import into existing features/environments
(including the `default` feature/environment), and set specific platforms for the feature. See the previous section for details.

## `pixi init --import`

It is also possible to combine the steps of `pixi init` and `pixi import` into one, via
[`pixi init --import`](https://pixi.sh/latest/reference/cli/pixi/init/#arg---import). For example,
`pixi init --import environment.yml` (using the same file from our example above) produces a manifest
which looks like this:

```toml title="pixi.toml"
[workspace]
authors = ["Lucas Colley <lucas.colley8@gmail.com>"]
channels = ["conda-forge"]
name = "simple-env"
platforms = ["osx-arm64"]
version = "0.1.0"

[tasks]

[dependencies]
python = "*"

[pypi-dependencies]
httpx = "*"
```

Unlike `pixi import`, this by default uses the `default` feature and environment. Thus,
it achieves a very similar workspace to that obtained by running `pixi init ` and `pixi import --feature=default environment.yml`.

One difference is that `pixi init --import` will by default inherit its name from the given import file (if the file specifies the `name` field), rather than from its working directory.

!!! note "Supported formats"
    At the time of writing, only the `conda-env` format is supported by `pixi init --import`.

## Conclusion

For further details, please see the CLI reference documentation for [`pixi import`](https://pixi.sh/latest/reference/cli/pixi/import/) and [`pixi init --import`](https://pixi.sh/latest/reference/cli/pixi/init/#arg---import).
If there are any questions, or you know how to improve this tutorial, feel free to reach out to us on [GitHub](https://github.com/prefix-dev/pixi).

At the time of writing, there are plans for many potential extensions to our import capabilities — you can follow along with that work at the `import` [roadmap issue on GitHub](https://github.com/prefix-dev/pixi/issues/4192).
