PipMaster

https://parisneo.github.io/pipmaster/
Admin
PipMaster is a Python library providing a programmatic API to install, update, check, uninstall, and...
Tokens:32,725
Snippets:330
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install with version specifiers

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/installing.rst.txt

Shows how to install packages with version specifiers using pm.install and pm.install_multiple. Includes examples for >=, <, ==, and ~= specifiers.

```python
pm.install("requests>=2.25.0")
pm.install("django<4.0")
pm.install_multiple(["pandas==1.5.3", "numpy~=1.23.0"]) # Compatible release
```

--------------------------------

### Install with custom index URL

Source: https://parisneo.github.io/pipmaster/user_guide/installing.html

Shows how to pass an index_url to install, install_multiple, and install_requirements. The example uses a PyTorch index URL for CUDA 12.1.

```python
pytorch_index = "https://download.pytorch.org/whl/cu121" # Example
pm.install("torch", index_url=pytorch_index)
pm.install_multiple(["torchvision", "torchaudio"], index_url=pytorch_index)
pm.install_requirements("torch_reqs.txt", index_url=pytorch_index)

```

--------------------------------

### Install in editable mode

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/installing.rst.txt

Demonstrates using pm.install_edit to install a local package in editable mode. The example is commented out.

```python
# Assuming you have a package source in a directory named 'my_local_project'
# pm.install_edit("./my_local_project") # Uncomment to run
```

--------------------------------

### Install based on version requirements

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/installing.rst.txt

Demonstrates pm.install_if_missing to install a package only if missing or if the installed version doesn't meet the specified requirement. Includes examples for version specifiers and always_update.

```python
# Ensure numpy is at least version 1.21.0
pm.install_if_missing("numpy", version_specifier=">=1.21.0")

# Ensure requests is exactly version 2.28.1
pm.install_if_missing("requests", version_specifier="==2.28.1")

# Ensure requests is installed, and update to latest if already present
pm.install_if_missing("requests", always_update=True)
```

--------------------------------

### Install and uninstall packages with uv manager

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/uv.rst.txt

Install multiple packages with install_multiple and uninstall a package with uninstall, both with verbose output. This example assumes an environment has already been created and targeted.

```python
# ... (previous code for creating the environment) ...
try:
    uv_manager = get_uv_manager()
    if uv_manager.create_env(path=env_path):
        print("Environment created. Now installing packages...")
        
        # Install multiple packages
        uv_manager.install_multiple(["numpy", "pandas"], verbose=True)

        # You can now use this environment to run code
        # (e.g., using subprocess with uv_manager.python_executable)

        print("\nUninstalling pandas...")
        uv_manager.uninstall("pandas", verbose=True)

# ... (error handling and cleanup) ...
```

--------------------------------

### Example Async Usage with async_install and run_in_executor

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/core_concepts.rst.txt

Demonstrates asynchronous usage of pipmaster. It installs 'httpx' using async_install, then runs the synchronous is_installed check in an asyncio executor to avoid blocking. The example includes a commented-out asyncio.run call to execute the async function.

```python
import pipmaster as pm
import asyncio

async def manage_packages_async():
    print("Async: Installing httpx...")
    await pm.async_install("httpx")

    print("Async: Checking requests (sync check in executor)...")
    loop = asyncio.get_running_loop()
    # Run the synchronous is_installed function in the default executor
    req_installed = await loop.run_in_executor(None, pm.is_installed, "requests")
    print(f"Async: Is requests installed? {req_installed}")

# To run this:
# asyncio.run(manage_packages_async())
```

--------------------------------

### Install with custom index URL

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/installing.rst.txt

Shows how to pass a custom index_url to various installation functions, including install, install_multiple, and install_requirements.

```python
pytorch_index = "https://download.pytorch.org/whl/cu121" # Example
pm.install("torch", index_url=pytorch_index)
pm.install_multiple(["torchvision", "torchaudio"], index_url=pytorch_index)
pm.install_requirements("torch_reqs.txt", index_url=pytorch_index)
```

--------------------------------

### Install and uninstall packages with uv

Source: https://parisneo.github.io/pipmaster/user_guide/uv.html

Install multiple packages and uninstall one using the uv manager. The example shows creating an environment, installing numpy and pandas, then uninstalling pandas.

