Importing Existing Environments

Learn how to import existing conda and pip environments into Pixi workspaces.

Learn how to migrate existing conda environments, requirements.txt files, and environment.yml files into Pixi workspaces.

Why Import Environments?

You may have existing projects using:

• Conda environment.yml files
• Pip requirements.txt files
• Poetry or other dependency managers

Pixi can import these environments, preserving your dependencies while adding Pixi’s powerful features.

Before You Start

Ensure you have a Pixi workspace. If not, create one:

pixi init my-project
cd my-project

If you’re starting from scratch, you can combine pixi init and pixi import into one command - see pixi init —import below.

Importing Conda Environments

Import conda environment.yml files into your workspace.

Basic Import

1. Create an environment.yml
2. Example environment file:
3. name: data-science
   channels: ["conda-forge"]
   dependencies:
     - python=3.11
     - numpy
     - pandas
     - matplotlib
     - pip:
       - httpx
       - requests
   

4. Import the Environment
5. Import into your workspace:
6. pixi import environment.yml
   

7. What happens:
9. View the Result
10. Check your pixi.toml:
11. [feature.data-science]
    channels = ["conda-forge"]
    
    [feature.data-science.dependencies]
    python = "3.11.*"
    numpy = "*"
    pandas = "*"
    matplotlib = "*"
    
    [feature.data-science.pypi-dependencies]
    httpx = "*"
    requests = "*"
    
    [environments]
    data-science = { features = ["data-science"], no-default-feature = true }
    

12. Use the Environment
13. Run commands in the imported environment:
14. pixi run --environment data-science python -c "import numpy; print(numpy.__version__)"
    

Import Options

Customize the import with options:

Custom Feature Name

Import into a feature with a different name:

pixi import --feature ml-tools environment.yml

Result:

[feature.ml-tools]
channels = ["conda-forge"]

[feature.ml-tools.dependencies]
python = "3.11.*"
numpy = "*"
# ...

[environments]
ml-tools = { features = ["ml-tools"], no-default-feature = true }

Custom Environment Name

Import into an environment with a different name:

pixi import --environment analysis environment.yml

Creates an environment named “analysis” with the feature name from the file.

Specific Platforms

Import with platform restrictions:

pixi import --platform linux-64 --platform osx-arm64 environment.yml

Result:

[feature.data-science]
platforms = ["linux-64", "osx-arm64"]
channels = ["conda-forge"]

[feature.data-science.target.linux-64.dependencies]
python = "3.11.*"
numpy = "*"

[feature.data-science.target.osx-arm64.dependencies]
python = "3.11.*"
numpy = "*"

Merge into Existing Environments

Import into an existing environment:

1. Create Base Environment
2. # base.yml
   name: base
   channels: ["conda-forge"]
   dependencies:
     - python
     - pip:
       - httpx
   

3. Import:
4. pixi import base.yml
   

5. Add More Dependencies
6. # extras.yml
   channels: ["conda-forge"]
   dependencies:
     - numpy
     - pandas
   

7. Import into the existing environment:
8. pixi import --feature numpy-tools --environment base extras.yml
   

9. Check the Result
10. [feature.base]
    channels = ["conda-forge"]
    
    [feature.base.dependencies]
    python = "*"
    
    [feature.base.pypi-dependencies]
    httpx = "*"
    
    [feature.numpy-tools]
    channels = ["conda-forge"]
    
    [feature.numpy-tools.dependencies]
    numpy = "*"
    pandas = "*"
    
    [environments]
    base = { features = ["base", "numpy-tools"], no-default-feature = true }
    

Import into Default Environment

Import dependencies into the default environment:

pixi import --feature default environment.yml

This adds dependencies to the top-level [dependencies] section.

Importing PyPI Requirements

Import pip requirements.txt files.

Basic Import

1. Create requirements.txt
2. Example requirements file:
3. cowpy
   array-api-extra>=0.8
   requests==2.31.0
   httpx~=0.24.0
   

4. Import the File
5. Import with a feature name:
6. pixi import --format pypi-txt --feature python-tools requirements.txt
   

7. For PyPI imports, you must specify either --feature or --environment.

8. View the Result
9. [feature.python-tools.pypi-dependencies]
   cowpy = "*"
   array-api-extra = ">=0.8"
   requests = "==2.31.0"
   httpx = "~=0.24.0"
   
   [environments]
   python-tools = { features = ["python-tools"], no-default-feature = true }
   

10. Use the Environment
11. pixi run --environment python-tools python -c "import cowpy; print('Imported!')"
    

12. Expected Output:
13. Imported!
    

Advanced Requirements

Pixi supports various requirement formats:

Version Specifiers

numpy>=1.20.0
pandas==2.0.0
matplotlib~=3.8.0
scipy>=1.10,<2.0

Multiple Requirements Files

Import multiple files into the same environment:

# Import base requirements
pixi import --format pypi-txt --feature app requirements.txt

