---
title: register_application (Python agent API)
source: https://docs.newrelic.com/docs/apm/agents/python-agent/python-agent-api/registerapplication-python-agent-api
---

## Syntax

```py
newrelic.agent.register_application(name=None, timeout=None)
```

Registers the Python agent immediately. Used for manual initialization of agent.

## Description

When [`initialize`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/initialize) is called, it sets up the Python agent but does not register the agent with the [collector](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#collector). This call registers the agent with the collector.

This is primarily used for non-web [background transactions](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/background_task) instrumented using the API. When used with non-web transactions, call `register_application` as soon as possible after the `initialize` call.

For web transactions, the agent normally registers automatically when the first web request or background task occurs the agent receives its [server-side configuration](https://docs.newrelic.com/docs/agents/manage-apm-agents/configuration/configure-agent#ssc) from the collector. Because registration can take a second or so, details are usually lost from the earliest transactions. You can collect all of this data by forcing registration with `register_application`, though doing so means your app may wait for registration to complete before serving any web requests or running background tasks.

If the script itself runs the WSGI server, call `register_application` from the main program thread in the main script file. If you use Apache/mod_wsgi or uWSGI, make the call from the WSGI script file and place the call immediately after `initialize`**.**

This call returns the application object, in the same way [`application`](https://docs.newrelic.com/docs/agents/python-agent/python-agent-api/application) does. The application object is used to get a reference to the current agent-monitored application and is used by some Python agent API calls.

### Avoid calling during global import lock [#globl-lock]

Do not call `register_application` with a non-zero timeout when the Python global import lock will be held. In other words, do not call it in a module file at global scope while the module is being imported. Doing so may result in a temporary deadlock with the background thread created by this call (the deadlock will not be broken until the timeout expires).

Note that many WSGI servers import the module containing the WSGI application via the standard Python module import mechanisms. In those cases, the global import lock will be held and the deadlock problem described above can occur.

For Gunicorn: The deadlock issue just described can also occur when using Gunicorn. The problem is that triggering `register_application` from the WSGI module is not safe, because it preloads the module into the parent process. To use `register_application` with Gunicorn (with or without a timeout) call it from a `post_fork()` callback. This is not a problem with Apache/mod_wsgi, since those tools have been designed not to do this, so it's safe to create background threads when the WSGI application is loaded.

### Call after worker process fork [#worker-processes]

If you're recording transactions in child worker process, do not call `register_application` in the parent process before the child worker processes are forked. If you were to call `register_application` before forking, the background agent thread would be killed when the process is forked. Since the parent thread is reporting data to the collector, the agent will not be able to report data from child worker process.

## Parameters

| Parameter                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` _string_            | Optional. The application name. If set, this overrides the application name set in the Python agent's configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `timeout` _int_ or _float_ | The number of seconds that the app will try to register before giving up and sending a response; meaning this line will block until New Relic starts up or the timeout is exceeded. A value of `0` means that the application will not wait for registration before it serves requests. The default is `0`. If running a web application, setting this value isn't recommended as it'll block and delay the application  while New Relic starts up. If instrumenting a single program run or task, where the process runs once and immediately terminates, setting this is recommended as otherwise New Relic will not be started in time to capture the information. This value gives the maximum number of seconds the caller should be blocked before control is returned and the caller allowed to proceed. With no value, the call uses the globally configured [`startup_timeout`](https://docs.newrelic.com/docs/agents/python-agent/installation-configuration/python-agent-configuration#startup-timeout) setting in the agent configuration, which is `0.0` by default. |

## Return values

Returns an application object that can be used by some other Python agent API calls.

## Examples

### Registering a background task [#register-example]

This example registers a non-web background task with a long timeout. Typically, for a web application, you would have a very short time-out (the default is 0), but you might set a longer timeout for a infrequent non-web task to ensure initialization and registration take place.

```py
import newrelic.agent

newrelic.agent.initialize('newrelic.ini')
newrelic.agent.register_application(timeout=10.0)

@newrelic.agent.background_task()
def main():
    pass

if __name__ == '__main__':
    main()
```