```python
# ... (previous code for creating the environment) ...
try:
    uv_manager = get_uv_manager()
    if uv_manager.create_env(path=env_path):
        print("Environment created. Now installing packages...")

        # Install multiple packages
        uv_manager.install_multiple(["numpy", "pandas"], verbose=True)

        # You can now use this environment to run code
        # (e.g., using subprocess with uv_manager.python_executable)

        print("\nUninstalling pandas...")
        uv_manager.uninstall("pandas", verbose=True)

# ... (error handling and cleanup) ...

```

--------------------------------

### Install from requirements file

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/installing.rst.txt

Shows how to create a requirements.txt file and then install all packages listed in it using pm.install_requirements.

```python
# Create the file first for the example
with open("requirements.txt", "w") as f:
    f.write("click>=8.0\nflask\nrich ; python_version >= '3.6'\n")

pm.install_requirements("requirements.txt")
```

--------------------------------

### AsyncPackageManager.install()

Source: https://parisneo.github.io/pipmaster/api/async.html

Asynchronously installs a single package with visual feedback.

```APIDOC
## [ASYNC] AsyncPackageManager.install()

### Description
Asynchronously installs a single package with visual feedback.

### Method
Async method

### Endpoint
AsyncPackageManager.install()

### Parameters
#### Method Parameters
- **package** (str) - Required - The name of the package to install.
- **index_url** (str | None) - Optional - The index URL to use for installation.
- **force_reinstall** (bool) - Optional - Whether to force reinstallation.
- **upgrade** (bool) - Optional - Whether to upgrade the package.
- **extra_args** (List[str] | None) - Optional - Additional arguments to pass to pip.
- **dry_run** (bool) - Optional - If True, only simulate the installation.
- **verbose** (bool) - Optional - If True, enable verbose output.

### Returns
- **bool** - True if the installation succeeds, False otherwise.

### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Async install method

Source: https://parisneo.github.io/pipmaster/_modules/pipmaster/async_package_manager.html

Asynchronously installs a package with optional upgrade, force-reinstall, index URL, and extra args. Provides visual feedback via a spinner or logs based on verbose/dry_run flags. Returns True on success, False on failure.

```python
    async def install(
        self,
        package: str,
        index_url: Optional[str] = None,
        force_reinstall: bool = False,
        upgrade: bool = True,
        extra_args: Optional[List[str]] = None,
        dry_run: bool = False,
        verbose: bool = False,
    ) -> bool:
        """Async install with visual feedback."""
        command = ["install"]
        if upgrade: command.append("--upgrade")
        if force_reinstall: command.append("--force-reinstall")
        if index_url: command.extend(["--index-url", index_url])
        if extra_args: command.extend(extra_args)
        command.append(package)

        action_emoji = EMOJI['update'] if upgrade else EMOJI['install']
        action_text = "Updating" if upgrade else "Installing"
        msg = f"{action_emoji} [Async] {action_text}: {package}"

        if verbose or dry_run:
            logger.info(msg)
            success, _ = await self._run_command(command, dry_run=dry_run, verbose=verbose, capture_output=False)
            if success:
                logger.info(f"{EMOJI['sparkles']} [Async] Successfully handled: {package}")
            else:
                logger.error(f"{EMOJI['cross']} [Async] Failed to handle: {package}")
        else:
            with ASCIIColors.status(msg, spinner="dots", spinner_style="bold cyan") as status:
                success, _ = await self._run_command(command, dry_run=dry_run, verbose=verbose, capture_output=False)
                if success:
                    logger.debug(f"{EMOJI['sparkles']} [Async] Successfully handled: {package}")
                else:
                    logger.error(f"{EMOJI['cross']} [Async] Failed to handle: {package}")

        return success
```

--------------------------------

### Install a package with pm.install

Source: https://parisneo.github.io/pipmaster/_sources/getting_started.rst.txt

Use pm.install to ensure a package is installed, upgrading if already present by default. Prints success or failure messages.

```python
package_name = "requests"
print(f"Ensuring '{package_name}' is installed...")
if pm.install(package_name):
    print(f"'{package_name}' installed or already up-to-date.")
else:
    print(f"Failed to install '{package_name}'.")
```

--------------------------------

### async_install(package: str, **kwargs: Any) -> bool

Source: https://parisneo.github.io/pipmaster/_modules/pipmaster/async_package_manager.html

Asynchronously installs a single package.

```APIDOC
## [ASYNC] async_install

