CLI Reference#

This reference documents all available commands, options, and usage patterns for the conda pypi command-line interface.

Overview#

conda-pypi adds the conda pypi subcommand to conda, providing two main operations:

  • conda pypi install - Install PyPI packages with conversion to conda format

  • conda pypi convert - Convert PyPI packages to .conda format without installing

Global Options#

These options are inherited from conda and available for all conda pypi commands:

Target Environment Specification#

-n ENVIRONMENT, --name ENVIRONMENT

Name of the conda environment to operate on. If not specified, uses the currently active environment.

-p PATH, --prefix PATH

Full path to environment location (i.e. prefix). Use this instead of -n when working with environments outside the default envs directory.

Output, Prompt, and Flow Control Options#

--json

Report all output as JSON. Suitable for using conda programmatically or parsing output in scripts.

--console CONSOLE

Select the backend to use for normal output rendering. Options depend on your conda installation.

-v, --verbose

Increase verbosity level. Can be used multiple times:

  • Once: detailed output

  • Twice: INFO logging

  • Thrice: DEBUG logging

  • Four times: TRACE logging

-q, --quiet

Do not display progress bar or other non-essential output. Useful for scripting.

-d, --dry-run

Only display what would have been done without actually performing the operation. Useful for previewing changes.

-y, --yes

Sets any confirmation values to ‘yes’ automatically. Users will not be asked to confirm any operations.

-h, --help

Show help message and exit.

conda pypi install#

Install PyPI packages by converting them to conda format when possible.

Synopsis#

conda pypi install [options] package [package ...]
conda pypi install [options] -e path
conda pypi install [options] -e vcs+url

Description#

The install command takes PyPI packages and converts them to .conda format. Explicitly requested packages are always converted from PyPI, while dependencies are preferentially installed from conda channels when available.

Arguments#

package

Package specification(s) to install. Can be:

  • Package names: httpx, numpy

  • Version specifications: httpx>=0.28, numpy==1.21.*

  • URLs to wheels or source distributions: https://files.pythonhosted.org/packages/...

  • Local file paths: ./my-package-1.0.tar.gz

Options#

--override-channels

Do not search default or .condarc channels during dependency resolution. Requested packages are always converted from PyPI regardless of this flag, but dependencies will be forced to convert from PyPI instead of using conda channels like conda-forge.

--dry-run

Don’t actually install anything, just print what would be done. Shows which packages would be converted from PyPI and which would be installed from conda channels.

-e, --editable

Install packages in editable mode (development mode). Supports:

  • Local directories: -e ./my-project/

  • VCS URLs: -e git+https://github.com/user/repo.git

  • VCS URLs with branches: -e git+https://github.com/user/repo.git@branch

  • VCS URLs with subdirectories: -e git+https://github.com/user/repo.git#subdirectory=sub

Examples#

Install a single package:

conda pypi install httpx

Install multiple packages:

conda pypi install httpx numpy pandas

Install with version constraints:

conda pypi install "httpx>=2.25.0" "numpy<1.22"

Preview installation without changes:

conda pypi install --dry-run tensorflow

Force dependency resolution from PyPI only:

conda pypi install --override-channels some-package-with-many-deps

Install in editable mode from local directory:

conda pypi install -e ./my-project/

Install in editable mode from git repository:

conda pypi install -e git+https://github.com/user/project.git

Install in specific environment:

conda pypi install -n myenv httpx

Quiet installation for scripting:

conda pypi install --quiet --yes httpx

Exit Codes#

  • 0: Success - all packages installed successfully

  • 1: Failure - one or more packages failed to install

conda pypi convert#

Convert PyPI packages to .conda format without installing them.

Synopsis#

conda pypi convert [options] package [package ...]

Description#

The convert command transforms PyPI packages to .conda format without installing them. This is useful for creating conda packages from PyPI distributions, preparing packages for offline installation, or building custom conda channels.

Arguments#

package

Package specification(s) to convert. Same format as install command:

  • Package names: httpx, numpy

  • Version specifications: httpx>=2.25.0, numpy==1.21.*

  • URLs to wheels: https://files.pythonhosted.org/packages/...