# Import dev requirements into same environment
pixi import --format pypi-txt --feature app-dev --environment app requirements-dev.txt

Combining Init and Import

Combine workspace creation and import in one command:

Import Conda Environment

Create a workspace from an environment.yml:

pixi init --import environment.yml

Result:

[workspace]
name = "data-science"  # From environment.yml name field
authors = ["Your Name <[e-mail]>"]
channels = ["conda-forge"]
platforms = ["linux-64"]
version = "0.1.0"

[dependencies]
python = "3.11.*"
numpy = "*"
pandas = "*"

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

pixi init --import adds dependencies to the default environment, unlike pixi import which creates a new environment.

Override Workspace Name

Specify a custom workspace name:

pixi init my-project --import environment.yml

At the time of writing, pixi init --import only supports the conda-env format, not pypi-txt.

Automatic Format Detection

Pixi can detect the format automatically:

pixi import environment.yml    # Detects conda-env format
pixi import requirements.txt   # Detects pypi-txt format

Or specify explicitly:

pixi import --format conda-env environment.yml
pixi import --format pypi-txt requirements.txt

Real-World Examples

Migrate a Data Science Project

1. Original Setup
2. # environment.yml
   name: ml-project
   channels:
     - conda-forge
     - pytorch
   dependencies:
     - python=3.11
     - pytorch
     - torchvision
     - numpy
     - pandas
     - matplotlib
     - jupyter
     - pip:
       - transformers
       - datasets
   

3. Import
4. pixi init
   pixi import environment.yml
   

5. Add Development Tools
6. pixi add --feature dev ruff mypy pytest
   pixi workspace environment add dev --feature ml-project --feature dev
   

7. Result
8. You now have:

Migrate a Web Application

1. Original Setup
2. # requirements.txt
   flask==3.0.0
   sqlalchemy==2.0.25
   celery==5.3.4
   redis==5.0.1
   python-dotenv==1.0.0
   gunicorn==21.2.0
   

3. # requirements-dev.txt
   pytest==8.0.0
   pytest-cov==4.1.0
   ruff==0.1.0
   black==23.12.0
   

4. Import
5. pixi init web-app
   pixi import --format pypi-txt --feature app requirements.txt
   pixi import --format pypi-txt --feature dev requirements-dev.txt
   

6. Create Environments
7. pixi workspace environment add production --feature app --no-default-feature
   pixi workspace environment add dev --feature app --feature dev --no-default-feature
   

8. Result
9. [feature.app.pypi-dependencies]
   flask = "==3.0.0"
   sqlalchemy = "==2.0.25"
   celery = "==5.3.4"
   redis = "==5.0.1"
   python-dotenv = "==1.0.0"
   gunicorn = "==21.2.0"
   
   [feature.dev.pypi-dependencies]
   pytest = "==8.0.0"
   pytest-cov = "==4.1.0"
   ruff = "==0.1.0"
   black = "==23.12.0"
   
   [environments]
   production = { features = ["app"], no-default-feature = true }
   dev = { features = ["app", "dev"], no-default-feature = true }
   

Import from Poetry

While Pixi doesn’t directly import pyproject.toml from Poetry, you can export and import:

# Export from Poetry
poetry export -f requirements.txt --output requirements.txt
poetry export -f requirements.txt --only dev --output requirements-dev.txt

# Import to Pixi
pixi init
pixi import --format pypi-txt --feature default requirements.txt
pixi import --format pypi-txt --feature dev requirements-dev.txt

Post-Import Tasks

After importing, you may want to:

Add Tasks

Define common commands:

[feature.data-science.tasks]
notebook = "jupyter notebook"
lab = "jupyter lab"
analysis = "python analysis.py"

Add More Dependencies

pixi add --feature data-science scipy scikit-learn

Create Additional Environments

pixi workspace environment add test --feature data-science --feature test

Update Lock File

pixi install

Troubleshooting

Import Format Not Detected

Specify the format explicitly:

pixi import --format conda-env environment.yml
pixi import --format pypi-txt requirements.txt

Feature Name Required

For PyPI imports, always specify a feature or environment:

pixi import --feature my-feature requirements.txt

Platform-Specific Dependencies

Some dependencies may not be available on all platforms. Use platform-specific imports:

pixi import --platform linux-64 environment.yml

Version Conflicts

If you encounter conflicts after import:

1. Check the lock file: pixi lock
2. Update specific packages: pixi update package-name
3. Adjust version constraints in pixi.toml

Best Practices

Test after import: Always test your imported environments to ensure everything works.

Use features for organization: Import related dependencies into separate features for better organization.

Specify platforms: If your environment is platform-specific, use --platform to document this.

Keep original files: Keep the original environment.yml or requirements.txt for reference during migration.

Next Steps

• Learn about multi-environment workspaces
• Explore Python development with Pixi
• Understand pyproject.toml integration

Future Improvements

Pixi’s import capabilities are actively being developed:

• Import roadmap issue on GitHub - Track planned enhancements
• Poetry and PDM integration improvements in progress