### Description
Asynchronously installs a single package.

### Method
ASYNC

### Endpoint
async_install

### Parameters
- **package** (str) - Required - The name of the package to install.
- **kwargs** (Any) - Optional - Additional keyword arguments passed to the underlying install method.

### Returns
- **bool** - True if installation succeeded, False otherwise.

### Example
```python
result = await async_install('requests')
```
```

--------------------------------

### Async installation with pm.async_install

Source: https://parisneo.github.io/pipmaster/_sources/getting_started.rst.txt

Asynchronously install a package using pm.async_install inside an async function. The asyncio.run call is commented out.

```python
async def install_async_package():
    pkg = "aiohttp"
    print(f"Asynchronously installing '{pkg}'...")
    if await pm.async_install(pkg):
        print(f"Async install of '{pkg}' succeeded.")
    else:
        print(f"Async install of '{pkg}' failed.")

# To run the async function:
# asyncio.run(install_async_package())
```

--------------------------------

### Synchronous progress callback example

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/async.rst.txt

Shows how to define a synchronous progress callback for pm.ensure_packages. The callback receives a dictionary with status, message, package(s), progress/total, and success keys. Use this to display progress in a console or UI when installing packages synchronously.

```python
import pipmaster as pm

def my_callback(data):
    print(f"[{data['status'].upper()}] {data['message']}")
    if 'progress' in data:
        print(f"  Progress: {data['progress']}/{data['total']}")

pm.ensure_packages(["requests", "numpy", "pandas"], 
                     progress_callback=my_callback, 
                     verbose=True)
```

--------------------------------

### Install exact version with install_version

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/installing.rst.txt

Demonstrates using pm.install_version to install a specific exact version of a package.

```python
pm.install_version("colorama", "0.4.6")
```

--------------------------------

### async_install_if_missing(package: str, **kwargs: Any) -> bool

Source: https://parisneo.github.io/pipmaster/_modules/pipmaster/async_package_manager.html

Asynchronously installs a package only if it is not already installed.

```APIDOC
## [ASYNC] async_install_if_missing

### Description
Conditionally installs a single package asynchronously, only if it is not already present.

### Method
ASYNC

### Endpoint
async_install_if_missing

### Parameters
- **package** (str) - Required - The name of the package to install if missing.
- **kwargs** (Any) - Optional - Additional keyword arguments passed to the underlying install method.

### Returns
- **bool** - True if the package is installed or already present, False otherwise.

### Example
```python
result = await async_install_if_missing('requests')
```
```

--------------------------------

### Install multiple packages if missing

Source: https://parisneo.github.io/pipmaster/_sources/getting_started.rst.txt

Install multiple packages only if they are missing, using pm.install_multiple_if_not_installed.

```python
extras = ["rich", "tqdm"] # Example utility packages
print(f"Installing missing packages from: {extras}")
if pm.install_multiple_if_not_installed(extras):
    print("Checked/installed extra utility packages.")
else:
    print("Failed to install some utility packages.")
```

--------------------------------

### Async install_if_missing method

Source: https://parisneo.github.io/pipmaster/_modules/pipmaster/async_package_manager.html

Asynchronously checks if a package needs installation and installs it if necessary. Supports version specifiers, always_update flag, and progress callbacks. Returns True if already satisfied or successfully installed, False otherwise.

```python
    async def install_if_missing(
        self,
        package: str,
        version_specifier: Optional[str] = None,
        always_update: bool = False,
        index_url: Optional[str] = None,
        extra_args: Optional[List[str]] = None,
        dry_run: bool = False,
        verbose: bool = False,
    ) -> bool:
        """Async conditional install with visual feedback."""
        loop = asyncio.get_running_loop()
        # We must pass the verbose argument as a keyword argument because run_in_executor
        # only takes *args. We use functools.partial or lambda, but here we can just
        # construct the call carefully.
        # Since _check_if_install_is_needed signature is (package, version_specifier, always_update, verbose)
        # We can pass them positionally.
        is_needed, install_target, force = await loop.run_in_executor(
            None, 
            self._sync_pm_instance._check_if_install_is_needed, 
            package, 
            version_specifier, 
            always_update, 
            verbose
        )

        if not is_needed:
            logger.debug(f"{EMOJI['check']} [Async] '{package}' already satisfied. Skipping.")
            return True

        return await self.install(
            install_target,
            index_url=index_url,
            upgrade=True,
            force_reinstall=force,
            extra_args=extra_args,
            dry_run=dry_run,
            verbose=verbose,
        )