Options#

--override-channels

Do not search default or .condarc channels during conversion. Since the convert command only converts the explicitly requested packages (not dependencies), this flag mainly affects whether conda-pypi checks for existing conda equivalents before converting.

-d OUTPUT_DIR, --dest OUTPUT_DIR, -o OUTPUT_DIR, --output-dir OUTPUT_DIR

Directory to save converted .conda packages. If not specified, saves to current directory. The directory will be created if it doesn’t exist.

Examples#

Convert packages to current directory:

conda pypi convert httpx packaging

Convert to specific directory:

conda pypi convert -d ./converted-packages httpx numpy

Convert without checking for conda equivalents:

conda pypi convert --override-channels some-package

Convert from specific environment:

conda pypi convert -n myenv -d ./packages httpx

Quiet conversion:

conda pypi convert --quiet -d ./output httpx

Exit Codes#

  • 0: Success - all packages converted successfully

  • 1: Failure - one or more packages failed to convert

Package Specifications#

Both install and convert commands accept various package specification formats:

Basic Package Names#

conda pypi install httpx
conda pypi install numpy pandas

Version Constraints#

conda pypi install "httpx>=2.25.0"
conda pypi install "numpy>=1.20,<1.22"
conda pypi install "django~=4.0.0"

Exact Versions#

conda pypi install httpx==2.28.1
conda pypi install numpy==1.21.6

URLs#

conda pypi install https://files.pythonhosted.org/packages/.../httpx-2.28.1-py3-none-any.whl

Local Files#

conda pypi install ./dist/mypackage-1.0.tar.gz
conda pypi install /path/to/package.whl

VCS URLs (editable only)#

conda pypi install -e git+https://github.com/user/repo.git
conda pypi install -e git+https://github.com/user/repo.git@branch
conda pypi install -e git+https://github.com/user/repo.git#subdirectory=sub
conda pypi install -e hg+https://bitbucket.org/user/repo
conda pypi install -e svn+https://svn.example.com/repo/trunk

Environment Variables#

conda-pypi respects standard conda environment variables and adds a few of its own:

Conda Variables#

  • CONDA_DEFAULT_ENV: Default environment name

  • CONDA_PREFIX: Current environment prefix

  • CONDA_CHANNELS: Default channels (affects dependency resolution)

Pip Variables#

  • PIP_INDEX_URL: Primary PyPI index URL

  • PIP_EXTRA_INDEX_URL: Additional PyPI index URLs

  • PIP_TRUSTED_HOST: Trusted hosts for PyPI access

Integration with conda list#

When conda-pypi converts and installs packages, they appear in conda list output and are tracked by conda’s package management system. Converted packages can be removed with conda remove.

Common Usage Patterns#

Development Workflow#

# Set up development environment
conda create -n dev python=3.10 pip
conda activate dev

# Install your project in editable mode
conda pypi install -e .

# Install additional development dependencies
conda pypi install -e git+https://github.com/user/dev-tool.git

Building Custom Packages#

# Convert packages for offline use
conda pypi convert -d ./offline-packages httpx numpy pandas

# Create custom channel
conda index ./offline-packages

Mixed Environment Setup#

# Install scientific stack from conda, other packages from PyPI
conda install numpy scipy matplotlib
conda pypi install some-domain-specific-package

Troubleshooting#

Common Issues#

Package conversion fails

  • Check that the package is available on PyPI

  • Try --override-channels to skip conda channel checks

  • Use --verbose to see detailed error messages

Dependency conflicts

  • Use --dry-run to preview what would be installed

  • Check if conflicting packages are already installed via conda

  • Consider using --override-channels for complex dependency trees

Permission errors

  • Ensure you have write access to the target environment

  • Check that the target environment is not marked as protected (check if conda-meta/frozen exists).

Network issues

  • Verify PyPI connectivity

  • Check proxy settings if behind corporate firewall

  • Use PIP_TRUSTED_HOST for internal PyPI mirrors