Basic Usage¶

pip2conda translates pip-style requirements into conda requirements by reading or generating metadata for a project, evaluating build and runtime requirements, and translating each requirement into a conda-forge compatible format.

Simple Project Analysis¶

Run pip2conda from the base of your project directory:

pip2conda

Collecting requirements for the current project

$ pip2conda
grayskull>=1.0.0
packaging>=25.0
python-build>=1.0.0
python>=3.11
requests>=2.32.5
ruamel.yaml>=0.18.15
setuptools-scm>=3.4.3
setuptools>=61.0
wheel
wheel>=0.45.1

The tool will analyze your project’s metadata and output the conda-compatible requirements.

Analyzing Wheel Files¶

You can also point pip2conda at a wheel file for any project:

pip2conda path/to/package.whl

Converting requirements.txt¶

To convert an existing requirements.txt file into a conda environment.yml file, use the -r/--requirements option:

pip2conda -r ./requirements.txt

This will read the requirements from the specified file and output the conda-compatible equivalents.

Working with Dependency Groups¶

pip2conda supports both standard PEP 735 dependency groups and custom pip2conda-specific dependency groups.

Standard Dependency Groups¶

Standard dependency groups are defined in the [dependency-groups] table of your pyproject.toml:

[dependency-groups]
test = ["pytest", "coverage"]
docs = ["sphinx", "myst-parser"]

You can install specific groups using the -g/--dependency-group option:

pip2conda -g test
pip2conda --dependency-group docs

Or install all groups at once:

pip2conda --all-groups

Custom Dependency Groups¶

For projects that use tools like uv which may fail when dependency groups contain non-pip-installable packages, you can define custom dependency groups that are only recognized by pip2conda:

[tool.pip2conda.dependency-groups]
conda = ["my-conda-only-package", "another-conda-package"]
custom-test = ["pytest-conda", "conda-coverage"]

These custom groups work exactly like standard groups:

pip2conda -g conda
pip2conda -g custom-test

Mixing Standard and Custom Groups¶

You can use both standard and custom dependency groups in the same project. Custom groups take precedence when both define the same group name:

[dependency-groups]
test = ["pytest", "coverage"]

[tool.pip2conda.dependency-groups]
test = ["pytest-conda", "conda-coverage"]  # This overrides the standard test group
conda = ["my-conda-only-package"]

Groups can also reference each other using include-group:

[dependency-groups]
base = ["requests", "numpy"]

[tool.pip2conda.dependency-groups]
extended = [
    {"include-group" = "base"},
    "additional-conda-package",
]

Output Formats¶

By default, pip2conda outputs requirements in a simple list format suitable for use with conda. The tool can also generate YAML format output for conda environment files.

Example: YAML output

Write output in YAML format¶

pip2conda -o requirements.yaml

requirements.yaml¶

channels:
- conda-forge
dependencies:
- grayskull>=1.0.0
- packaging>=25.0
- python-build>=1.0.0
- python>=3.11
- requests>=2.32.5
- ruamel.yaml>=0.18.15
- setuptools-scm>=3.4.3
- setuptools>=61.0
- wheel
- wheel>=0.45.1

Command Line Options¶

For a full list of available options, run:

pip2conda --help

Using the rattler backend¶

pip2conda can use py-rattler as an experimental backend for checking whether packages exist in conda-forge.

Warning

The rattler backend is experimental. It should be very fast, but hasn’t been as rigorously tested as the conda backend. Feedback is welcome on GitLab.

Install the optional extra first:

python -m pip install "pip2conda[rattler]"

Then select the backend with -S/--solver:

pip2conda -S rattler

All other options continue to work as usual, including extras, dependency groups, and Python version selection.