```

--------------------------------

### AsyncPackageManager.install_multiple()

Source: https://parisneo.github.io/pipmaster/api/async.html

Asynchronously installs multiple packages with progress feedback.

```APIDOC
## [ASYNC] AsyncPackageManager.install_multiple()

### Description
Asynchronously installs multiple packages with progress feedback.

### Method
Async method

### Endpoint
AsyncPackageManager.install_multiple()

### Parameters
#### Method Parameters
- **packages** (List[str]) - Required - The list of packages to install.
- **index_url** (str | None) - Optional - The index URL to use for installation.
- **force_reinstall** (bool) - Optional - Whether to force reinstallation.
- **upgrade** (bool) - Optional - Whether to upgrade the packages.
- **extra_args** (List[str] | None) - Optional - Additional arguments to pass to pip.
- **dry_run** (bool) - Optional - If True, only simulate the installation.
- **verbose** (bool) - Optional - If True, enable verbose output.

### Returns
- **bool** - True if all installations succeed, False otherwise.

### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### AsyncPackageManager.install_if_missing()

Source: https://parisneo.github.io/pipmaster/api/async.html

Asynchronously installs a package only if it is not already installed.

```APIDOC
## [ASYNC] AsyncPackageManager.install_if_missing()

### Description
Asynchronously installs a package only if it is not already installed, with visual feedback.

### Method
Async method

### Endpoint
AsyncPackageManager.install_if_missing()

### Parameters
#### Method Parameters
- **package** (str) - Required - The name of the package to install.
- **version_specifier** (str | None) - Optional - A version specifier for the package.
- **always_update** (bool) - Optional - If True, always update the package even if installed.
- **index_url** (str | None) - Optional - The index URL to use for installation.
- **extra_args** (List[str] | None) - Optional - Additional arguments to pass to pip.
- **dry_run** (bool) - Optional - If True, only simulate the installation.
- **verbose** (bool) - Optional - If True, enable verbose output.

### Returns
- **bool** - True if the installation succeeds, False otherwise.

### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Install multiple packages with pm.install_multiple

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/installing.rst.txt

Install or upgrade multiple packages in a single pip command using pm.install_multiple. This is more efficient than installing them individually.

```python
packages_to_install = ["matplotlib", "seaborn", "plotly"]
pm.install_multiple(packages_to_install)
```

--------------------------------

### Install uv on macOS/Linux

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/uv.rst.txt

Install the uv executable on macOS/Linux using the official installer script. The uv executable must be available in the system's PATH to use the pipmaster uv backend.

```bash
# Example installation for macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# See the official uv documentation for other installation methods.
```

--------------------------------

### Install single package with pm.install

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/installing.rst.txt

Install a single package with pm.install. By default it acts like pip install --upgrade. Use upgrade=False to avoid upgrading, and force_reinstall=True to reinstall even if the latest version is present.

```python
import pipmaster as pm

# Install the latest version of 'requests', or upgrade if already installed
pm.install("requests")

# Install 'numpy' but *don't* upgrade it if it's already installed
pm.install("numpy", upgrade=False)

# Force reinstall 'pandas', even if the latest version is present
pm.install("pandas", force_reinstall=True)
```

--------------------------------

### Install package asynchronously with portable Python 3.12

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/async_versions.rst.txt

Creates an AsyncPackageManager for portable Python 3.12, installs 'rich' asynchronously, and verifies installation using run_in_executor because is_installed is synchronous. Uses the get_async_pip_manager_for_version factory.

```python
import pipmaster as pm
import asyncio

async def main():
    # Create an AsyncPackageManager that uses a portable Python 3.12
    async_pm = pm.get_async_pip_manager_for_version("3.12", "./my_portable_venv")
    
    # Install a package asynchronously in that environment
    await async_pm.install("rich", verbose=True)

    # Verify installation (run in executor because ``is_installed`` is sync)
    loop = asyncio.get_running_loop()
    installed = await loop.run_in_executor(None, async_pm.is_installed, "rich")
    print(f"'rich' installed? {installed}")

