# Add Python packages

> Add Python packages - Add required Python packages to agentic workflows using pyproject.toml
> dependency management.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-04-24T16:03:56.225186+00:00` (UTC).

## Primary page

- [Add Python packages](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-python-packages.html): Full documentation for this topic (HTML).

## Sections on this page

- [Add packages to your agent](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-python-packages.html#add-packages-to-your-agent): In-page section heading.
- [Agent-specific considerations](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-python-packages.html#agent-specific-considerations): In-page section heading.
- [Add runtime dependencies (Fast iteration)](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-python-packages.html#add-runtime-dependencies-fast-iteration): In-page section heading.
- [Feature considerations](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-python-packages.html#feature-considerations): In-page section heading.

## Related documentation

- [Agentic AI](https://docs.datarobot.com/en/docs/agentic-ai/index.html): Linked from this page.
- [Build](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/index.html): Linked from this page.
- [configure an internal PyPI proxy](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-install.html): Linked from this page.

## Documentation content

# Add Python packages

To add additional Python packages to your agent environment, add them to your `pyproject.toml` file using uv, a modern Python package and environment manager.

> [!WARNING] Keep existing packages
> We recommend keeping existing packages in `pyproject.toml` to ensure consistent behavior across playground and deployment environments.

> [!TIP] Fast iteration with runtime dependencies
> For rapid development, you can add dependencies using [runtime dependencies](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-python-packages.html#add-runtime-dependencies-fast-iteration) without rebuilding the Docker image. This is ideal for quick testing during development.

The typical workflow for adding packages is:

1. Add the package: uv add <PACKAGE_NAME>
2. Test locally: dr run dev or task dev (runs the development server)
3. Build Docker image: dr task agent:build-docker-context (if using custom Docker image)
4. Deploy: Use your deployment pipeline

> [!NOTE] Automatic synchronization
> During `dr run deploy`, `dr run deploy-dev`, or `dr run dev`, the `pyproject.toml` file is automatically synchronized with the agentic workflow code. Package installation is auto-synchronized with `uv` by default. You don't need to manually update the `pyproject.toml` file in these directories.

## Add packages to your agent

1. Navigate to your agent directory and use uv to add the new package:

```
cd agent
uv add <PACKAGE_NAME>
```

For example, to add the `requests` package:

```
uv add requests
```

You can also specify version constraints:

```
uv add "requests>=2.32.0"
```

1. Create a custom execution environment to test your agent in the playground:
2. Open the.envfile.
3. SetDATAROBOT_DEFAULT_EXECUTION_ENVIRONMENT=to empty or delete the line completely.
4. Optional: If you need to test with a custom Docker image, first create the docker context:

```
# Create docker_context directory if needed
dr task agent:create-docker-context

# Then build and test the Docker image
cd agent/docker_context
docker build -f Dockerfile . -t docker_context_test
```

After completing these steps, when you run `dr run dev`, `dr run deploy-dev`, or `dr run deploy`, the new environment will be automatically built the first time. Subsequent builds will use the cached environment if the requirements have not changed. The new environment will be automatically linked and used for all your agent components, models, and deployments.

You can manually test building your agent image by running the following command, ensuring the new dependency is defined successfully:

```
dr task agent:build-docker-context
```

> [!NOTE] docker_context is optional
> The `docker_context` directory is no longer included by default. If you need to build a custom Docker image, first create the docker context using `dr task agent:create-docker-context`. This command downloads the necessary Docker files and creates the `docker_context` directory in your agent folder. The `dr task agent:build-docker-context` command will then copy the updated `pyproject.toml` to the `docker_context/` directory, build the Docker image with the new dependencies, and save the image.

> [!WARNING] Don't remove requirements
> Don't remove any packages from the `pyproject.toml` file unless you are certain they aren't needed. Removing packages may lead to unexpected behavior with playground or deployment interactions, even if the local execution environment works correctly.

## Agent-specific considerations

Different agent types may have different dependency management approaches:

| Agent Type | Dependency Management Approach |
| --- | --- |
| agent_generic_base | Uses pyproject.toml. |
| agent_llamaindex | Uses pyproject.toml with auto-generated requirements.in and requirements.txt files. |
| agent_crewai | Uses pyproject.toml. |
| agent_langgraph | Uses pyproject.toml. |
| agent_nat | Uses pyproject.toml. |

For all agent types, the recommended approach is to use `uv add <PACKAGE_NAME>` to modify the `pyproject.toml` file, which will automatically handle dependency resolution and version constraints.

The `pyproject.toml` file serves as the single source of truth for all dependencies, and the build process automatically handles the Docker environment setup.

## Add runtime dependencies (Fast iteration)

For rapid development and testing, add dependencies at runtime without rebuilding the Docker image. Dependencies added to the `extras` group in your `pyproject.toml` file will be installed when the prompt is first executed in the Playground or when the deployment starts. Runtime dependencies are ideal for:

- Quick iteration during development
- Testing new packages without rebuilding images
- Adding lightweight dependencies that don't require compilation

Add runtime dependencies directly using `uv`:

```
cd agent
uv add --active --no-upgrade --group extras "chromadb>=1.1.1"
```

> [!TIP] Use --no-upgrade flag
> The `--no-upgrade` flag is crucial to minimize the time required to install extra dependencies. It ensures that only new dependencies are added without upgrading existing ones, which helps to keep the runtime installation fast and minimize differences from the execution environment.

### Feature considerations

Runtime dependencies have several important limitations to consider:

- Internet access required: Since extra dependencies are installed at runtime,internet access is required. In restricted network environments, you mustconfigure an internal PyPI proxyor build custom execution environments to include custom dependencies.
- Installation complexity: If a dependency has a sophisticated installation process (for example, compilation of C bindings, setting up cache, or custom build steps), the runtime installation may fail due to restrictions in the execution environment. In such cases, building a custom execution environment is the only option.
- Security considerations: Using runtime dependencies makes it possible to quickly fix CVE issues in runtime by upgrading library versions directly in the agent. However, it's also possible to introduce vulnerabilities by downgrading libraries to vulnerable versions, even if the execution environment doesn't have those vulnerabilities. You must update both execution environments andpyproject.toml/uv.lockfiles in your agents to ensure vulnerabilities are properly fixed.

Consider the following best practices for using runtime dependencies:

- Use runtime dependencies for development and testing.
- For production deployments, consider building custom execution environments with all required dependencies installed.
- Keep the pyproject.toml file synchronized with all dependencies to ensure consistency across environments.
- Minimize upgrades by using the --no-upgrade flag to keep installation times fast.