asyncio.run(main())
```

--------------------------------

### async_install_multiple(packages: List[str], **kwargs: Any) -> bool

Source: https://parisneo.github.io/pipmaster/_modules/pipmaster/async_package_manager.html

Asynchronously installs multiple packages.

```APIDOC
## [ASYNC] async_install_multiple

### Description
Installs multiple packages asynchronously.

### Method
ASYNC

### Endpoint
async_install_multiple

### Parameters
- **packages** (List[str]) - Required - List of package names to install.
- **kwargs** (Any) - Optional - Additional keyword arguments passed to the underlying install method.

### Returns
- **bool** - True if all installations succeeded, False otherwise.

### Example
```python
result = await async_install_multiple(['requests', 'flask'])
```
```

--------------------------------

### Check package installation and version

Source: https://parisneo.github.io/pipmaster/_sources/getting_started.rst.txt

Check if a package is installed and retrieve its version using pm.is_installed and pm.get_installed_version.

```python
package_to_check = "packaging" # A dependency of pipmaster
if pm.is_installed(package_to_check):
    version = pm.get_installed_version(package_to_check)
    print(f"'{package_to_check}' is installed, version: {version}")
else:
    print(f"'{package_to_check}' is not installed.")
```

--------------------------------

### Async ensure_packages method

Source: https://parisneo.github.io/pipmaster/_modules/pipmaster/async_package_manager.html

Asynchronously ensures a list of packages are installed, using a thread executor to call the synchronous check. Supports progress callbacks (sync or async) and returns True if all requirements are satisfied or installed successfully.

```python
    async def ensure_packages(
        self,
        requirements: Union[str, Dict[str, Any], List[str]],
        index_url: Optional[str] = None,
        extra_args: Optional[List[str]] = None,
        dry_run: bool = False,
        verbose: bool = False,
        progress_callback: Optional[callable] = None,
    ) -> bool:
        """Async ensure with pleasant batch feedback."""
        loop = asyncio.get_running_loop()
        
        # Define a wrapper to call async callback from sync context
        def sync_progress_wrapper(data):
            if progress_callback and asyncio.iscoroutinefunction(progress_callback):
                # Schedule the async callback on the event loop
                try:
                    loop.call_soon_threadsafe(lambda: asyncio.create_task(progress_callback(data)))
                except Exception:
                    pass
            elif progress_callback:
                progress_callback(data)
        
        packages_to_process = await loop.run_in_executor(
            None, self._sync_pm_instance._get_packages_to_process, requirements, False, verbose, sync_progress_wrapper
        )

        if not packages_to_process:
            msg = f"{EMOJI['check']} [Async] All requirements satisfied."
            logger.debug(msg)
            if progress_callback:
                if asyncio.iscoroutinefunction(progress_callback):
                    await progress_callback({"status": "complete", "message": msg, "packages": []})
                else:
                    progress_callback({"status": "complete", "message": msg, "packages": []})
            return True
```

--------------------------------

### is_installed(package_name, version_specifier=None)

Source: https://parisneo.github.io/pipmaster/user_guide/checking.html

Checks if a package is installed, optionally verifying a version specifier.

```APIDOC
## is_installed(package_name, version_specifier=None)

### Description
Determines if a package is installed in the target environment. Optionally checks if the installed version satisfies a PEP 440 version specifier.

### Parameters
- **package_name** (str) - Required - The name of the package to check.
- **version_specifier** (str) - Optional - A PEP 440 version specifier (e.g., ">=2.25.0") to check compatibility.

### Returns
- **bool** - True if the package is installed (and meets the version specifier if provided), False otherwise.

### Example
```python
import pipmaster as pm

if pm.is_installed("requests"):
    print("requests is installed.")
else:
    print("requests is NOT installed.")

# With version specifier
if pm.is_installed("requests", version_specifier=">=2.25.0"):
    print("requests >= 2.25.0 is installed.")
```
```

--------------------------------

### Get installed version with pm.get_installed_version

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/checking.rst.txt

Retrieve the version string of an installed package using pm.get_installed_version. Returns None if the package is not found. The example checks 'packaging' and prints the version or a not-found message.

```python
package_name = "packaging" # Dependency of pipmaster
version = pm.get_installed_version(package_name)

if version:
    print(f"Installed version of '{package_name}': {version}")
else:
    print(f"'{package_name}' not found.")
```

--------------------------------

### get_installed_version(package_name)

Source: https://parisneo.github.io/pipmaster/user_guide/checking.html

Gets the installed version of a package.

```APIDOC
## get_installed_version(package_name)

### Description
Retrieves the version string of an installed package. Returns None if the package is not found.

### Parameters
- **package_name** (str) - Required - The name of the package to query.

### Returns
- **str or None** - The installed version string, or None if the package is not installed.

### Example
```python
package_name = "packaging"
version = pm.get_installed_version(package_name)

if version:
    print(f"Installed version of '{package_name}': {version}")
else:
    print(f"'{package_name}' not found.")
```
```

--------------------------------

### Get uv manager with get_uv_manager

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/uv.rst.txt

Get an instance of UvPackageManager using the get_uv_manager factory function. Raises FileNotFoundError if the uv executable is not installed.

```python
from pipmaster import get_uv_manager

try:
    uv_manager = get_uv_manager()
    print("UvPackageManager created successfully.")
except FileNotFoundError as e:
    print(e)
    # Handle the case where 'uv' is not installed
```

--------------------------------

### Async install_multiple method

Source: https://parisneo.github.io/pipmaster/_modules/pipmaster/async_package_manager.html

Builds a pip install command with optional flags, runs it with or without a status spinner, and returns success. Handles empty package lists and logs batch results.

```python
    async def install_multiple(
        self,
        packages: List[str],
        index_url: Optional[str] = None,
        force_reinstall: bool = False,
        upgrade: bool = True,
        extra_args: Optional[List[str]] = None,
        dry_run: bool = False,
        verbose: bool = False,
    ) -> bool:
        """Async install batch with progress feedback."""
        if not packages: 
            return True

        msg = f"{EMOJI['rocket']} [Async] Installing batch of {len(packages)} package(s)..."

        command = ["install"]
        if upgrade: command.append("--upgrade")
        if force_reinstall: command.append("--force-reinstall")
        if index_url: command.extend(["--index-url", index_url])
        if extra_args: command.extend(extra_args)
        command.extend(packages)
        
        if verbose or dry_run:
            logger.info(msg)
            success, _ = await self._run_command(command, dry_run=dry_run, verbose=verbose, capture_output=False)
            if success:
                logger.info(f"{EMOJI['sparkles']} [Async] Batch complete: {len(packages)} package(s)")
            else:
                logger.error(f"{EMOJI['cross']} [Async] Batch failed")
        else:
            with ASCIIColors.status(msg, spinner="star", spinner_style="bold green") as status:
                success, _ = await self._run_command(command, dry_run=dry_run, verbose=verbose, capture_output=False)
                if success:
                    logger.debug(f"{EMOJI['sparkles']} [Async] Batch complete: {len(packages)} package(s)")
                else:
                    logger.error(f"{EMOJI['cross']} [Async] Batch failed")

        return success
```

--------------------------------

### Get detailed package info with pm.get_package_info

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/checking.rst.txt

Retrieve the output of 'pip show <package_name>' for a package using pm.get_package_info. The example gets info about pipmaster itself and prints it or a message if not found.

```python
info = pm.get_package_info("pipmaster") # Get info about pipmaster itself
if info:
    print("\n--- pipmaster info ---")
    print(info)
    print("----------------------\n")
else:
    print("Could not get info for pipmaster (is it installed?).")
```

--------------------------------

### Async batch install with progress callback

Source: https://parisneo.github.io/pipmaster/_modules/pipmaster/async_package_manager.html

Processes a list of packages, logs progress, invokes install_multiple, and reports completion or failure via a progress callback. Supports both async and sync callbacks.

```python
        pkg_list_str = "', '".join(packages_to_process)
        if verbose:
            logger.info(f"{EMOJI['package']} [Async] Processing {len(packages_to_process)} packages: '{pkg_list_str}'")
        else:
            logger.debug(f"{EMOJI['package']} [Async] Processing {len(packages_to_process)} packages.")
        
        if progress_callback:
            data = {
                "status": "processing",
                "message": f"Installing {len(packages_to_process)} package(s)",
                "packages": packages_to_process,
                "count": len(packages_to_process)
            }
            if asyncio.iscoroutinefunction(progress_callback):
                await progress_callback(data)
            else:
                progress_callback(data)

        result = await self.install_multiple(
            packages=packages_to_process,
            index_url=index_url,
            force_reinstall=False,
            upgrade=True,
            extra_args=extra_args,
            dry_run=dry_run,
            verbose=verbose,
        )
        
        if progress_callback:
            data = {
                "status": "complete" if result else "failed",
                "message": "Installation complete" if result else "Installation failed",
                "packages": packages_to_process,
                "success": result
            }
            if asyncio.iscoroutinefunction(progress_callback):
                await progress_callback(data)
            else:
                progress_callback(data)
        
        return result
```

--------------------------------

### Check if a package is installed with pm.is_installed

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/checking.rst.txt

Use pm.is_installed to determine if a package exists in the target environment. The example checks for 'requests' and a non-existent package, printing appropriate messages.

```python
import pipmaster as pm

if pm.is_installed("requests"):
    print("requests is installed.")
else:
    print("requests is NOT installed.")

# Check a non-existent package
if not pm.is_installed("no_such_package_exists_i_hope"):
    print("Confirmed: The non-existent package is not installed.")
```

--------------------------------

### Non-blocking package check with asyncio.run_in_executor

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/async.rst.txt

Checks if a package is installed without blocking the event loop by running the synchronous pipmaster functions in the default thread pool executor. Use this when you need to call pipmaster from async code without freezing the loop. The example checks 'numpy' and prints its version if installed.

```python
       print(f"Checking '{package_name}' without blocking...")
       # Run the synchronous pm.is_installed in the default thread pool executor
       installed = await loop.run_in_executor(None, pm.is_installed, package_name)

       if installed:
           # Run get_installed_version in the executor as well
           version = await loop.run_in_executor(None, pm.get_installed_version, package_name)
           print(f"'{package_name}' is installed (Version: {version})")
       else:
           print(f"'{package_name}' is not installed.")

   # To run:
   # asyncio.run(check_package_non_blocking("numpy"))
```

--------------------------------

### Async get_package_info method

Source: https://parisneo.github.io/pipmaster/_modules/pipmaster/async_package_manager.html

Asynchronously retrieves package information using the 'show' command. Returns the output string on success, otherwise None.

```python
    async def get_package_info(self, package_name: str) -> Optional[str]:
        """Async package info retrieval."""
        success, output = await self._run_command(
            ["show", package_name], capture_output=True
        )
        return output if success else None
```

--------------------------------

### Run synchronous pipmaster checks in async executor

Source: https://parisneo.github.io/pipmaster/user_guide/async.html

Use asyncio.get_running_loop().run_in_executor to run pm.is_installed and pm.get_installed_version without blocking the event loop. The example checks a package and prints its version if installed.

```python
import pipmaster as pm
import asyncio

async def check_package_non_blocking(package_name):
    loop = asyncio.get_running_loop()

    print(f"Checking '{package_name}' without blocking...")
    # Run the synchronous pm.is_installed in the default thread pool executor
    installed = await loop.run_in_executor(None, pm.is_installed, package_name)

    if installed:
        # Run get_installed_version in the executor as well
        version = await loop.run_in_executor(None, pm.get_installed_version, package_name)
        print(f"'{package_name}' is installed (Version: {version})")
    else:
        print(f"'{package_name}' is not installed.")

# To run:
# asyncio.run(check_package_non_blocking("numpy"))
```

--------------------------------

### Check version compatibility with pm.is_version_compatible

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/checking.rst.txt

Use pm.is_version_compatible to check if the installed version meets a PEP 440 specifier. The example assumes 'packaging' version 23.2 and tests multiple specifiers, including a non-existent package returning False.

```python
# Assume 'packaging' version 23.2 is installed for these examples

# Check if >= 21.0 (Should be True)
if pm.is_version_compatible("packaging", ">=21.0"):
    print("packaging version is >= 21.0")

# Check if == 23.2 (Should be True)
if pm.is_version_compatible("packaging", "==23.2"):
    print("packaging version is exactly 23.2")

# Check if < 23.0 (Should be False)
if not pm.is_version_compatible("packaging", "<23.0"):
    print("packaging version is NOT < 23.0")

# Check against a non-existent package (will be False)
if not pm.is_version_compatible("nonexistent_pkg", ">=1.0"):
    print("Compatibility check returns False for non-existent packages.")
```

--------------------------------

### Build documentation

Source: https://parisneo.github.io/pipmaster/contributing.html

Build the documentation locally to check for errors.

```bash
sphinx-build -b html docs docs/_build/html
```

--------------------------------

### Targeting a Different Python Environment with PackageManager and get_pip_manager

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/core_concepts.rst.txt

Shows how to create a PackageManager instance targeting the current environment by default, and how to target a specific virtual environment by providing its Python executable path. The example prints the target executable and installs 'requests' into the venv, catching FileNotFoundError if the path is invalid.

```python
import pipmaster as pm
import sys

# Default manager targets the current environment
default_pm = pm.PackageManager()
print(f"Default targets: {default_pm.target_python_executable}")
# is equivalent to:
current_pm = pm.PackageManager(python_executable=sys.executable)
print(f"Current targets: {current_pm.target_python_executable}")

# Target a specific venv (replace with a valid path on your system)
# venv_python_path = "/path/to/myenv/bin/python" # Linux/macOS
venv_python_path = "C:/path/to/myenv/Scripts/python.exe" # Windows

try:
    # Get a manager instance specifically for this environment
    venv_pm = pm.get_pip_manager(python_executable=venv_python_path)
    print(f"Targeting venv: {venv_pm.target_python_executable}")

    # Operations using venv_pm will affect the other environment
    venv_pm.install("requests") # Installs requests into the venv

except FileNotFoundError:
    print(f"Warning: Path not found for target environment: {venv_python_path}")
```

--------------------------------

### Set up development environment (bash)

Source: https://parisneo.github.io/pipmaster/_sources/contributing.rst.txt

Creates a virtual environment, activates it, and installs pipmaster in editable mode with dev dependencies. Use this before making changes. The activation command differs on Windows (commented out).

```bash
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows
pip install -e ".[dev]" # Install in editable mode with dev dependencies
```

--------------------------------

### Conditional Git install with ensure_packages

Source: https://parisneo.github.io/pipmaster/_sources/user_guide/installing.rst.txt

Define a conditional Git installation rule for ensure_packages. The rule installs from a Git repository only if the installed version does not meet the condition.

```python
# This rule means: "We need diffusers>=0.25.0. 
# If not met, install from the main branch on GitHub."
conditional_req = {
    "name": "diffusers",
    "vcs": "git+https://github.com/huggingface/diffusers.git",
    "condition": ">=0.25.0"
}

# This will trigger the git install if an older version is present
pm.ensure_packages([conditional_req], verbose=True)
```

--------------------------------

### Installing Specific Versions with Version Specifiers

Source: https://parisneo.github.io/pipmaster/user_guide/installing.html

Specify versions directly in the package string (PEP 508 format) for pm.install() or pm.install_multiple(). Use pm.install_version() for an exact version.

```python
# Using install with version specifiers
pm.install("requests>=2.25.0")
pm.install("django<4.0")
pm.install_multiple(["pandas==1.5.3", "numpy~=1.23.0"]) # Compatible release

# Using install_version for an exact version
pm.install_version("colorama", "0.4.6")
```

--------------------------------

### Default behavior: install and check version in current environment

Source: https://parisneo.github.io/pipmaster/user_guide/environments.html

Shows how pipmaster functions operate on the current Python environment (sys.executable) when no environment is specified. Installs 'requests' and prints the interpreter path and installed version.

```python
import pipmaster as pm
import sys

# These commands affect the current environment
pm.install("requests")
print(f"Running in: {sys.executable}")
print(f"Requests version: {pm.get_installed_version('requests')}")

```

--------------------------------

### Create a virtual environment with uv

Source: https://parisneo.github.io/pipmaster/user_guide/uv.html

Create a new virtual environment using the uv manager. The example removes an existing environment, creates a new one, and prints the targeted Python executable.

```python
import os
import shutil
from pipmaster import get_uv_manager

env_path = "./my_uv_env"

if os.path.exists(env_path):
    shutil.rmtree(env_path)

try:
    uv_manager = get_uv_manager()

    print(f"Creating uv environment at: {env_path}")
    if uv_manager.create_env(path=env_path):
        print("Environment created successfully.")
        # The manager now targets this new environment for subsequent calls
        print(f"Manager now targets Python: {uv_manager.python_executable}")
    else:
        print("Failed to create environment.")

except FileNotFoundError:
    print("Skipping example: 'uv' executable not found in PATH.")
finally:
    if os.path.exists(env_path):
        shutil.rmtree(env_path)

```
Tokens:
Raw